API - גישת מפתחים למערכות


  • ימות המשיח ניהול ראשי

    מצ"ב קישור להגדרות הAPI למערכות ימות המשיח.

    מפתחים מוזמנים להשתמש.


  • ניהול

    API גישת מפתחים למערכות

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

    בכל פעולה בAPI יש 2 חלקים. חלק ראשון - שליחת בקשה לשרת. חלק שני - תשובה מהשרת.

    חלק ראשון: שליחת בקשה לשרת
    את הבקשה יש לשלוח לכתובת https://www.call2all.co.il/ym/api במידה והמערכת נמצאת בשרת הפרייבט הכתובת למשלוח הבקשה היא https://private.call2all.co.il/ym/api

    את כל הבקשות (למעט העלאת קבצים) ניתן לשלוח בGET או בPOST

    הבקשה מורכבת מ2 חלקים. חלק 1 פקודה חלק 2 פרמטרים.

    לדוגמה: הפקודה להורדת קובץ היא DownloadFile והפרמטרים הנדרשים הם token path
    במקרה כזה הבקשה בGET תראה כך:

    https://www.call2all.co.il/ym/api/DownloadFile?token=1234&path=ivr/1/000.wav
    

    בהמשך נביא את כל הפקודות הקיימות.

    חלק שני: התשובה מהשרת
    כל התשובות מהשרת (למעט הורדת קבצים) מקודדות בפורמט JSON וכוללות את המידע בנוגע לבקשה. בהמשך נביא את סוגי התשובות הקיימות עבור כל בקשה.

    בנוסף, בכל תשובה יכללו המאפיינים הבאים:
    yemotAPIVersion – גרסת הAPI הנוכחית (עשוי לשמש לאיתור בעיות תאימות עם גרסאות עתידיות)
    responseStatus – מידע אודות הפעולה המבוקשת. אם הפעולה המבוקשת הושלמה בהצלחה, הערך יהיה OK אם הפעולה נכשלה, הערך יהיה ERROR ערך FORBIDDEN פירושו שהבקשה הייתה אסורה על ידי השרת, ערך EXCEPTION פירושו שהבקשה גרמה לחריג בשרת.
    מאפיינים נוספים הנשלחים בחלק מהבקשות
    message - הסבר על הפעולה שבוצעה או הסבר על השגיאה.
    messageCode - קוד שגיאה. להלן יובאו כל סוגי הקודים הקיימים. אם במקום קוד שגיאה התקבל הערך null אירעה שגיאה כללית.

    דוגמה לתשובה מהשרת עם הודעת שגיאה:

    {
    "yemotAPIVersion": "1",
    "responseStatus": "ERROR",
    "message": "Username or password is incorrect",
    "messageCode": 1
    }
    

    בדוגמה זו, גירסת הAPI היא 1, הפעולה נכשלה, הסבר על השגיאה זמין במאפיין 'message' קוד השגיאה הוא 1.

    הפונקציות האפשריות בממשק הAPI:

    בגדול כמעט כל הדברים שאפשר לעשות דרך האתר אפשר גם בAPI (הפעלת קמפיינים שינוי שלוחות ניהול קבצים ועוד)

    במדריך זה נחלק את האפשרויות ל3 חלקים.
    חלק 1 התחברות למערכת והגדרות כלליות - שינוי סיסמה העברת יחידות עדכון פרטי משתמש ועוד
    חלק 2 ניהול קמפיינים - הגדרת קמפיינים, הפעלת קמפיין עדכון מספרים ועוד.
    חלק 3 מערכת תוכן - ניהול הקבצים והשלוחות במערכת.

    חלק 1 התחברות למערכת והגדרות כלליות
    התחברות-Login
    התנתקות-Logout
    פרטי המערכת-GetSession
    שינוי סיסמת ניהול-SetPassword
    עדכון פרטי משתמש-SetCustomerDetails
    קבלת רשימת חיובי יחידות-GetTransactions
    העברת יחידות-TransferUnits
    קבלת רשימת שיחות נכנסות-GetIncomingCalls
    העלאת קובץ-UploadFile
    הורדת קובץ-DownloadFile

    חלק 2 ניהול קמפיינים
    קבלת מצב כל תבניות הקמפיינים-GetTemplates
    עדכון תבנית קמפיין-UpdateTemplate
    העלאת קובץ שמע לקמפיין - ראה ערך UploadFile
    הורדת קובץ שמע של הקמפיין - ראה ערך DownloadFile
    יצירת תבנית קמפיין חדשה-CreateTemplate
    מחיקת תבנית קמפיין-DeleteTemplate
    קבלת רשימת מספרים מתבנית קמפיין-GetTemplateEntries
    הוספת מספר בודד לתבנית קמפיין-UpdateTemplateEntry
    הוספת כמות מספרים לתבנית קמפיין-UpdateTemplateEntries
    מחיקת מספרים מתבנית קמפיין-ClearTemplateEntries
    העלאת קובץ טקסט והפיכתו לרשימת טלפונים לתבנית קמפיין-UploadPhoneList
    הפעלת קמפיין-RunCampaign
    מצב הקמפיין-GetCampaignStatus
    הורדת דו"ח קמפיין-DownloadCampaignReport
    קבלת קמפיינים פעילים-GetActiveCampaigns
    ביצוע פעולות בקמפיינים פעילים-CampaignAction
    יצירת קמפיין מתוזמן-ScheduleCampaign
    קבלת קמפיינים מתוזמנים-GetScheduledCampaigns
    מחיקת קמפיין מתוזמן-DeleteScheduledCampaign

    חלק 3 מערכת תוכן
    קבלת מידע מלא על השלוחה-GetIVR2Dir
    קבלת רשימת קבצים שבשלוחה-GetIvrTree
    ניהול קבצים (שינוי שם, העתקה, העברה ומחיקה)-FileAction
    העלאת קבצים- ראה ערך UploadFile
    הורדת קבצים - ראה ערך DownloadFile
    קבלת תוכן קובץ טקסט-GetTextFile
    העלאת טקסט לקובץ-UploadTextFile


  • ניהול

    התחברות-Login

    הסבר: בכל הבקשות הנשלחות לשרת יש צורך בפרמטר token שמשמש כקוד התחברות למערכת

    הפקודה היא -Login
    הפרמטרים הנדרשים:

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

    מאפייני תגובת השרת (בכניסה מוצלחת):

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

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

    דוגמה לקבלת פרטי מערכת בGET בצורה הזאת:

    https://call2all.co.il/ym/api/GetSession?token=0795000000:0000
    

  • ניהול

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

    הפקודה היא - Logout
    הפרמטרים הנדרשים:

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

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


  • ניהול

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

    הפקודה היא - GetSession
    הפרמטרים הנדרשים:

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

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

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

  • ניהול

    שינוי סיסמת ניהול-SetPassword
    הגדרת סיסמת ניהול חדשה

    הפקודה היא - SetPassword
    הפרמטרים הנדרשים:

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

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


  • ניהול

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

    הפקודה היא - SetCustomerDetails
    הפרמטרים הנדרשים:

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

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


  • ניהול

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

    הפקודה היא - GetTransactions
    הפרמטרים הנדרשים:

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

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

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

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

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

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

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

  • ניהול

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

    הפקודה היא - TransferUnits
    הפרמטרים הנדרשים:

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

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

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

    במקרה של שגיאה בביצוע ההעברה ההודעות והקודים האפשריים הם כדלקמן:

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

  • ניהול

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

    הפקודה היא - GetIncomingCalls
    הפרמטרים הנדרשים:

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

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

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

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

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

התחבר כדי לפרסם תגובה