VoIPe SMS API

מתוך wiki.voipe.co.il

הסבר על פרוטוקול VoIPe SMS Webservices.

גישה

Webservices URL: http://sms.voipe.co.il/index.php?app=ws

פרמטרים

בטבלה הבאה מפורטים הפרמטרים של ה webservices.

שם תיאור
h טוקן ה webservices, מוגדר על ידי המשתמש בתפריט "העדפות"
u שם משתמש
p סיסמא, מסופקת עבור op=get_token
op פעולה או סוג של פעולה
format בחירת פורמט פלא
from מזהה שולח הSMS עבור op=pv
to מספרי היעד, אפשר להשתמש בפסיקים
footer כותרת תחתונה של הSMS עבור op=pv
nofooter הסרת הכותרת התחתונה בSMS
msg הודעה (+ או %20 עבור רווחים, urlencode עבור תווים שאינם ascii)
schedule תזמון מסירת ההודעה, בתבנית YYYY-MM-DD hh:mm:ss
type סוג ההודעה (flash או text)
unicode ציון האם ההודעה unicode או לא (0=unicode=1, not unicode)
queue קוד תור
src מזהה או מספר השולח
dst מספר היעד (מספר יחיד)
dt תאריך ושעת שליחת הSMS
smslog_id SMS Log ID
last מזהה SMS LOG האחרון (המספר הזה לא כלול בתוצאה)
c מספר סטטוס המסירה שיוחזר
kwd מילת מפתח
login_key מפתח התחברות מוגדר על ידי האדמין דרך קריאת op=loginkeyse -webservices
query שרת שאילתות עבור מידע שימושי

קודי החזרה

בטבלה הבאה מפורטים קודי שגיאות שמוחזרים אחרי קריאה לפעולת webservices שלא צלחה.
פעולה שבוצעה בהצלחה תחזיר OK בהודעת התגובה.
שימו לב, ברירת המחדל של הודעה התגובה היא הודעה מקודדת של JSON.

קוד שגיאה תיאור
ERR 100 אימות נכשל
ERR 101 סוג הפעולה לא תקין או לא ידוע
ERR 102 שדה אחד או יותר ריק
ERR 103 אין מספיק אשראי לפעולה זו
ERR 104 טוקן webservice לא זמין
ERR 105 טוקן webservice לא מופעל עבור המשתמש
ERR 106 טוקן webservice לא מאופשר עבור כתובת הIP
ERR 200 שליחת ההודעה נכשלה
ERR 201 מספר היעד או ההודעה ריקים
ERR 400 אין סטטוס מסירה זמין
ERR 401 לא הוחזר ססטוס מסירה והSMS עדיין בתור
ERR 402 לא הוחזר ססטוס מסירה והSMS יצא מהתור
ERR 501 לא הוחזר מידע או התוצאה ריקה
ERR 600 שלב אימות האדמין נכשל
ERR 601 הזרקת ההודעה נכשלה
ERR 602 מזהה השולח או ההודעה ריקים
ERR 603 הוספת חשבון נכשלה עקב מידע חסר
ERR 604 הוספת חשבון נכשלה
ERR 605 מחיקת חשבון נכשלה עקב שם משתמש לא ידוע
ERR 606 מחיקת חשבון נכשלה
ERR 607 הוספת הורה נכשלה עקב שם משתמש לא ידוע
ERR 608 קביעה הורה נכשלה
ERR 609 שליפת הורה נכשלה עקב שם משתמש לא ידוע
ERR 610 שליפת הורה נכשלה
ERR 611 חסימת חשבון נכשלה עקב שם משתמש לא ידוע
ERR 612 חסימת חשבון נכשלה
ERR 613 ביטול חסימת חשבון נכשלה עקב שם משתמש לא ידוע
ERR 614 ביטול חסימת חשבון נכשלה
ERR 615 עריכת העדפות חשבון נכשלה עקב שם מידע חסר
ERR 616 עריכת העדפות חשבון נכשלה
ERR 617 עריכת תצורת חשבון נכשלה עקב שם מידע חסר
ERR 618 עריכת תצורת חשבון נכשלה
ERR 619 הצגת אשראי נכשלה עקב מידע חסר
ERR 620 הצגת אשראי נכשלה
ERR 621 הוספת אשראי נכשלה עקב מידע חסר
ERR 622 הוספת אשראי נכשלה
ERR 623 ניכוי אשראי נכשל עקב מידע חסר
ERR 624 ניכוי אשראי נכשל
ERR 625 הגדרת קוד התחברות נכשלה עקב מידע חסר
ERR 626 הגדרת קוד התחברות נכשלה

בעתיד יכולים להיות קודי שגיאות נוספים, הקודים הנוספים יופיעו בתבנית הבאה:

קוד שגיאה תיאור
ERR 1xx שגיאות אימות או פרמטרים
ERR 2xx שגיאות pv ספציפיות
ERR 4xx שגיאות סטטוס מסירה
ERR 5xx אחרים
ERR 6xx משימות מנהליות

פרוטוקול משימות

שליחת הודעה

שליחת הודעה למספר יחיד או מספרי נייד מרובים, username@ או groupcode#.

פרמטרים שם או תיאור
Operation Pv
Mandatory u h to msg
Optional הקלד unicode מתבנית footer nofooter
Returns מחזיר קודים

הפרמטר "to" יכול להיות מספר נייד בקידוד בינלאומי.

SMS יוצא וסטטוס מסירה

רשימת SMS יוצא וסטטוס מסירה.

פרמטרים שם או תיאור
Operation Ds
Mandatory u h
Optional queue src dst dt smslog_id c last format
Returns מחזיר מידע או קודים

הפרמטר c יאחזר מספר פעמים כהערך c, האחרון יאחזר מידע מהSMS LOG ID האחרון.

SMS נכנס

רשימת SMS נכנס.

פרמטרים שם או תיאור
Operation In
Mandatory u h
Optional queue src dst dt smslog_id c last format
Returns מחזיר מידע או קודים

הפרמטר c יאחזר מספר פעמים כהערך c, האחרון יאחזר מידע מהSMS LOG ID האחרון.

User credit

שליפת מידע אודות האשראי של המשתמש.

פרמטרים שם או תיאור
Operation Cr
Mandatory u h
Optional Format
Returns מחזיר אשראי של המשתמש או קודים

Get token

שליפת טוקן webservices של המשתמש. יכול לשמש כמנגנון התחברות.

פרמטרים שם או תיאור
Operation get_token
Mandatory u p
Optional Format
Returns מחזיר טוקן webservices או קודים

Set token

קביעת טוקן webservices של המשתמש. יכול לשמש כמנגנון שינוי סיסמא.

פרמטרים שם או תיאור
Operation set_token
Mandatory u h
Optional Format
Returns מחזיר טוקן webservices חדש או קודים

התחברות Webservices

אימות משתמש באמצעות webservices והפניה לindex.php עם האימות, מוצלח, נכשל או לא תקין.

פרמטרים שם או תיאור
Operation ws_login
Mandatory u login_key
Optional None
Returns אין החזרות, הפניה ל- index.php

הפרמטר login_key מוגדר על ידי חשבונות אדמין דרך קריאת webservices בשימוש הפעולה loginkeyset.

JSON HTTPS

חייב להיות שימוש ב HTTPS במקום HTTP.
ה-URL הבסיסי חייב להיות:
https://sms.voipe.co.il/playsms/api.php
כל הפרמטרים אמורים להיות מועברים כחלק מאובייקט JSON בגוף POST ולא ב-GET.
את הפרמטרים הבאים יש לשנות:
1. "user" במקום "u".
2. "token" במקום "h".

בשאר הפרמטרים של Playsms Webservice Api ניתן להשתמש כפי שהם מפורטים ב- http://sms.voipe.co.il/index.php?app=ws.


דוגמא לקריאת API
POST /playsms/api.php HTTP/1.1
Host: sms.voipe.co.il

{"user":"vipuser","token":"1212121212121212121212121212","op":"pv","to":"052111222","msg":"Test message","from":"VipInvest"}


מספר הערות

  • השדה "from" חייב להכיל ערך מוגדר מראש אשר נקבע בפאנל הניהול שלנו ע"י האדמין- לכן יש להתייעץ לגבי שדה זה עם התמיכה שלנו.
  • השדה "from" אמור להיות עד 8 תווים.

שליפת אשראי חשבון

הצגת אשראי או יתרה של חשבון.

פרמטרים שם או תיאור
Operation creditview
Mandatory u h data_username
Optional Format
Returns מחזיר קודים ויתרה

דוגמאות

שליחת SMS

דוגמא ל webservice URL:
http://sms.voipe.co.il/index.php?app=ws&u=anton&h=a45a02791b2fe2fedb078c39fd83637a&op=pv&to=0987654321&msg=test+only

הסבר
VoIPe SMS webservices ב-sms.voipe.co.il עם הפעולה op pv (שליחת SMS) נקרא עם הפרמטרים:
1. שם משתמש "u".
2. טוקן "h".
3. מספר יעד 050555555.
4. ההודעה "test only".
5. תבנית הפלט היא תבנית ברירת המחדל- JSON.

כשהSMS נשלח בהצלחה VoUPe SMS יחזיר הודעת סטטוס OK בבתנית JSON:
{"data":[{"status":"OK","error":"0","smslog_id":"30","queue":"afb5f34575e30ec4efe4471cf5d1bee4","to":"0987654321"}],"error_string":null}

במקרה ששגיאה אירעה, VoIPe SMS יחזיר את אחד מקודי ההחזרה בתבנית JSON.

רשימת SMS נכנס

דוגמא ל webservice URL:
http://x.com/index.php?app=ws&u=anton&h=482ac0069592c647289e52dfef88be68&op=in&kwd=IDOL&format=xml
הסבר
VoIPe SMS webservices ב x.com עם הפעולה op in (סמס נכנס) נקרא עם הפרמטרים:
1. שם משתמש "u".
2. טוקן "h".
3. מילת מפתח kwd.
4. תבנית הפלט ב XML.

בעת הצלחה VoIPe SMS יחזיר הודעת סטטוס OK בבתנית XML:

Xml.png


























במקרה ששגיאה אירעה, VoIPe SMS יחזיר את אחד מקודי ההחזרה בתבנית XML.