ממשק זה מיועד לביצוע שליחה של סיסמא חד פעמית – OTP/קוד אימות ללקוח, ובדיקה האם הקוד שהוקש על ידי הלקוח תואם לקוד שנשלח, לשימוש בממשק זה יש לרכוש חבילת הודעות סמס ומומלץ גם הודעות קוליות.
בשלב הראשון יש לבצע פנייה לממשק עם מספר הטלפון והמערכת תבצע שליחה של קוד אימות ללקוח, ניתן גם לקבוע את הקוד שהמערכת תשלח באופן עצמאי.
בשלב השני יש לבצע פנייה לממשק עם מספר הטלפון והקוד שהוקש, והמערכת תחזיר תשובה האם הקוד שהוקש תואם לקוד שנשלח או לא. במידה ושלחת את הקוד באופן עצמאי בשלב הראשון, אין צורך לבצע את השלב השני מול המערכת.
הממשק תומך במגוון אפשרויות הכוללות: קביעת אורך הקוד שישלח, קביעת הטקסט בסמס, קביעת ההודעה הקולית, קביעת שפת ההודעה, הגדרה של פרק הזמן שהקוד בתוקף, קביעת הקוד באופן עצמאי, וכן קביעת מקסימום הודעות סמס או קוליות לשליחה.
הממשק מאפשר לך לקבוע האם לשלוח סמס, הודעה קולית, או לאפשר למערכת להחליט מה לשלוח באופן אוטומטי.
שים לב, המערכת שולחת בכל פעם קוד אימות אחד, באחריותך לבצע פניות נוספות לשליחת קוד אימות במידה והלקוח לא קיבל קוד אימות, על יד הצגת קישור ללקוח שיאפשר לו לקבל קוד נוסף.
השליחה מתבצעת באמצעות API בפרוטוקול HTTPS סטנדרטי המאפשר העברת הפרמטרים בשיטת GET או POST.
הכתובת לפנייה לממשק לשליחת סיסמא חד פעמית היא:
https://www.micropay.co.il/extApi/sendOtp.php
לכתובת הזו יש להוסיף את הפרמטרים המתאימים על מנת לבצע את האימות
חלק מהפרמטרים הינם חובה, וחלקם רשות
יש לשלוח את כל השמות של הפרמטרים ב- Lower Case
רשימת הפרמטרים לביצוע שליחה
token – טוקן שיצרת במערכת, עם הרשאה לשירותי סמס
ניתן לפתוח ולנהל את הטוקנים על ידי כניסה למערכת, לחיצה על האייקון הירוק למעלה משמאל, ובחירה באפשרות "טוקנים לממשקים"
חשוב לוודא שפתחת את ההרשאות לשירותי סמס ולשירותי טלפוניה, על מנת שהמערכת תוכל לשלוח הודעות סמס והודעות קוליות
phone – מספר הטלפון שאליו תרצה לשלוח את קוד האימות
יש לשלוח מספר טלפון נייח או נייד, עם ספרות בלבד
קביעת שיטת השליחה: GET או POST
ניתן לשלוח את הפרמטרים בשיטת GET או POST
במידה ואתה מבצע את השליחה בשיטת GET יש להוסיף את הפרמטר: get=1
במידה ואתה שולח בשיטת POST יש להוסיף את הפרמטר post=2
שים לב, הגדרת הפרמטר אינה משנה את שיטת השליחה, אלא רק מגדירה למערכת את סוג השליחה שבחרת
אתה צריך לבצע את השליחה בשיטה המתאימה בקוד עצמו
פרמטר חובה לפנייה הראשונה לקבלת הקוד
type – קובע כיצד לשלוח את קוד האימות ללקוח
המערכת מאפשרת לך לקבוע באופן עצמאי האם לשלוח סמס או הודעה קולית עם קוד, וניתן גם לאפשר למערכת להחליט לבד כיצד לשלוח את הקוד, האפשרויות הן:
- sms – המערכת תשלח הודעת סמס עם הקוד לאימות
- vms – המערכת תשלח הודעה קולית עם הקוד לאימות
- auto – המערכת תחליט לבד האם לשלוח סמס או הודעה קולית
בשליחה מסוג auto המערכת תבדוק אוטומטית האם המספר נייח, נייד או מספר כשר ותחליט בהתאם כיצד לשלוח את הקוד. בנוסף, במידה וקיבלנו חיווי שלילי על שליחת הסמס הראשון או שנשלחו מקסימום הודעות הסמס המורשות, המערכת תשלח אוטומטית הודעה קולית.
פרמטר חובה לפנייה השנייה לאימות הקוד שהתקבל
code – הקוד שהתקבל במספר הטלפון של הלקוח
רשימת פרמטרים נוספים אפשריים
smsfrom – קובע את זיהוי השולח של הודעת הסמס
ניתן לשלוח כל זיהוי שולח שכבר אושר בחשבון במערכת.
במידה ולא תשלח את הפרמטר הזה, ההודעה תצא עם זיהוי שולח ברירת מחדל של המערכת.
vmsfrom – קובע את זיהוי השולח של ההודעה הקולית
ניתן לשלוח כל מספר טלפון שמוגדר בחשבון במערכת להודעות קוליות או לשיחות נכנסות.
במידה ולא תשלח את הפרמטר הזה, ההודעה תצא ממספר חסוי.
codelen – קובע את אורך הקוד שישלח ללקוח, ברירת המחדל היא 5, ניתן לשלוח מספר בין 3 ל- 8
במידה ואתה משתמש בפרמטר הזה, חובה לשלוח אותו גם בפנייה הראשונה וגם בפנייה השנייה
smstext – טקסט שיופיע לפני הקוד בהודעת הסמס, טקסט ברירת המחדל הוא "קוד האימות שלך הוא: "
במידה ואתה שולח את הפרמטר הזה חובה לבצע url encode על הטקסט
vmssid – מאפשר לך לקבוע איזו הודעה קולית תושמע לפני השמעת הקוד בהודעה הקולית
יש לשלוח קוד שירות טלפוני קיים במערכת, מסוג "השמעת הודעה"
ברירת המחדל של ההודעה הקולית שהלקוח ישמע לפני הקוד היא "להלן קוד האימות המבוקש"
minvalid – קובע כמה דקות הקוד תקף מרגע שהוא נשלח ללקוח, ברירת המחדל היא 10 דקות, ניתן לשלוח מספר בין 1 ל- 60
במידה ואתה משתמש בפרמטר הזה, חובה לשלוח אותו גם בפנייה הראשונה וגם בפנייה השנייה
maxsms – מגדיר את מקסימום הודעות האימות בסמס שישלחו ללקוח בפרק הזמן שהקוד תקף, ברירת המחדל היא 2, ניתן לשלוח מספר בין 1 ל- 10
ברירת המחדל שהקוד תקף היא 10 דקות, או כפי ששלחת בפרמטר minvalid
maxvms – מגדיר את מקסימום הודעות האימות בהודעה קולית שישלחו ללקוח בפרק הזמן שהקוד תקף, ברירת המחדל היא 2, ניתן לשלוח מספר בין 1 ל- 10
ברירת המחדל שהקוד תקף היא 10 דקות, או כפי ששלחת בפרמטר minvalid
lang – פרמטר זה מאפשר לך לבחור את השפה בה תשלח הודעת הסמס ותושמע ההודעה הקולית, ניתן לבחור אחת מהאפשרויות הבאות:
he – לשפה העברית (ברירת המחדל), en – לשפה האנגלית, ar – לשפה הערבית, ru – לשפה הרוסית
precode – קביעת הקוד שישלח באופן עצמאי, ניתן לשלוח ספרות בלבד בין 3 ל- 8 ספרות.
באפשרותך לקבוע את הקוד שהמערכת תשלח באופן עצמאי, ולשמור אותו בשרת שלך, כך שאת שלב הבדיקה של הקוד תוכל לבצע מול השרת שלך, במידה ושלחת את הקוד באופן עצמאי, אין צורך לבצע את שלב בדיקת הקוד מול המערכת
webotp – בשליחת סמס, המערכת תומכת בפורמט של WebOTP שמאפשר בדיקת הקוד שמתקבל במכשיר באופן אוטומטי במכשיר הסלולר (כאשר הלקוח מבצע כניסה דרך מכשיר הסלולר שאליו נשלחה הודעת הסמס).
על מנת להשתמש באפשרות הזו, יש לשלוח בפרמטר webotp את שם הדומיין או סאב הדומיין שאליו נכנס המשתמש לבצע כניסה (ללא שום תוספות וללא http בהתחלה), לדוגמא, אם הלקוח מבצע כניסה מהאתר:
https://www.mysite.co.il/login.php
יש לרשום בפרמטר webotp את הדומיין: www.mysite.co.il
ברגע שהמערכת תזהה את הנתון, היא תוסיף אוטומטית את הפורמט הנדרש של WebOTP בסוף ההודעה, לדוגמא:
@www.mysite.co.il #123456
ניתן לקרוא מידע על הממשק של WebOTP בכתובת הבאה:
https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API
דוגמאות שליחה בשיטת GET
להלן דוגמא לפנייה ראשונה לשליחת קוד אימות
https://www.micropay.co.il/extApi/sendOtp.php?get=1&token=xxxxx&phone=0540000000&type=auto
להלן דוגמא לפנייה שנייה לבדיקת קוד אימות שהלקוח הקיש
https://www.micropay.co.il/extApi/sendOtp.php?get=1&token=xxxxx&phone=0540000000&code=xxxxx
התשובה שמתקבלת מהמערכת
המערכת תחזיר תשובה כטקסט פשוט, להלן התשובות האפשריות:
ERROR – יוחזר במידה ויש שגיאה באחד הפרמטרים או בתהליך, ולאחריו רווח ותיאור של השגיאה
CODE_SENT – יוחזר לאחר שהמערכת שלחה בהצלחה קוד ללקוח
CODE_VALID – יוחזר במידה ויש התאמה בין הקוד שהקיש הלקוח לקוד הקיים במערכת
WRONG_CODE – יוחזר במידה ואין התאמה בין הקוד שהקיש הלקוח לקוד הקיים במערכת, או שכבר פג תוקף הקוד
MAX_SENT – יוחזר במידה והלקוח קיבל את מקסימום ההודעות האפשרי בפרק הזמן שהוגדר, הלקוח יוכל לקבל קוד שוב לאחר המתנה