מדריך API — הפעלת שיחת אימות דו שלבי

דרישת חובה — אישור כתובת IP לפני כל שימוש

שירות זה מוגן ברמת כתובת IP. כל כתובת IP חייבת לקבל אישור מפורש ונפרד לפני שהבקשות שלה יתקבלו. בקשה שמגיעה מ-IP שאינו מורשה תידחה מיידית עם HTTP 400 — ללא כל מידע נוסף.

לאישור כתובת IP יש לפנות לצוות הטכני עם הפרטים: כתובת IP + שם המערכת / לקוח. כל IP מאושר בנפרד — אישור IP אחד אינו מעניק גישה ל-IP אחר.

תוכן עניינים

סקירה כללית פרמטרי הבקשה הגבלת שימוש (Rate Limit) תשובות השרת קודי שגיאה

סקירה כללית

ה-API מאפשר הפעלת שיחה טלפונית יוצאת למספר נבחר, תוך שליטה מלאה על זיהוי המתקשר (Caller ID). הזיהוי נבנה מ-6 ספרות שהלקוח מגדיר בכל בקשה — כך ניתן להטמיע קוד ייחודי לכל שיחה לצורך מעקב, אימות, או כל שימוש עסקי אחר.

כתובת ה-API

https://app.ipsales.co.il/ivrFilesApi.php

ניתן לשלוח בשיטת GET או POST.
פרמטרים ניתן להעביר ב-Query String, JSON body, או application/x-www-form-urlencoded.

השיחה מתנתקת מיד עם המענה.
אין אפשרות לשוחח — מטרת השיחה היא להציג למקבל את מספר ה-Caller ID בלבד. ברגע שהצד השני עונה, השיחה מסתיימת אוטומטית.

זרימת עבודה

אימות IP בדיקה מול Whitelist

→

ולידציית פרמטרים phone + cid

→

בדיקת Rate Limit 2 דק׳ / שעה

→

הפעלת השיחה CallID = 0510XXXXXX

פרמטרי הבקשה

makeCall — הפעלת שיחה יוצאת

action=makeCall

פרמטר	סוג	חובה	תיאור
action	string	חובה	ערך קבוע: `makeCall`
apiKey	string	חובה	מפתח ה-API של החשבון. מתקבל מהצוות הטכני עם הגדרת הגישה.
phone	string	חובה	מספר הטלפון שאליו תתבצע השיחה. נתמך פורמטים: `0501234567`, `+972501234567`, `00972501234567`
cid	string	חובה	6 ספרות בדיוק שיצורפו לסיומת ה-Caller ID. ה-Caller ID הסופי שיוצג למקבל השיחה: `0510` + ערך ה-cid. דוגמה: `cid=123456` → Caller ID: `0510123456`

דוגמת URL

https://app.ipsales.co.il/ivrFilesApi.php?action=makeCall&apiKey=YOUR_API_KEY&phone=0501234567&cid=111111

הגבלת שימוש (Rate Limit)

כדי למנוע ניצול לרעה של השירות, קיימת הגבלה לכל מספר טלפון בנפרד:

חלון זמן	מקסימום שיחות	תיאור
2 דקות	5 שיחות	מניעת ריצה מהירה (burst) — לא ניתן לשלוח יותר מ-5 בקשות לאותו מספר בתוך שתי דקות
שעה	15 שיחות	מגבלה שעתית כוללת לאותו מספר — גם אם הבקשות מפוזרות לאורך הזמן

ההגבלה היא לכל מספר יעד (phone) בנפרד. חריגה מאחד מהתנאים גורמת לדחיית הבקשה עם errorCode: 4.

תשובות השרת

תשובה מוצלחת

HTTP 200 — שיחה הופעלה בהצלחה

status: "OK"

errorCode: "0"

phone: מספר הטלפון המנורמל (פורמט ישראלי)

callId: ה-Caller ID שהוצג (0510 + cid)

// תשובה מוצלחת
{
  "status":    "OK",
  "errorCode": "0",
  "phone":     "0501234567",
  "callId":    "0510111111"
}

תשובת שגיאה

HTTP 200 — שגיאה לוגית (ולידציה / rate limit)

status: "ERROR"

errorCode: קוד שגיאה (ראה טבלה למטה)

note: תיאור השגיאה

// דוגמת שגיאה
{
  "status":    "ERROR",
  "errorCode": "4",
  "note":      "Rate limit exceeded — too many calls to this number"
}

קודי שגיאה

errorCode	HTTP	סיבה	פתרון
400 (ללא JSON)	400	ה-IP אינו מורשה	פנה לצוות הטכני לאישור כתובת ה-IP שלך
`1`	200	פרמטר `phone` חסר	הוסף את פרמטר `phone` לבקשה
`2`	200	פרמטר `cid` אינו 6 ספרות בדיוק	ודא ש-`cid` מכיל ספרות בלבד ואורכו 6 תווים
`3`	200	מספר הטלפון אינו תקין	בדוק את פורמט המספר — חייב להיות מספר ישראלי תקני
`4`	200	חריגה מהגבלת שימוש (Rate Limit)	המתן לפני שליחת בקשה נוספת לאותו מספר (ראה פרק Rate Limit)