API לאימות זיהוי שולח
ממשק אימות זיהוי השולח של מיקרופיי מאמת מספר טלפון לשימוש כזיהוי שולח בהודעות סמס, בהתאם להנחיות משרד התקשורת. האימות מתבצע בשני שלבים: שליחת קוד למספר (בסמס או בהודעה קולית) ואימות הקוד שהתקבל. לאחר האימות, המספר מאושר אוטומטית במערכת ומול המפעילים וניתן לשימוש מיידי.
סקירת הממשק
ממשק זה מיועד לאימות מספר טלפון לשימוש כזיהוי שולח בהודעות סמס בלבד, בהתאם להנחיות משרד התקשורת. הזיהוי מתבצע על ידי שליחת סמס או הודעה קולית עם קוד למספר המבוקש, ושליחת הקוד שהתקבל בחזרה למערכת. לאחר האימות, מספר הטלפון מאושר אוטומטית במערכת ומול המפעילים, וניתן לשלוח אותו מיד כזיהוי שולח.
תהליך השימוש בממשק
השימוש בממשק מתבצע בשני שלבים:
auto). בקשות נוספות יחזירו MAX_SENT.
כתובת הממשק ושיטת השליחה
הכתובת לפנייה לממשק לאימות זיהוי שולח היא:
https://www.micropay.co.il/extApi/senderVerify.php
לכתובת זו מוסיפים את הפרמטרים המתאימים. חלק מהפרמטרים הם חובה וחלקם רשות. יש לשלוח את כל שמות הפרמטרים באותיות קטנות (Lower Case). ניתן להעביר את הפרמטרים בשיטת GET או POST, או לשלוח אותם בגוף הבקשה בפורמט JSON.
אימות וטוקן
כל קריאה דורשת פרמטר token, טוקן שיצרת במערכת עם הרשאת שירותי סמס.
פרמטרים
פרמטרים בכל פנייה
| פרמטר | חובה | תיאור |
|---|---|---|
token | חובה | טוקן הזדהות שיצרת במערכת, עם הרשאת שירותי סמס. |
phone | חובה | מספר הטלפון שברצונך לאמת. יש לשלוח מספר נייח או נייד ישראלי, ספרות בלבד. |
get / post | חובה | מציין למערכת באיזו שיטה נשלחו הפרמטרים. יש לשלוח אחד מהם בלבד: get=1 בשליחת GET, או post=2 בשליחת POST. הפרמטר אינו משנה את שיטת השליחה בפועל, אלא רק מצהיר עליה. (בפורמט JSON אין צורך בפרמטר זה.) |
פרמטר חובה לפנייה הראשונה (שליחת הקוד)
| פרמטר | חובה | תיאור |
|---|---|---|
type | חובה |
קובע כיצד לשלוח את הקוד למספר הטלפון. האפשרויות:
• sms: שליחת הקוד בהודעת סמס.
• vms: שליחת הקוד בהודעה קולית.
• auto: המערכת מחליטה לבד, הודעה קולית למספר נייח וסמס למספר נייד.
|
פרמטר חובה לפנייה השנייה (אימות הקוד)
| פרמטר | חובה | תיאור |
|---|---|---|
code | חובה | הקוד שהתקבל במספר הטלפון המבוקש, לאימות מול הקוד שנשלח. |
פרמטר נוסף (רשות)
| פרמטר | חובה | תיאור |
|---|---|---|
desc | רשות | טקסט של עד כ-50 תווים שיישמר כתיאור המספר במערכת, ויופיע בשליחה ידנית בחלונית "זיהוי שולח שמורים". יש לשלוח אותו בפנייה השנייה, יחד עם קוד האימות. |
דוגמאות קוד
הדוגמאות מוצגות ב-cURL. לכל שלב מוצגת דוגמה בפרמטרים (name=value) ודוגמה ב-JSON.
שלב 1: שליחת הקוד
curl "https://www.micropay.co.il/extApi/senderVerify.php?get=1&token=XXXXX&phone=0540000000&type=auto"curl -X POST https://www.micropay.co.il/extApi/senderVerify.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","phone":"0540000000","type":"auto"}'
שלב 2: אימות הקוד שהתקבל
curl "https://www.micropay.co.il/extApi/senderVerify.php?get=1&token=XXXXX&phone=0540000000&code=12345"curl -X POST https://www.micropay.co.il/extApi/senderVerify.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","phone":"0540000000","code":"12345"}'
curl -X POST https://www.micropay.co.il/extApi/senderVerify.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","phone":"0540000000","code":"12345","desc":"מספר ראשי"}'
Content-Type: application/json, כפי שמופיע בדוגמאות.
אם אינך יכול לקבוע כותרות בבקשה, תוכל במקום זאת להוסיף json=1 בכתובת ה-URL ולשלוח את גוף ה-JSON ב-POST.
תשובת השרת
המערכת מחזירה תשובה כטקסט פשוט. בקריאת JSON מוחזר מבנה אחיד {status, message, data} שבו data כולל את remoteIP.
תשובה רגילה (טקסט)
CODE_SENT OK WRONG_CODE PHONE_EXIST MAX_SENT ERROR --> Description: phone parameter, must be a valid Israeli phone
תשובה ב-JSON
// הקוד נשלח {"status":1,"message":"CODE_SENT","data":{"remoteIP":"203.0.113.10"}} // אומת והתווסף כזיהוי שולח {"status":1,"message":"OK","data":{"remoteIP":"203.0.113.10"}} // שגיאת פרמטר {"status":0,"message":"ERROR","data":{"description":"phone parameter, must be a valid Israeli phone","remoteIP":"203.0.113.10"}}
טבלת קודי תשובה
| ערך | status ב-JSON | משמעות |
|---|---|---|
CODE_SENT | 1 | המערכת קיבלה בקשה לשליחת קוד אימות, והקוד נשלח למספר. |
OK | 1 | הקוד אומת בהצלחה והמספר התווסף כזיהוי שולח מאומת. |
WRONG_CODE | 1 | הקוד שנשלח אינו תואם לקוד שהמערכת שלחה למספר. |
PHONE_EXIST | 1 | המספר המבוקש כבר קיים במערכת כזיהוי שולח. |
MAX_SENT | 1 | התקבלו מעל 4 בקשות לשליחת קוד תוך 15 דקות (2 בסמס ו-2 בהודעה קולית, או 4 ב-auto). |
ERROR | 0 | שגיאה באחד הפרמטרים או בתהליך. בטקסט מופיע רווח ותיאור; ב-JSON התיאור נמצא ב-data.description. |
שאלות נפוצות
אילו מספרי טלפון ניתן לאמת כזיהוי שולח?
מספרי טלפון נייחים וניידים ישראליים בלבד. לא ניתן לאמת מספרי 1800, 1700, מספרי חו"ל ואחרים.
כמה בקשות אימות אפשר לשלוח לאותו מספר?
עד שתי הודעות בסמס ועד שתי הודעות בהודעה קולית בפרק זמן של 15 דקות לאותו מספר (או עד ארבע בקשות ב-auto). מעבר לכך מוחזר MAX_SENT.
מה קורה אחרי שהמספר אומת?
לאחר אימות הקוד, המספר מאושר אוטומטית במערכת ומול המפעילים, וניתן להשתמש בו מיד כזיהוי שולח בהודעות סמס.
איך שולחים את הקוד בהודעה קולית במקום בסמס?
בפנייה הראשונה שולחים type=vms לשליחה בהודעה קולית, type=sms לסמס, או type=auto כדי שהמערכת תחליט (קולית לנייח, סמס לנייד).