מוסכמות ה-API ופורמט התשובה
כל ממשקי ה-API של מיקרופיי חולקים מוסכמות אחידות: כתובות הממשקים נמצאות תחת /extApi/, הפרמטרים נשלחים בשיטת GET או POST,
וניתן לבחור במצב JSON שמחזיר מבנה תשובה אחיד {status, message, data}. עמוד זה מרכז את הכללים החלים על כל הממשקים: שיטות שליחה, מצב JSON, קידוד, פורמט מספרי טלפון ופורמט השגיאות.
כתובות הממשקים
כל הממשקים נמצאים תחת הבסיס:
https://www.micropay.co.il/extApi/
לכל ממשק כתובת ייעודית, לדוגמה scheduleSms.php לשליחת סמס או sendOtp.php ל-OTP. השליחה מתבצעת בפרוטוקול HTTPS סטנדרטי. יש לשלוח את כל שמות הפרמטרים באותיות קטנות (Lower Case).
שיטת השליחה: GET או POST
ניתן לשלוח את הפרמטרים בשיטת GET או POST. יש להוסיף פרמטר המצהיר על השיטה שבחרת:
| פרמטר | שיטה | תיאור |
|---|---|---|
get=1 | GET | הצהרה על שליחה בשיטת GET. הפרמטרים עוברים במחרוזת ה-URL. |
post=2 | POST | הצהרה על שליחה בשיטת POST. הפרמטרים עוברים בגוף הבקשה. |
מצב JSON
בנוסף לשליחה הרגילה ב-name=value, ניתן לעבוד במצב JSON: שליחת גוף JSON וקבלת תשובה במבנה JSON אחיד. מצב זה אופציונלי לחלוטין, והפונקציונליות זהה לשליחה הרגילה.
איך מפעילים
קיימות שתי דרכים להפעיל את מצב ה-JSON:
Content-Type: application/json וגוף JSON. זו הדרך המומלצת.json=1 בכתובת ה-URL (לדוגמה ...?json=1) ושלח את גוף ה-JSON ב-POST.מבנה התשובה
פורמט התשובה תלוי בשיטת השליחה:
תשובה רגילה (טקסט)
בשליחת GET או POST רגילה, התשובה מתקבלת כטקסט פשוט המתחיל בקוד תוצאה. לדוגמה:
OK 34556 ERROR --> Description: token parameter, invalid or missing
תשובה ב-JSON
במצב JSON מוחזר תמיד מבנה אחיד:
| שדה | סוג | תיאור |
|---|---|---|
status | מספר | דגל הצלחה מספרי: 1 כשהפרמטרים תקינים, 0 רק כאשר התקבלה שגיאת פרמטר (ERROR). |
action | מחרוזת | אופציונלי. מהדהד את הפעולה שבוצעה, תמיד באותיות קטנות, לדוגמה sendsms או sendvms. מופיע מיד אחרי status בממשקים שמגדירים פעולה, ונעדר באחרים (למשל OTP). |
message | מחרוזת | קוד התוצאה, לדוגמה OK, CODE_SENT, ERROR. זהה לקוד שמופיע בתחילת התשובה הרגילה. |
data | אובייקט | נתונים נוספים לפי הממשק (לדוגמה taskId בשליחת סמס). כולל תמיד את remoteIP, ובשגיאה את description. |
// הצלחה (השדה action מהדהד את הפעולה) {"status":1,"action":"sendsms","message":"OK","data":{"taskId":"34556","remoteIP":"203.0.113.10"}} // שגיאת פרמטר {"status":0,"message":"ERROR","data":{"description":"token parameter, invalid or missing","remoteIP":"203.0.113.10"}}
status: הערך 0 מציין אך ורק שגיאת פרמטר (ERROR). תוצאות אחרות שאינן הצלחה מלאה, כמו WRONG_CODE, MAX_SENT או NOT_ENOUGH_CREDIT, נחשבות לפנייה תקינה ולכן מחזירות status 1, והקוד נשמר ב-message. כדאי לבדוק תמיד את message ולא רק את status.
אפשרויות שליחה וקידוד טקסט
אפשר לשלוח את הנתונים בארבע צורות. הצורך ב-url encoding תלוי במיקום הנתונים וב-Content-Type, ושני אלה חייבים להתאים זה לזה.
| צורת שליחה | Content-Type | url encode לערכים? |
|---|---|---|
| GET, פרמטרים בכתובת (query string) | — | כן, חובה |
POST, גוף בפורמט name=value | application/x-www-form-urlencoded | כן, חובה |
| POST, גוף מרובה חלקים | multipart/form-data | לא, הערכים נשלחים כפי שהם |
| JSON | application/json | לא url encode, רק escape של JSON |
- מתי לקודד: רק כשהנתונים נמצאים בכתובת (query string ב-GET), או בגוף מסוג
application/x-www-form-urlencoded. בצורות אלו תווים כמו רווח,&,+,=ו-%מפרידים בין פרמטרים, ולכן בערכי טקסט חופשי (למשל תוכן הודעה) חובה לבצע url encode כדי שלא יפרקו את הבקשה. - מתי לא לקודד: בשליחת multipart/form-data (לדוגמה העברת מערך נתונים ל-cURL, שמייצרת multipart אוטומטית) ובשליחת JSON. בשתי הצורות כל ערך עובר במבנה משלו, ו-url encoding דווקא יפגום בו (לדוגמה רווח יהפוך ל-
%20מילולי בתוך ההודעה). - בשליחת JSON מבצעים רק escape של JSON: לפני התווים
"ו-\מוסיפים\(לדוגמה\"או\\). השרת מפענח את הגוף כ-JSON ואינו מבצע url decode. - חשוב, התאמת Content-Type לגוף: השרת מפענח את הגוף לפי ה-
Content-Type. שליחת query string בגוף תוך הצהרה עלmultipart/form-data(או להפך) תגרום לכך שהפרמטרים לא ייקראו כלל. ודאו שצורת הגוף תואמת לכותרת. - קידוד תווים: מומלץ לעבוד ב-UTF-8, הנדרש לתמיכה מלאה בעברית ובאימוג'ים. במצב JSON הקידוד תמיד UTF-8.
- ירידת שורה בטקסט: בטקסט url-encoded השתמשו ב-
%0D(CR) או%0A(LF); בשליחת JSON השתמשו ב-\rאו\n; ב-multipart הכניסו ירידת שורה ממש.
פורמט מספרי טלפון
מומלץ לשלוח מספרי טלפון בספרות בלבד, ללא רווחים או מקף. ניתן לשלוח בפורמט מקומי (לדוגמה 0501234567) או בינלאומי. רשימות מספרים נשלחות מופרדות בפסיק.
פורמט השגיאות
שגיאת פרמטר מחזירה תשובה המתחילה ב-ERROR ואחריה רווח ותיאור השגיאה. במצב JSON, message יהיה ERROR,
status יהיה 0, ותיאור השגיאה יופיע ב-data.description. כדאי לרשום (log) את תיאור השגיאה לצורך איתור תקלות.
שאלות נפוצות
מה ההבדל בין שליחה ב-GET, ב-POST וב-JSON?
GET ו-POST שולחים פרמטרים ב-name=value ומחזירים טקסט פשוט. שליחה עם Content-Type: application/json (או json=1) מחזירה JSON במבנה {status, message, data}. הבחירה היא של המפתח, והפונקציונליות זהה.
מה המבנה של התשובה ב-JSON?
מבנה אחיד: status (1 הצלחה, 0 שגיאת פרמטר), message (קוד התוצאה כמו OK), ו-data (נתונים נוספים לפי הממשק, כולל תמיד remoteIP).
מתי status מקבל את הערך 0?
רק כשהפנייה נכשלה בגלל פרמטר שגוי (ERROR). כל תוצאה אחרת, גם אם אינה הצלחה מלאה, מחזירה status 1 והקוד נשמר ב-message.