אפשרויות API של חברת ימות המשיח

[נועם חיון]

הורדת קובץ

הפקודה היא: DownloadFile

---

פרמטרים נדרשים

פרמטר	תיאור	הערות
token	טוקן	חובה
path	שם הקובץ להורדה	יפורט בהמשך איך לציין נתיב לכל קובץ

---

מאפייני תגובת השרת

• אם הקובץ קיים → התגובה תכיל את תוכן הקובץ עצמו (binary).
• אם הקובץ לא קיים או התרחשה שגיאה → תוחזר תשובת HTTP 404 Not Found.

שים לב: תגובה זו אינה JSON בשונה מרוב הקריאות האחרות בממשק.

---

[נועם חיון]

העלאת קובץ

הפקודה היא: UploadFile

---

מתודת פניה

יש לפנות ב־HTTP POST בפורמט multipart/form-data.

שים לב: ניתן להעלות קובץ בודד בכל פנייה.
מגבלת גודל קובץ: 50MB (נכון ל־28/09/2022). בקבצים גדולים יותר יש לבצע פיצול (ראו להלן).

---

פרמטרים נדרשים

פרמטר	תיאור	הערות
token	טוקן	חובה
path	נתיב להעלאה	חובה. לדוגמה: ivr2:5/000.wav
convertAudio	המרת הקובץ	בוליאני (1/0). אם =1 הקובץ יומר ל־WAV לטלפוניה
autoNumbering	מספור אוטומטי לקבצי שמע	true/false. במקרה זה path יצביע על תיקייה בלבד
tts	קובץ TTS	1/0. חובה לציין במספור אוטומטי עבור קובצי TTS

---

פיצול קובץ לחלקים

שלב א’ – העלאת חלקים

פרמטר	תיאור	דוגמה
qquuid	מזהה פעולה ייחודי (UUID)	2017390a-60cf-44ea-822f-27017c13de69
qqpartindex	אינדקס חלק	1
qqpartbyteoffset	כמה בייטים הועלו עד כה	4000000
qqchunksize	גודל החלק הנוכחי בבייטים	4000000
qqtotalparts	סה"כ חלקים (כולל אינדקס 0 האחרון)	8
qqtotalfilesize	גודל כולל של הקובץ בבייטים	29863882
qqfilename	שם הקובץ המקורי	בוקר טוב.mp3
qqfile	מקטע הקובץ הנוכחי	(קובץ)
uploader	מחלקת העלאה	yemot-admin

שלב ב’ – סיום העלאה

פנייה אל: UploadFile?done

פרמטרים שיש לשלוח:

פרמטר	תיאור	דוגמה
token	טוקן	כנ"ל
path	נתיב	כנ"ל
convertAudio	המרת אודיו	כנ"ל
autoNumbering	מספור אוטומטי	כנ"ל
tts	קובץ TTS	כנ"ל
qquuid	מזהה פעולה UUID	2017390a-60cf-44ea-822f-27017c13de69
qqfilename	שם קובץ מקורי	בוקר טוב.mp3
qqtotalfilesize	גודל כולל	29863882
qqtotalparts	סה"כ חלקים	8

---

תגובת השרת

מאפיין	סוג	הסבר
path	string	נתיב הקובץ שהועלה
size	long	גודל הקובץ בבייטים

אם convertAudio=1, יוחזרו גם:

מאפיין	סוג	הסבר
convertedSize	long	גודל קובץ WAV לאחר ההמרה
duration	double	משך האודיו בשניות

---

הודעות שגיאה אפשריות

messageCode	message	הסבר
105	System error	שגיאה כללית
107	File upload expected	לא נמצא קובץ להעלאה
108	Only single upload per request	הועלה יותר מקובץ אחד
109	path is required	דרוש נתיב
110	path is invalid	הנתיב אינו חוקי

---

כלי בדיקה

לטופס בדיקת העלאות HTTP:
https://www.call2all.co.il/ym/api_upload_test.php

[נועם חיון]

קבלת רשימת שיחות הפעילות במערכת

הפקודה היא: GetIncomingCalls

---

הפרמטרים הנדרשים:

פרמטר	תיאור / הערות
token	טוקן

---

מאפייני תגובת השרת:

מאפיין	סוג	הסבר
calls	array	מערך אובייקטים (ראה “תבנית אובייקט שיחה” להלן)
callsCount	int	מספר כולל של שיחות במערכת

---

תבנית אובייקט שיחה

מאפיין	ערך
did	מספר מחוייג
callerIdNum	מספר מחייג (כולל ערכים של ID val_name במידה וקיים במערכת)
duration	משך זמן שיחה – בשניות
transferFrom	האם השיחה הועברה ממערכת אחרת. אם כן יופיע הערך “מועבר”, אם לא – יופיע הערך null
id	מזהה ייחודי לאורך השיחה
path	מספר שלוחה (כולל תיאור שלוחה ומספר קובץ במידה וקיים)

[נועם חיון]

העברת יחידות

העברת יחידות למערכת אחרת

הפקודה היא: TransferUnits

---

הפרמטרים הנדרשים:

פרמטר	תיאור / הערות
token	טוקן
destination	מספר מערכת להעברה
amount	כמות יחידות להעברה

---

מאפייני תגובת השרת במקרה שהעברה בוצעה בהצלחה:

מאפיין	סוג	ערך
destination	string	מערכת היעד אליה בוצעה ההעברה
amount	double	הסכום שהועבר
newBalance	double	יתרת היחידות במערכת המקור לאחר ביצוע ההעברה

---

במקרה של שגיאה בביצוע ההעברה:

messageCode	message	הסבר
111	Bad destination	יעד להעברה לא חוקי: המערכת אינה קיימת או שאינה מורשית לקבל יחידות ממערכת זו
112	Bad amount	סכום היחידות להעברה אינו חוקי
113	Not enough balance	יתרת היחידות שבמערכת אינה מאפשרת את ביצוע ההעברה

[נועם חיון]

קבלת רשימת חיובי יחידות

היסטוריה של תנועת יחידות במערכת (כולל דוחות קמפיינים שהסתיימו)

הפקודה היא: GetTransactions

---

הפרמטרים הנדרשים:

פרמטר	תיאור	הערות
token	טוקן	חובה
from	מאיזה תנועה להציג	רשות
limit	מספר מרבי של תנועות שיש לכלול	רשות
filter	סינון תוצאות לפי סוג פעולה	campaigns עבור חיובי קמפיינים

---

מאפייני תגובת השרת:

מאפיין	סוג	ערך
transactions	array	מערך אובייקטים (ראה “תבנית אובייקט תנועה” להלן)
totalCount	int	מספר כולל של תנועת יחידות

---

תבנית אובייקט תנועה

מאפיין	סוג	ערך
id	int	מזהה תנועה ייחודי
transactionTime	string	תאריך ושעה (פורמט: yyyy-MM-dd HH:mm:ss)
amount	double	סכום היחידות
description	string	תיאור העסקה (ראה מילות מפתח מיוחדות להלן)
who	string	בוצע על ידי: <br>1) כתובת IP אם דרך אתר האינטרנט. <br>2) מספר טלפון אם דרך הטלפון. <br>3) ADMIN אם ע״י שירות הלקוחות. <br>4) TRANSFER בהעברת יחידות. <br>5) expire במקרה של פג תוקף.
newBalance	double	כמות יחידות מחודשת לאחר התנועה
expireDate	string	תאריך תפוגה חדש (אם קיים) בפורמט yyyy-MM-dd, אחרת null
campaignId	string	מזהה קמפיין אם התנועה היא הפעלת קמפיין (משמש להורדת דוח), אחרת null

---

מילות מפתח מיוחדות למאפיין description

ניתן להשתמש בהן כדי לזהות סוגי פעולות:

תיאור המתחיל ב	פירושו
Start-	חיוב עבור הפעלת קמפיין
transfer to	חיוב עבור העברת יחידות למערכת אחרת
transfer from	יחידות שנוספו בהעברה ממערכת אחרת
Units expired	פג תוקף היחידות

[נועם חיון]

עדכון פרטי משתמש

הערה: הפקודה מוחקת את פרטי המשתמש המעודכנים במערכת.

הפקודה היא: SetCustomerDetails

---

הפרמטרים הנדרשים:

פרמטר	תיאור
token	טוקן (פרמטר חובה)
name	שם לקוח
email	כתובת דוא"ל
organization	שם ארגון
contactName	שם איש קשר
phones	טלפון
invoiceName	חשבונית על שם
invoiceAddress	כתובת למשלוח חשבונית
fax	פקס
accessPassword	סיסמת גישה
recordPassword	סיסמת הקלטות

---

אין מאפיינים מיוחדים בתגובת השרת

[נועם חיון]

שינוי סיסמת ניהול

הפקודה היא: SetPassword

---

הפרמטרים הנדרשים:

פרמטר	תיאור / הערות
token	טוקן
password	סיסמת הניהול הנוכחית
newPassword	סיסמה חדשה

---

אין מאפיינים מיוחדים בתגובת השרת

[נועם חיון]

קבלת פרטי המערכת

הפקודה היא: GetSession

---

הפרמטרים הנדרשים:

פרמטר	תיאור / הערות
token	טוקן

---

מאפייני תגובת השרת:

מאפיין	סוג	ערך
name		שם לקוח
unitsExpireDate	string	תאריך תפוגה של היחידות
email		כתובת אימייל
organization		שם ארגון
contactName		שם איש קשר
phones		טלפון
invoiceName		חשבונית על שם
invoiceAddress		כתובת למשלוח חשבונית
fax		פקס
accessPassword		סיסמת גישה למערכת
units	double	כמות היחידות שבמערכת
recordPassword		סיסמת הקלטות
creditFile		שם משווק
username	string	מספר המערכת

[נועם חיון]

התנתקות

מחיקת הטוקן שהתקבל בהתחברות

הפקודה היא: Logout

---

הפרמטרים הנדרשים:

פרמטר	תיאור / הערות
token	טוקן

---

אין מאפיינים מיוחדים בתגובת השרת

[נועם חיון]

התחברות

הסבר: בכל הבקשות שנשלחות לשרת יש צורך בפרמטר token שמשמש כנקודת התחברות למערכת.
כאשר שולחים פקודת Login תקינה, תקבלו בחזרה פרמטר token שאת הערך שלו עליכם לציין כשאתם שולחים כל פקודת API.
ראה להלן דרך נוספת.

הפקודה היא: Login

---

הפרמטרים הנדרשים:

פרמטר	תיאור / הערות
username	מספר מערכת
password	סיסמת ניהול של המערכת

---

מאפייני תגובת השרת:

מאפיין	ערך	הערה
token	טוקן	הטוקן שיחזור יופיע לאחר 30 דקות אם לא תבוצע שיחת API עם הטוקן. כלומר כל עוד הטוקן תקף יש להשתמש בו ולהימנע מבקשת התחברות נוספת.

---

שימו לב:

אין צורך נוספת ליצירת טוקן ללא בקשת Login.
כאשר שולחים כל פקודת API, לרבות פקודת token, יש לכתוב בצורה הבאה (פורמט username:password):

${url}<WebServiceName>?token=${username}:${password}

[נועם חיון]

הסיסמה היא (copy:123456)

[נועם חיון]

התחברות

הסבר: בכל הבקשות הנשלחות לשרת יש צורך בפרמטר token שמשמש כקוד התחברות למערכת
כאשר תשלחו פקודת Login תקינה, תקבלו בחזרה פרמטר token שאת הערך שלו עליכם לציין כשאתם שולחים כל פקודת API.
ראה להלן דרך נוספת

הפקודה היא -Login

הפרמטרים הנדרשים:

פרמטר תיאור / הערות
username מספר מערכת
password סיסמת הניהול של המערכת
מאפייני תגובת השרת:

מאפיין ערך הערה
token טוקן הטוקן שנוצר יפוג לאחר 30 דקות אם לא תתבצע שיחת API עם הטוקן. כמו כן, כל עוד הטוקן תקף יש להשתמש בו ולהימנע מבקשת התחברות נוספת
שימו לב!
ישנה דרך נוספת ליצירת טוקן ללא צורך בבקשת Login
כאשר שולחים כל פקודת API, לרשום בפרמטר token מספר מערכת : סיסמא (username:password)

לדוגמה: