מיקרופיי · מרכז מפתחים מרכז מפתחים · OTP וקוד אימות

API לשליחת OTP וקוד אימות חד-פעמי

עודכן לאחרונה: 3 בנובמבר 2026 · נתמך ב-HTTP GET, POST ו-JSON

ממשק ה-OTP של מיקרופיי מיועד לשליחת סיסמה חד-פעמית (One-Time Password) או קוד אימות ללקוח, ולבדיקה האם הקוד שהוקש על ידי הלקוח תואם לקוד שנשלח. הממשק משמש לאימות זהות ולאימות דו-שלבי (2FA). לשימוש בממשק יש לרכוש חבילת הודעות סמס, ומומלץ גם חבילת הודעות קוליות. השליחה מתבצעת ב-API בפרוטוקול HTTPS סטנדרטי, ב-HTTP GET/POST רגיל או בפורמט JSON.

כתובת הממשק
/extApi/sendOtp.php
שיטות נתמכות
HTTP GET · POST · JSON
אימות
טוקן עם הרשאת שירותי סמס/טלפוניה
ערוצי שליחה
סמס · הודעה קולית · אוטומטי

מה זה OTP?

OTP (ראשי תיבות של One-Time Password, סיסמה חד-פעמית) הוא קוד אימות זמני בן מספר ספרות, תקף לזמן קצר ולשימוש בודד, הנשלח ללקוח לצורך אימות זהות או אימות דו-שלבי (2FA). מיקרופיי מייצרת את הקוד, שולחת אותו ללקוח ב-SMS או בהודעה קולית, ומאמתת עבורך האם הקוד שהוקש תואם לקוד שנשלח. למונחים נוספים ראו את מילון המונחים.

תהליך השימוש בממשק

השימוש בממשק מתבצע בשני שלבים:

1 שליחת הקוד: מבצעים פנייה לממשק עם מספר הטלפון, והמערכת שולחת קוד אימות ללקוח ב-SMS או בהודעה קולית. ניתן גם לקבוע את הקוד שיישלח באופן עצמאי (באמצעות precode).
2 אימות הקוד: מבצעים פנייה שנייה לממשק עם מספר הטלפון והקוד שהלקוח הקיש, והמערכת מחזירה האם הקוד תואם לקוד שנשלח. אם שלחת את הקוד באופן עצמאי בשלב הראשון, אין צורך לבצע את השלב השני מול המערכת, ניתן לאמת את הקוד מול השרת שלך.

יכולות הממשק

הממשק תומך במגוון אפשרויות: קביעת אורך הקוד שיישלח, קביעת הטקסט בהודעת הסמס, קביעת ההודעה הקולית, קביעת שפת ההודעה, הגדרת פרק הזמן שהקוד בתוקף, קביעת הקוד באופן עצמאי, וקביעת מקסימום הודעות סמס או קוליות לשליחה. כמו כן ניתן לקבוע האם לשלוח את הקוד בסמס, בהודעה קולית, או לאפשר למערכת להחליט באופן אוטומטי.

שים לב: המערכת שולחת בכל פנייה קוד אימות אחד. באחריותך לבצע פניות נוספות לשליחת קוד נוסף במידה והלקוח לא קיבל את הקוד, למשל על ידי הצגת קישור ללקוח שיאפשר לו לבקש קוד נוסף.

כתובת הממשק ושיטת השליחה

הכתובת לפנייה לממשק לשליחת סיסמה חד-פעמית היא:

Endpoint
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: שליחת הקוד

בסיסי · HTTP GET
# המינימום ההכרחי: שליחה בבחירה אוטומטית בין סמס להודעה קולית
curl "https://www.micropay.co.il/extApi/sendOtp.php?get=1&token=XXXXX&phone=0501234567&type=auto"
בסיסי · JSON
curl -X POST https://www.micropay.co.il/extApi/sendOtp.php \
  -H "Content-Type: application/json" \
  -d '{"token":"XXXXX","phone":"0501234567","type":"auto"}'
מלא · JSON (כל הפרמטרים)
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: אימות הקוד שהלקוח הקיש

בסיסי · HTTP GET
curl "https://www.micropay.co.il/extApi/sendOtp.php?get=1&token=XXXXX&phone=0501234567&code=12345"
בסיסי · JSON
curl -X POST https://www.micropay.co.il/extApi/sendOtp.php \
  -H "Content-Type: application/json" \
  -d '{"token":"XXXXX","phone":"0501234567","code":"12345"}'
איך מפעילים את מצב ה-JSON? הדרך המומלצת היא לשלוח את הבקשה עם הכותרת 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, שבו המערכת בוחרת את הערוץ בעצמה, אך הוא מוחזר בכל סוג בקשה כדי שתוכל לקרוא אותו תמיד באותה צורה.

תשובה רגילה (טקסט)

Plain text
CODE_SENT
CODE_VALID
WRONG_CODE
MAX_TRIES
MAX_SENT
ERROR --> Description: phone parameter, must be a valid phone number

תשובה ב-JSON

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_SENT1המערכת שלחה בהצלחה קוד ללקוח. ב-JSON מצורף data.channel עם הערוץ שבו יצא הקוד: sms, vms או wa. שים לב: זהו הערוץ שבו נשלחה הבקשה, ולא אישור מסירה ללקוח.
CODE_VALID1יש התאמה בין הקוד שהקיש הלקוח לקוד הקיים במערכת.
WRONG_CODE1אין התאמה בין הקוד שהקיש הלקוח לקוד הקיים, או שכבר פג תוקף הקוד. כשהניסיון נספר, ב-JSON השדה data.triesLeft מציין כמה ניסיונות נשארו (0: זה היה הניסיון האחרון, והפנייה הבאה תחזיר MAX_TRIES). קוד באורך שונה מהקוד שנשלח, או קוד שאינו ספרות, לא נספר.
MAX_TRIES1כבר נוצלו כל האימותים השגויים המותרים (maxtries, ברירת מחדל 10), כלומר זו הפנייה שאחרי הניסיון השגוי האחרון. כל הקודים של הטלפון ננעלו, גם קוד נכון לא יתקבל, וצריך לשלוח קוד חדש. מומלץ להציג למשתמש "יותר מדי ניסיונות, נא לבקש קוד חדש". הספירה היא לכל טלפון בחשבון, וקוד נוסף שנשלח לפני הנעילה לא מאפס אותה (אלא אם שולחים clearcodes=send). שימו לב: שליחת קוד חדש כפופה למגבלת השליחות (maxsms וכו'), ולכן עשויה להחזיר MAX_SENT עד שיעבור זמן התוקף.
MAX_SENT1הלקוח קיבל את מקסימום ההודעות האפשרי בפרק הזמן שהוגדר, ולכן לא נשלחה הודעה. הלקוח יוכל לקבל קוד שוב לאחר המתנה. בתשובה זו אין data.channel, מכיוון שלא בוצעה שליחה. שים לב: בבקשת AUTO, מיצוי מכסת ה-SMS אינו מחזיר MAX_SENT אלא עובר לשיחה קולית ומחזיר CODE_SENT.
ERROR0שגיאה באחד הפרמטרים או בתהליך. בטקסט רגיל מופיע רווח ותיאור השגיאה; ב-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). השפה הנבחרת חלה הן על הודעת הסמס והן על ההודעה הקולית.

ממשקים קשורים

רוצה להתחיל לשלוח OTP?
פתח חשבון, צור טוקן והרץ את הדוגמה הראשונה תוך דקות
פתח חשבון חינם