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: שליחת הקוד בהודעה קולית.
• wa: שליחת הקוד בוואטסאפ. דורש טוקן עם הרשאת וואטסאפ וטמפלט אימות (OTP) מאושר, שאת הקוד שלו שולחים בפרמטר watemplate.
• auto: המערכת בוחרת לבד בין סמס להודעה קולית, לפי סוג המספר ולפי הצלחת המסירה. לפני שימוש באפשרות זו יש לקרוא את ההסבר במלבן הכתום שמתחת לטבלה.
|
type=auto
איך זה עובד: המערכת בודקת אוטומטית האם המספר נייח, נייד או מספר כשר, ומחליטה בהתאם אם לשלוח את הקוד בסמס או בהודעה קולית. בנוסף, אם התקבל חיווי שלילי על שליחת הסמס הראשון, או שנשלחו כבר מקסימום הודעות הסמס המורשות, המערכת תשלח את הקוד בהודעה קולית במקום. וואטסאפ אינו נכלל ב-auto, יש לבחור בו במפורש.
מה היתרון: מספרים כשרים אינם יכולים לקבל סמס כלל, וגם מספר שחסום לקבלת סמס לא יקבל את ההודעה. בשליחה רגילה בסמס הלקוחות האלה פשוט לא יקבלו את קוד האימות ולא יוכלו להשלים את ההרשמה או הכניסה, ואתם לא בהכרח תדעו על כך. באפשרות auto הם יקבלו את הקוד בהודעה קולית באופן אוטומטי, בלי שתצטרכו לזהות את סוג המספר מראש או לטפל בכך בקוד שלכם.
תנאי הפעלה, חובה: כדי להשתמש ב-auto חובה ששירות ההודעות הקוליות יהיה פעיל בחשבון, וחובה שתהיה בחשבון יתרת הודעות קוליות. שימו לב להבדל בין השניים: אם השירות אינו פעיל בחשבון, הבקשה כולה תידחה בשגיאה ולא יישלח קוד כלל, גם לא בסמס. אם השירות פעיל אך אין יתרת הודעות קוליות, הקוד יישלח כרגיל למספרים שיכולים לקבל סמס, אך מספרים שדורשים הודעה קולית לא יקבלו קוד. להפעלת השירות ולרכישת חבילה יש לפנות אלינו.
פרמטר חובה לפנייה השנייה (אימות הקוד)
| פרמטר | חובה | תיאור |
|---|---|---|
code | חובה | הקוד שהתקבל במספר הטלפון של הלקוח, לאימות מול הקוד שנשלח. |
בפנייה השנייה שולחים רק token, phone ו-code. כל שאר הפרמטרים שייכים לפנייה הראשונה: ההגדרות נשמרות עם הקוד, ואין צורך לשלוח אותן שוב.
maxtries, ברירת מחדל 10) הקודים ננעלים ומתקבלת התשובה MAX_TRIES. בנוסף אפשר לבטל קודים קודמים כשנשלח קוד חדש או אחרי אימות תקין (clearcodes), וכל קוד תקף פעם אחת בלבד ועד לסיום זמן התוקף. אם הקוד נבדק בצד שלך (למשל עם precode), ההגנות האלה לא חלות, ויש לממש אותן בעצמך.
פרמטרים נוספים לפנייה הראשונה (רשות)
| פרמטר | חובה | תיאור |
|---|---|---|
smsfrom | רשות | זיהוי השולח של הודעת הסמס. ניתן לשלוח כל זיהוי שולח שכבר אושר בחשבון. אם לא יישלח, ההודעה תצא עם זיהוי שולח ברירת מחדל של המערכת. |
vmsfrom | רשות | זיהוי השולח (מספר המקור) של ההודעה הקולית. ניתן לשלוח כל מספר טלפון שמוגדר בחשבון להודעות קוליות או לשיחות נכנסות. אם לא יישלח, ההודעה תצא ממספר חסוי. |
codelen | רשות | אורך הקוד שיישלח ללקוח, מספר בין 3 ל-8 (ברירת מחדל: 5). |
minvalid | רשות | כמה דקות הקוד תקף מרגע שנשלח, מספר בין 1 ל-60 (ברירת מחדל: 10). |
maxsms | רשות | מקסימום הודעות אימות בסמס שיישלחו ללקוח בפרק הזמן שהקוד תקף, מספר בין 1 ל-10 (ברירת מחדל: 2). |
maxvms | רשות | מקסימום הודעות אימות קוליות שיישלחו ללקוח בפרק הזמן שהקוד תקף, מספר בין 1 ל-10 (ברירת מחדל: 2). |
watemplate | רשות | חובה כאשר type=wa. קוד הטמפלט (מספר) של תבנית אימות (OTP) מאושרת בחשבונך שבה יישלח הקוד. הטמפלט חייב להיות מסוג AUTHENTICATION ובסטטוס מאושר. נוסח ההודעה נקבע על ידי הטמפלט שאושר במטא, ולכן smstext ו-lang אינם חלים על שליחת וואטסאפ. |
wafrom | רשות | מספר הוואטסאפ (השולח) שממנו יישלח הקוד. אינו חובה כאשר מוגדר בחשבונך מספר וואטסאפ יחיד, ובמקרה כזה המערכת תבחר בו אוטומטית. יש לשלוח פרמטר זה רק כאשר בחשבונך מוגדר יותר ממספר וואטסאפ אחד, כדי לציין מאיזה מספר יישלח הקוד. |
maxwa | רשות | מקסימום הודעות אימות בוואטסאפ שיישלחו ללקוח בפרק הזמן שהקוד תקף, מספר בין 1 ל-10 (ברירת מחדל: 2). |
maxtries | רשות | מספר האימותים השגויים המותר לטלפון, מספר בין 1 ל-20 (ברירת מחדל: 10). כל הניסיונות מותרים ומחזירים WRONG_CODE. אחריהם כל הקודים של הטלפון ננעלים, והפנייה הבאה מחזירה MAX_TRIES (גם עם קוד נכון), וצריך לשלוח קוד חדש. למשל עם maxtries=5: חמישה קודים שגויים מחזירים WRONG_CODE, והפנייה השישית מחזירה MAX_TRIES. קוד באורך שגוי (למשל הקלדה חלקית) לא נספר. |
clearcodes | רשות | מה קורה לקודים קודמים של אותו טלפון. בלי הפרמטר, כל קוד תקף עד שפג או שאומת, גם אם נשלח קוד חדש אחריו.
• send: קוד חדש מבטל את הקודים הקודמים (רק אחרי שנשלח בהצלחה).
• verify: אימות תקין מבטל את כל הקודים שממתינים לטלפון, לא רק את הקוד שאומת. |
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"}'
Content-Type: application/json, כפי שמופיע בדוגמאות.
אם אינך יכול לקבוע כותרות בבקשה, תוכל במקום זאת להוסיף json=1 כפרמטר בכתובת ה-URL ולשלוח את גוף ה-JSON ב-POST, לדוגמה: /extApi/sendOtp.php?json=1
תשובת השרת
בקריאה רגילה המערכת מחזירה תשובה כטקסט פשוט. בקריאת JSON מוחזר מבנה אחיד: status (דגל מספרי, 1 = הפרמטרים תקינים, 0 = שגיאת פרמטר), message (קוד התוצאה), ו-data שכולל תמיד את remoteIP.
בתשובת CODE_SENT ב-JSON מתווסף גם data.channel, שמציין באיזה ערוץ יצא הקוד: sms, vms (שיחה קולית) או wa (וואטסאפ). השדה שימושי במיוחד ב-type=AUTO, שבו המערכת בוחרת את הערוץ בעצמה, אך הוא מוחזר בכל סוג בקשה כדי שתוכל לקרוא אותו תמיד באותה צורה.
תשובה רגילה (טקסט)
CODE_SENT CODE_VALID WRONG_CODE MAX_TRIES MAX_SENT ERROR --> Description: phone parameter, must be a valid phone number
תשובה ב-JSON
// נשלח בהצלחה ב-SMS {"status":1,"message":"CODE_SENT","data":{"remoteIP":"203.0.113.10","channel":"sms"}} // נשלח בהצלחה בשיחה קולית (למשל בבקשת AUTO למספר שאינו יכול לקבל SMS) {"status":1,"message":"CODE_SENT","data":{"remoteIP":"203.0.113.10","channel":"vms"}} // אימות: קוד תקין {"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 | המערכת שלחה בהצלחה קוד ללקוח. ב-JSON מצורף data.channel עם הערוץ שבו יצא הקוד: sms, vms או wa. שים לב: זהו הערוץ שבו נשלחה הבקשה, ולא אישור מסירה ללקוח. |
CODE_VALID | 1 | יש התאמה בין הקוד שהקיש הלקוח לקוד הקיים במערכת. |
WRONG_CODE | 1 | אין התאמה בין הקוד שהקיש הלקוח לקוד הקיים, או שכבר פג תוקף הקוד. כשהניסיון נספר, ב-JSON השדה data.triesLeft מציין כמה ניסיונות נשארו (0: זה היה הניסיון האחרון, והפנייה הבאה תחזיר MAX_TRIES). קוד באורך שונה מהקוד שנשלח, או קוד שאינו ספרות, לא נספר. |
MAX_TRIES | 1 | כבר נוצלו כל האימותים השגויים המותרים (maxtries, ברירת מחדל 10), כלומר זו הפנייה שאחרי הניסיון השגוי האחרון. כל הקודים של הטלפון ננעלו, גם קוד נכון לא יתקבל, וצריך לשלוח קוד חדש. מומלץ להציג למשתמש "יותר מדי ניסיונות, נא לבקש קוד חדש". הספירה היא לכל טלפון בחשבון, וקוד נוסף שנשלח לפני הנעילה לא מאפס אותה (אלא אם שולחים clearcodes=send). שימו לב: שליחת קוד חדש כפופה למגבלת השליחות (maxsms וכו'), ולכן עשויה להחזיר MAX_SENT עד שיעבור זמן התוקף. |
MAX_SENT | 1 | הלקוח קיבל את מקסימום ההודעות האפשרי בפרק הזמן שהוגדר, ולכן לא נשלחה הודעה. הלקוח יוכל לקבל קוד שוב לאחר המתנה. בתשובה זו אין data.channel, מכיוון שלא בוצעה שליחה. שים לב: בבקשת AUTO, מיצוי מכסת ה-SMS אינו מחזיר MAX_SENT אלא עובר לשיחה קולית ומחזיר CODE_SENT. |
ERROR | 0 | שגיאה באחד הפרמטרים או בתהליך. בטקסט רגיל מופיע רווח ותיאור השגיאה; ב-JSON התיאור נמצא ב-data.description. |
שאלות נפוצות
כמה זמן קוד ה-OTP תקף?
ברירת המחדל היא 10 דקות, וניתן לשנות בין 1 ל-60 דקות באמצעות הפרמטר minvalid. קוד חדש לא מבטל קודים קודמים, אלא אם שולחים clearcodes=send.
אפשר לשלוח OTP גם בהודעה קולית ולא רק בסמס?
כן. הפרמטר type מקבל sms לשליחה בסמס, vms לשליחה בהודעה קולית, או auto שבוחר אוטומטית לפי סוג המספר והצלחת המסירה. לשליחה קולית נדרשת הרשאת שירותי טלפוניה בטוקן, וכן שירות הודעות קוליות פעיל בחשבון ויתרת הודעות קוליות.
מה נדרש כדי להשתמש ב-type=auto?
שני תנאים: שירות הודעות קוליות פעיל בחשבון, ויתרת הודעות קוליות. ההבדל ביניהם חשוב. אם השירות אינו פעיל בחשבון, הבקשה כולה תידחה בשגיאה ולא יישלח קוד כלל, גם לא בסמס. אם השירות פעיל אך אין יתרת הודעות קוליות, הקוד יישלח כרגיל למספרים שיכולים לקבל סמס, אך מספרים שדורשים הודעה קולית, כמו מספרים כשרים או מספרים החסומים לסמס, לא יקבלו קוד. להפעלת השירות ולרכישת חבילה יש לפנות אלינו.
כיצד מאמתים את הקוד שהמשתמש הזין?
שולחים פנייה שנייה לאותו ממשק עם הפרמטרים phone ו-code. התשובה CODE_VALID מציינת קוד תקין, WRONG_CODE מציינת קוד שגוי או שפג תוקפו, ו-MAX_TRIES מציינת שכבר נוצלו כל הניסיונות השגויים המותרים (ברירת מחדל 10) וצריך לשלוח קוד חדש.
אפשר לקבוע את הקוד בעצמי ולאמת בשרת שלי?
כן. שלח את הקוד בפרמטר precode ושמור אותו בשרת שלך. במצב זה תוכל לבצע את שלב האימות מול השרת שלך, וללא הפנייה השנייה למיקרופיי. במצב זה ההגנות של המערכת (הגבלת ניסיונות שגויים וביטול קודים קודמים) לא חלות, ולכן מומלץ לאמת מולנו גם כשהקוד נקבע על ידך.
באילו שפות ניתן לשלוח את קוד האימות?
הממשק תומך בארבע שפות באמצעות הפרמטר lang: עברית (he, ברירת המחדל), אנגלית (en), ערבית (ar) ורוסית (ru). השפה הנבחרת חלה הן על הודעת הסמס והן על ההודעה הקולית.