API לשליחת הודעות SMS

ממשק שליחת ה-SMS של מיקרופיי מאפשר לשלוח הודעות סמס לרשימה של מספרי טלפון או לרשימות תפוצה, ישירות ממערכות מחשוב, מערכות CRM, אתרים ואפליקציות. השליחה מתבצעת ב-API בפרוטוקול HTTPS סטנדרטי, בשיטת HTTP GET או POST רגילה או בפורמט JSON, ותומכת בתזמון, בהתראות לשרת שלך ובהודעות מותאמות אישית לכל נמען.

סקירת הממשק

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

כתובת הממשק ושיטת השליחה

הכתובת לפנייה לממשק שליחת הודעות הסמס היא:

https://www.micropay.co.il/extApi/scheduleSms.php

לכתובת זו מוסיפים את הפרמטרים המתאימים. חלק מהפרמטרים הם חובה וחלקם רשות. יש לשלוח את כל שמות הפרמטרים באותיות קטנות (Lower Case). ניתן להעביר את הפרמטרים בשיטת GET או POST, או לשלוח אותם בגוף הבקשה בפורמט JSON.

אימות וטוקן

כל קריאה דורשת פרמטר token, טוקן שיצרת במערכת עם הרשאת שירותי סמס.

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

פרמטרים

פרמטרים בסיסיים

קביעת הנמענים

יש לשלוח אחד מבין שני הפרמטרים הבאים, לפי יעד השליחה:

פרמטרים נוספים (רשות)

פרמטרים לתזמון תאריך ושעה

לתזמון השליחה יש לשלוח את כל חמשת הפרמטרים יחד. ברירת המחדל, ללא תזמון, היא מועד שליחת הבקשה.

אורך ההודעה, קידוד וחיוב

הודעת סמס בסיסית מכילה עד 140 תווים באנגלית או 70 תווים בכל שפה אחרת (כולל עברית). המערכת מאפשרת לשלוח הודעות ארוכות של עד 1000 תווים, אשר יגיעו כהודעה אחת ארוכה ללקוח. כאשר ההודעה ארוכה מ-70 תווים, המערכת מחשבת כל 67 תווים כהודעה בודדת (134 באנגלית), והעלות תלויה בכמות התווים בהודעה לפי החבילה שרכשת.

• קידוד הטקסט תלוי בצורת השליחה (מתי לבצע url encode ומתי לא), ראו אפשרויות שליחה וקידוד.
• ירידת שורה נספרת כשני תווים (CRLF). כדי להוסיף ירידת שורה בהודעה: בשליחה רגילה הוסיפו %0D (התו CR), שנספר כתו אחד; בשליחת JSON השתמשו ב-\r בתוך הטקסט. ירידת שורה מלאה היא %0D%0A (או \r\n ב-JSON) ונספרת כשני תווים.
• ניתן לשלוח אימוג'ים בהודעה (רק בקידוד UTF-8) על ידי שליחת האימוג'י עצמו. מומלץ לבדוק בטסט שהאימוג'י נתמך במכשיר. אפשר להעתיק אימוג'ים לדוגמה מ- emojicopy.com.

דוגמאות קוד

הדוגמאות מוצגות ב-cURL. לכל מצב מוצגת דוגמה בסיסית בפרמטרים (name=value), דוגמה בסיסית ב-JSON, ודוגמה מלאה ב-JSON עם הפרמטרים הנפוצים.

שליחה לרשימת מספרים

curl "https://www.micropay.co.il/extApi/scheduleSms.php?get=1&token=XXXXX&from=035555555&msg=test%20message&list=0501234567"

curl -X POST https://www.micropay.co.il/extApi/scheduleSms.php \
  -H "Content-Type: application/json" \
  -d '{"token":"XXXXX","from":"035555555","msg":"test message","list":"0501234567,0541234567"}'

curl -X POST https://www.micropay.co.il/extApi/scheduleSms.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "XXXXX",
    "from": "035555555",
    "msg": "הודעת השירות שלך",
    "list": "0501234567,0541234567",
    "desc": "קמפיין יוני",
    "np": "0501112222",
    "ne": "alerts@mysite.co.il",
    "dh": "09", "di": "30", "dy": "2026", "dm": "06", "dd": "20"
}'

שליחה לרשימת תפוצה

# שליחה לרשימת תפוצה לפי קוד מאגר
curl "https://www.micropay.co.il/extApi/scheduleSms.php?get=1&token=XXXXX&from=035555555&msg=test%20message&pid=4898"

curl -X POST https://www.micropay.co.il/extApi/scheduleSms.php \
  -H "Content-Type: application/json" \
  -d '{"token":"XXXXX","from":"035555555","msg":"test message","pid":"4898,5012"}'

תשובת השרת

המערכת מחזירה תשובה ראשונית מיידית. בקריאה רגילה התשובה מתקבלת כטקסט פשוט; בקריאת JSON מוחזר מבנה אחיד {status, message, data} שבו data.taskId הוא קוד הקמפיין, ו-data כולל תמיד את remoteIP.

תשובה רגילה (טקסט)

# הצלחה: OK ואחריו קוד הקמפיין שהוקצה
OK 34556

# שגיאה: ERROR ואחריו תיאור
ERROR --> Description: from parameter, sender id not approved

תשובה ב-JSON

// התקבל בהצלחה ונכנס לתור
{"status":1,"action":"sendsms","message":"OK","data":{"taskId":"34556","remoteIP":"203.0.113.10"}}

// שגיאת פרמטר
{"status":0,"message":"ERROR","data":{"description":"from parameter, sender id not approved","remoteIP":"203.0.113.10"}}

טבלת קודי תשובה

ווידוא קליטת המספרים

להפעלת מנגנון הווידוא הוסיפו את הפרמטר validate. בשליחה רגילה (GET/POST) יש לשלוח אותו ללא ערך וכפרמטר האחרון בפנייה. בשליחת JSON שלחו "validate":1 בכל מקום בגוף הבקשה.

# validate נשלח אחרון, ללא ערך
curl "https://www.micropay.co.il/extApi/scheduleSms.php?get=1&token=XXXXX&from=035555555&msg=test%20message&list=0501234567&validate"

curl -X POST https://www.micropay.co.il/extApi/scheduleSms.php \
  -H "Content-Type: application/json" \
  -d '{"token":"XXXXX","from":"035555555","msg":"test message","list":"0501234567","validate":1}'

בתשובה יתווסף נתון נוסף:

# שליחה לרשימת מספרים: מספר הטלפונים שזוהו, ואז קוד הקמפיין
OK 250 34556

# שליחה לרשימת תפוצה
OK VALID 34556

// שליחה לרשימת מספרים: count = כמות הטלפונים שזוהו
{"status":1,"action":"sendsms","message":"OK","data":{"count":250,"taskId":"34556","remoteIP":"203.0.113.10"}}

// שליחה לרשימת תפוצה: valid = true
{"status":1,"action":"sendsms","message":"OK","data":{"valid":true,"taskId":"34556","remoteIP":"203.0.113.10"}}

הודעות מותאמות אישית לכל נמען

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

{"0540000000":"message number 1","0500000000":"message number 2"}

# listjson כפרמטר טופס (form-urlencoded); cURL מבצע את ה-url encode
curl -X POST https://www.micropay.co.il/extApi/scheduleSms.php \
  --data-urlencode "post=2" \
  --data-urlencode "token=XXXXX" \
  --data-urlencode "from=test" \
  --data-urlencode 'listjson={"0540000000":"message number 1","0500000000":"message number 2"}'

# listjson כאובייקט מקונן בתוך גוף ה-JSON
curl -X POST https://www.micropay.co.il/extApi/scheduleSms.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "XXXXX",
    "from": "test",
    "listjson": {
        "0540000000": "message number 1",
        "0500000000": "message number 2"
    }
}'

התראות לשרת שלך

כדי לקבל התראות על מהלך השליחה לעמוד בשרת שלך, הוסף בפנייה את הפרמטר nu עם כתובת העמוד. ההתראות נשלחות בשיטת GET עם הפרמטרים msg (סוג ההתראה), tid (קוד הקמפיין) ו-info (מידע נוסף, אם קיים):

http://www.yoursite.co.il/alert.asp?get=1&msg=END&tid=34556&info=589

אותן התראות יכולות להישלח גם בסמס או במייל (לפי np / ne). סוגי ההתראות:

שאלות נפוצות

ממשקים קשורים