API לשליחת OTP וקוד אימות חד-פעמי
ממשק ה-OTP של מיקרופיי מיועד לשליחת סיסמה חד-פעמית (One-Time Password) או קוד אימות ללקוח, ולבדיקה האם הקוד שהוקש על ידי הלקוח תואם לקוד שנשלח. הממשק משמש לאימות זהות ולאימות דו-שלבי (2FA). לשימוש בממשק יש לרכוש חבילת הודעות סמס, ומומלץ גם חבילת הודעות קוליות. השליחה מתבצעת ב-API בפרוטוקול HTTPS סטנדרטי, ב-HTTP GET/POST רגיל או בפורמט JSON.
מה זה OTP?
OTP (ראשי תיבות של One-Time Password, סיסמה חד-פעמית) הוא קוד אימות זמני בן מספר ספרות, תקף לזמן קצר ולשימוש בודד, הנשלח ללקוח לצורך אימות זהות או אימות דו-שלבי (2FA). מיקרופיי מייצרת את הקוד, שולחת אותו ללקוח ב-SMS או בהודעה קולית, ומאמתת עבורך האם הקוד שהוקש תואם לקוד שנשלח. למונחים נוספים ראו את מילון המונחים.
תהליך השימוש בממשק
השימוש בממשק מתבצע בשני שלבים:
precode).יכולות הממשק
הממשק תומך במגוון אפשרויות: קביעת אורך הקוד שיישלח, קביעת הטקסט בהודעת הסמס, קביעת ההודעה הקולית, קביעת שפת ההודעה, הגדרת פרק הזמן שהקוד בתוקף, קביעת הקוד באופן עצמאי, וקביעת מקסימום הודעות סמס או קוליות לשליחה. כמו כן ניתן לקבוע האם לשלוח את הקוד בסמס, בהודעה קולית, או לאפשר למערכת להחליט באופן אוטומטי.
כתובת הממשק ושיטת השליחה
הכתובת לפנייה לממשק לשליחת סיסמה חד-פעמית היא:
https://www.micropay.co.il/extApi/sendOtp.php
לכתובת זו מוסיפים את הפרמטרים המתאימים. חלק מהפרמטרים הם חובה וחלקם רשות. יש לשלוח את כל שמות הפרמטרים באותיות קטנות (Lower Case). ניתן להעביר את הפרמטרים בשיטת GET או POST, או לשלוח אותם בגוף הבקשה בפורמט JSON.
אימות וטוקן
כל קריאה דורשת פרמטר token, טוקן שיצרת במערכת עם הרשאת שירותי סמס (וגם הרשאת שירותי טלפוניה אם תרצה לשלוח את הקוד בהודעה קולית או באמצעות auto).
פרמטרים
פרמטרים בכל פנייה
| פרמטר | חובה | תיאור |
|---|---|---|
token | חובה | טוקן הזדהות שיצרת במערכת, עם הרשאת שירותי סמס (וגם שירותי טלפוניה לשליחה קולית). |
phone | חובה | מספר הטלפון של הלקוח שאליו יישלח קוד האימות. ניתן לשלוח מספר נייח או נייד, ספרות בלבד. |
get / post | חובה | מציין למערכת באיזו שיטה נשלחו הפרמטרים. יש לשלוח אחד מהם בלבד: get=1 בשליחת GET, או post=2 בשליחת POST. שים לב: הפרמטר אינו משנה את שיטת השליחה בפועל, אלא רק מצהיר עליה, עליך לבצע את הבקשה בשיטה המתאימה בקוד עצמו. (בפורמט JSON אין צורך בפרמטר זה.) |
פרמטר חובה לפנייה הראשונה (שליחת הקוד)
| פרמטר | חובה | תיאור |
|---|---|---|
type | חובה |
קובע כיצד לשלוח את קוד האימות ללקוח. האפשרויות:
• sms: שליחת הקוד בהודעת סמס.
• vms: שליחת הקוד בהודעה קולית.
• auto: המערכת מחליטה לבד. היא בודקת אוטומטית האם המספר נייח, נייד או מספר כשר ומחליטה בהתאם. בנוסף, אם התקבל חיווי שלילי על שליחת הסמס הראשון, או שנשלחו מקסימום הודעות הסמס המורשות, המערכת תשלח אוטומטית הודעה קולית.
|
פרמטר חובה לפנייה השנייה (אימות הקוד)
| פרמטר | חובה | תיאור |
|---|---|---|
code | חובה | הקוד שהתקבל במספר הטלפון של הלקוח, לאימות מול הקוד שנשלח. |
פרמטרים נוספים (רשות)
| פרמטר | חובה | תיאור |
|---|---|---|
smsfrom | רשות | זיהוי השולח של הודעת הסמס. ניתן לשלוח כל זיהוי שולח שכבר אושר בחשבון. אם לא יישלח, ההודעה תצא עם זיהוי שולח ברירת מחדל של המערכת. |
vmsfrom | רשות | זיהוי השולח (מספר המקור) של ההודעה הקולית. ניתן לשלוח כל מספר טלפון שמוגדר בחשבון להודעות קוליות או לשיחות נכנסות. אם לא יישלח, ההודעה תצא ממספר חסוי. |
codelen | רשות | אורך הקוד שיישלח ללקוח, מספר בין 3 ל-8 (ברירת מחדל: 5). אם אתה משתמש בפרמטר זה, חובה לשלוח אותו גם בפנייה הראשונה וגם בפנייה השנייה. |
minvalid | רשות | כמה דקות הקוד תקף מרגע שנשלח, מספר בין 1 ל-60 (ברירת מחדל: 10). אם אתה משתמש בפרמטר זה, חובה לשלוח אותו גם בפנייה הראשונה וגם בפנייה השנייה. |
maxsms | רשות | מקסימום הודעות אימות בסמס שיישלחו ללקוח בפרק הזמן שהקוד תקף, מספר בין 1 ל-10 (ברירת מחדל: 2). |
maxvms | רשות | מקסימום הודעות אימות קוליות שיישלחו ללקוח בפרק הזמן שהקוד תקף, מספר בין 1 ל-10 (ברירת מחדל: 2). |
smstext | רשות | טקסט שיופיע לפני הקוד בהודעת הסמס (ברירת המחדל: "קוד האימות שלך הוא:"). אם אתה שולח פרמטר זה, ראו קידוד הטקסט. |
vmssid | רשות | קובע איזו הודעה קולית תושמע לפני השמעת הקוד. יש לשלוח קוד של שירות טלפוני קיים במערכת מסוג "השמעת הודעה". ברירת המחדל היא "להלן קוד האימות המבוקש". |
lang | רשות | שפת הודעת הסמס וההודעה הקולית. אחת מהאפשרויות: he = עברית (ברירת מחדל), en = אנגלית, ar = ערבית, ru = רוסית. |
precode | רשות | קביעת הקוד שיישלח באופן עצמאי, 3 עד 8 ספרות. אתה קובע את הקוד ושומר אותו בשרת שלך, כך שתוכל לבצע את שלב האימות מול השרת שלך. אם שלחת את הקוד באופן עצמאי, אין צורך בפנייה השנייה לאימות מול המערכת. |
webotp | רשות | בשליחת סמס, מפעיל את פורמט WebOTP המאפשר קריאה ואימות אוטומטיים של הקוד במכשיר הסלולר (כשהלקוח מבצע כניסה מאותו מכשיר שאליו נשלח הסמס). יש לשלוח את שם הדומיין או הסאב-דומיין שאליו נכנס המשתמש, ללא תוספות וללא http בהתחלה (לדוגמה www.mysite.co.il). המערכת תוסיף אוטומטית את שורת ה-WebOTP בסוף ההודעה, בפורמט @www.mysite.co.il #123456. מידע נוסף: WebOTP API ב-MDN. |
דוגמאות קוד
הדוגמאות מוצגות ב-cURL. לכל שלב מוצגת דוגמה בסיסית בפרמטרים (name=value), דוגמה בסיסית ב-JSON, ודוגמה מלאה ב-JSON עם כל האפשרויות.
שלב 1: שליחת הקוד
# המינימום ההכרחי: שליחה בבחירה אוטומטית בין סמס להודעה קולית curl "https://www.micropay.co.il/extApi/sendOtp.php?get=1&token=XXXXX&phone=0501234567&type=auto"
curl -X POST https://www.micropay.co.il/extApi/sendOtp.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","phone":"0501234567","type":"auto"}'
curl -X POST https://www.micropay.co.il/extApi/sendOtp.php \ -H "Content-Type: application/json" \ -d '{ "token": "XXXXX", "phone": "0501234567", "type": "auto", "smsfrom": "MyBiz", "vmsfrom": "037123456", "codelen": "6", "minvalid": "15", "maxsms": "3", "maxvms": "2", "smstext": "קוד האימות שלך הוא:", "vmssid": "2000", "lang": "he", "webotp": "www.mysite.co.il" }'
שלב 2: אימות הקוד שהלקוח הקיש
curl "https://www.micropay.co.il/extApi/sendOtp.php?get=1&token=XXXXX&phone=0501234567&code=12345"curl -X POST https://www.micropay.co.il/extApi/sendOtp.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","phone":"0501234567","code":"12345"}'
# אם שלחת codelen / minvalid בשלב 1, יש לשלוח אותם שוב גם כאן curl -X POST https://www.micropay.co.il/extApi/sendOtp.php \ -H "Content-Type: application/json" \ -d '{ "token": "XXXXX", "phone": "0501234567", "code": "123456", "codelen": "6", "minvalid": "15" }'
Content-Type: application/json, כפי שמופיע בדוגמאות.
אם אינך יכול לקבוע כותרות בבקשה, תוכל במקום זאת להוסיף json=1 כפרמטר בכתובת ה-URL ולשלוח את גוף ה-JSON ב-POST, לדוגמה: /extApi/sendOtp.php?json=1
תשובת השרת
בקריאה רגילה המערכת מחזירה תשובה כטקסט פשוט. בקריאת JSON מוחזר מבנה אחיד: status (דגל מספרי, 1 = הפרמטרים תקינים, 0 = שגיאת פרמטר), message (קוד התוצאה), ו-data שכולל תמיד את remoteIP.
תשובה רגילה (טקסט)
CODE_SENT CODE_VALID WRONG_CODE MAX_SENT ERROR --> Description: phone parameter, must be a valid phone number
תשובה ב-JSON
// נשלח בהצלחה {"status":1,"message":"CODE_SENT","data":{"remoteIP":"203.0.113.10"}} // אימות: קוד תקין {"status":1,"message":"CODE_VALID","data":{"remoteIP":"203.0.113.10"}} // שגיאת פרמטר {"status":0,"message":"ERROR","data":{"description":"phone parameter, must be a valid phone number","remoteIP":"203.0.113.10"}}
טבלת קודי תשובה
| ערך | status ב-JSON | משמעות |
|---|---|---|
CODE_SENT | 1 | המערכת שלחה בהצלחה קוד ללקוח. |
CODE_VALID | 1 | יש התאמה בין הקוד שהקיש הלקוח לקוד הקיים במערכת. |
WRONG_CODE | 1 | אין התאמה בין הקוד שהקיש הלקוח לקוד הקיים, או שכבר פג תוקף הקוד. |
MAX_SENT | 1 | הלקוח קיבל את מקסימום ההודעות האפשרי בפרק הזמן שהוגדר. הלקוח יוכל לקבל קוד שוב לאחר המתנה. |
ERROR | 0 | שגיאה באחד הפרמטרים או בתהליך. בטקסט רגיל מופיע רווח ותיאור השגיאה; ב-JSON התיאור נמצא ב-data.description. |
שאלות נפוצות
כמה זמן קוד ה-OTP תקף?
ברירת המחדל היא 10 דקות, וניתן לשנות בין 1 ל-60 דקות באמצעות הפרמטר minvalid. אם שלחת minvalid בפנייה הראשונה, יש לשלוח אותו שוב גם בפנייה השנייה לאימות.
אפשר לשלוח OTP גם בהודעה קולית ולא רק בסמס?
כן. הפרמטר type מקבל sms לשליחה בסמס, vms לשליחה בהודעה קולית, או auto שבוחר אוטומטית לפי סוג המספר והצלחת המסירה. לשליחה קולית נדרשת גם הרשאת שירותי טלפוניה בטוקן.
כיצד מאמתים את הקוד שהמשתמש הזין?
שולחים פנייה שנייה לאותו ממשק עם הפרמטרים phone ו-code. התשובה CODE_VALID מציינת קוד תקין, ו-WRONG_CODE מציינת קוד שגוי או שפג תוקפו.
אפשר לקבוע את הקוד בעצמי ולאמת בשרת שלי?
כן. שלח את הקוד בפרמטר precode ושמור אותו בשרת שלך. במצב זה תוכל לבצע את שלב האימות מול השרת שלך, וללא הפנייה השנייה למיקרופיי.
באילו שפות ניתן לשלוח את קוד האימות?
הממשק תומך בארבע שפות באמצעות הפרמטר lang: עברית (he, ברירת המחדל), אנגלית (en), ערבית (ar) ורוסית (ru). השפה הנבחרת חלה הן על הודעת הסמס והן על ההודעה הקולית.