אימות (OTP) ב-SMS: אימות טלפון בשתי קריאות API

אימות (OTP) של Sendy הוא אימות מספר טלפון בשתי קריאות API. הראשונה שולחת למשתמש קוד בן 6 ספרות ב-SMS, השנייה בודקת את הקוד שהוא הקליד. Sendy מייצרת את הקוד, שומרת רק חתימה שלו, סופרת ניסיונות ומנהלת את התוקף. בצד שלכם נשמר רק מזהה האימות.

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

מה צריך מראש

1. טוקן API. נכנסים למפתחים ולוחצים על יצירת טוקן. רק בעלים של סביבת העבודה יכול ליצור אותו. הטוקן נשאר בשרת שלכם בלבד.
2. מזהה שליחה מאושר. הקוד יוצא מהשולח שלכם, שם מותג או מספר טלפון מאומת. אין שולח משותף של Sendy.
3. יתרת קרדיטים. כל קוד שנשלח עולה קרדיט אחד.

איך זה עובד

1. המשתמש מזין מספר טלפון. השרת שלכם קורא ל-POST /v1/verify עם המספר והשולח.
2. Sendy שולחת מיד SMS עם הקוד ומחזירה id. שומרים אותו ליד הסשן של המשתמש.
3. המשתמש מקליד את הקוד. השרת שלכם קורא ל-POST /v1/verify/{id}/check עם הקוד.
4. התשובה אומרת מה לעשות, לפי השדה status:

הבדיקה תמיד מחזירה 200 עם אובייקט האימות, כך שמספיק להסתעף לפי status.

הכללים

הכללים קבועים וזהים לכל הלקוחות, ואין מה להגדיר:

נוסח ההודעה קבוע: קוד האימות שלך ל-{שם השולח} הוא 482913. כשהשולח הוא מספר טלפון, ההודעה היא קוד האימות שלך הוא 482913. אפשר לבקש אותה באנגלית עם "locale": "en". הנוסח לא ניתן לשינוי בכוונה: הודעה שיש בה רק קוד, משולח מאומת, היא הודעת שירות ולא פרסומת, ואי אפשר להפוך אותה לכלי פישינג.

דוגמת קוד

curl:

# 1. שליחת קוד לטלפון של המשתמש
curl -X POST https://sendy.co.il/api/v1/verify \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "0501234567", "from": "MyBrand", "locale": "he"}'
# -> { "id": "...", "status": "pending", ... }  שומרים את ה-id

# 2. בדיקת הקוד שהמשתמש הקליד
curl -X POST https://sendy.co.il/api/v1/verify/VERIFICATION_ID/check \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "482913"}'

Node:

const BASE = "https://sendy.co.il/api/v1";
const headers = { Authorization: "Bearer " + process.env.SENDY_API_KEY, "Content-Type": "application/json" };

// 1. שליחת קוד (קרדיט אחד)
const start = await fetch(BASE + "/verify", {
  method: "POST",
  headers,
  body: JSON.stringify({ to: "0501234567", from: "MyBrand", locale: "he" }),
}).then((r) => r.json());
// start.id נשמר ליד הסשן של המשתמש

// 2. בדיקת הקוד (חינם)
const result = await fetch(BASE + "/verify/" + start.id + "/check", {
  method: "POST",
  headers,
  body: JSON.stringify({ code: userTypedCode }),
}).then((r) => r.json());

if (result.status === "approved") signIn(user);
else if (result.status === "pending") showError("קוד שגוי, נשארו " + result.attempts_left + " ניסיונות");
else showError("הקוד פג או ננעל, שלחו קוד חדש");

Python:

import os, requests

BASE = "https://sendy.co.il/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SENDY_API_KEY']}"}

# 1. שליחת קוד (קרדיט אחד)
start = requests.post(f"{BASE}/verify", headers=HEADERS,
                      json={"to": "0501234567", "from": "MyBrand", "locale": "he"}).json()
verification_id = start["id"]  # נשמר ליד הסשן של המשתמש

# 2. בדיקת הקוד (חינם)
result = requests.post(f"{BASE}/verify/{verification_id}/check", headers=HEADERS,
                       json={"code": user_typed_code}).json()

to מקבל מספר בפורמט מקומי (0501234567) או בינלאומי (+972501234567). from הוא אחד מהשולחים המאושרים שלכם, בדיוק כמו בשליחה רגילה. התיעוד המלא של כל שדה: Verify: start ו-Verify: check.

שליחה חוזרת וסטטוס מסירה

כפתור "שלחו לי שוב". POST /v1/verify/{id}/resend, בלי גוף, שולח קוד חדש לאותו אימות. הקוד הקודם מפסיק לעבוד, התוקף זז ל-10 דקות מעכשיו, ומונה הניסיונות לא מתאפס. אפשר אחרי 60 שניות, ועד 3 שליחות בסך הכול. כל שליחה חוזרת עולה קרדיט.

לחיצה כפולה לא מחייבת פעמיים. קריאה נוספת ל-POST /v1/verify לאותו מספר, כשהאימות שלו עוד פתוח, מחזירה את אותו id. אם עוד לא עברו 60 שניות, לא נשלח כלום ולא מחויב כלום, והתשובה כוללת retry_after. כך רענון דף או לחיצה כפולה לא שולחים שני קודים.

האם הקוד הגיע? GET /v1/verify/{id} מחזיר את מצב האימות, ובשדה delivery את גורל הקוד האחרון: sent (יצא לרשת), delivered (נמסר), failed (לא נמסר). זה שימושי כשמשתמש אומר שלא קיבל קוד. פירוט: Verify: get.

כשמשהו משתבש

שגיאה חוזרת עם קוד מזהה, כמו בכל ה-API. אלה השכיחות:

מגבלות לכל מספר קיימות כדי למנוע ניצול. הן לא אמורות להפריע למשתמש אמיתי. הרשימה המלאה של הקודים: Errors.

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

ניסיון בלי לכתוב קוד

בתפריט של Sendy יש אימות (OTP), ושם מגרש ניסוי: שולחים קוד אמיתי למספר הטלפון שאימתתם כשולח, מקלידים אותו, ורואים את האימות קורה בזמן אמת. כל שליחה עולה קרדיט אחד, ורק בעלי סביבת העבודה יכולים לשלוח משם.

באותו מקום יש יומן אימותים עם ציר זמן לכל אימות (נשלח, נמסר, ניסיונות, אומת), סקירה עם אחוז ההמרה והזמן עד אימות, והתחלה מהירה עם הקוד ב-curl, Node, Python ו-PHP, כבר עם השולח שלכם.

סוכני AI

מי שבונה עם סוכן AI יכול לתת לו לבצע את האימות ישירות. בשרת ה-MCP של Sendy יש שני כלים, start_verification ו-check_verification, על אותו טוקן API. בהתחלה המהירה בתוך המערכת יש גם פרומפט מוכן להעתקה, שמסביר לסוכן קוד איך לחבר את האימות לאפליקציה.

מחיר

קרדיט אחד לכל קוד שנשלח, והבדיקה תמיד חינם. שליחה חוזרת היא עוד קרדיט. זו אותה יתרה של כל השליחות ב-Sendy, בלי מנוי ובלי תוכנית נפרדת. המחיר בשקלים לפי החבילה, בעמוד התמחור. שליחה שנדחתה מראש, למשל מספר 056 או 059, לא מחויבת.

מתי לבנות לבד

אפשר עדיין לייצר את הקוד בעצמכם ולשלוח אותו ב-POST /v1/messages במצב תפעולי. זו הבחירה הנכונה כשצריך נוסח הודעה משלכם, ערוץ נוסף לצד SMS, או קוד שהוא לא אימות טלפון, למשל קוד איסוף שמודפס על קבלה. איך בונים את זה נכון: המדריך המלא לבניית אימות ב-SMS.

מה כל דרך דורשת, בהשוואה מלאה: לבנות לבד או להשתמש באימות מובנה.

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

מה עוד כדאי לדעת

האימות לא שולח webhooks. התוצאה חוזרת בתשובה של check, ומצב המסירה ב-GET /v1/verify/{id}. אירועי ה-webhooks מכסים רק הודעות שנשלחו ב-POST /v1/messages.

קודי אימות לא נכנסים לכרטיס איש הקשר ולא לדוחות הקמפיינים. יש להם יומן משלהם, בתוך אימות (OTP).

שאלות שחוזרות

אפשר לשנות את נוסח ההודעה, את אורך הקוד או את התוקף? לא. הם קבועים לכל הלקוחות. מי שצריך נוסח משלו בונה את האימות בעצמו על POST /v1/messages.

אפשר לשלוח קוד בוואטסאפ, בשיחה קולית או במייל? לא, האימות עובד ב-SMS בלבד.

אפשר לאמת מספר מחוץ לישראל? לא, רק מספרים ניידים ישראליים.

יש סביבת בדיקות שלא שולחת SMS אמיתי? לא. מגרש הניסוי שולח קוד אמיתי, בעלות של קרדיט, למספר המאומת שלכם.

יש מודול אימות ב-Zapier, Make או n8n? עדיין לא. החיבורים האלה שולחים הודעות רגילות. מתוך n8n אפשר לקרוא לאימות עם node של HTTP Request.

משלמים גם על בדיקה שנכשלה? לא. בדיקה תמיד חינם, בין אם הקוד נכון ובין אם לא. משלמים רק על קוד שנשלח.

הצעד הבא

עוד לא שלחתם דרך ה-API? מתחילים כאן: השליחה הראשונה דרך ה-API.