מדריך API — Click‑to‑Call (חיוג בלחיצה)

תוכן עניינים

סקירה כללית פרמטרי הבקשה סוגי מספרי יעד תשובות השרת קודי שגיאה

סקירה כללית

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

כתובת ה‑API

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

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

הסוכן מזין רק את מספר השלוחה הפנימי שלו (לדוגמה 101). אין צורך לדעת את שם המשתמש הטכני של השלוחה במרכזיה — המערכת מתרגמת אותו אוטומטית לפי החשבון של מפתח ה‑API.

זרימת עבודה

אימות apiKey זיהוי החשבון

→

הרשאת שלוחה שייכת לחשבון?

→

ולידציית יעד מספר תקין?

→

חיבור השיחה שלוחה ↔ יעד

חוויית המשתמש מצד הסוכן

הסוכן לוחץ על כפתור "חייג" ב‑CRM שלו (לדוגמה ליד מספר טלפון של לקוח).
הטלפון של הסוכן מצלצל מיד.
הסוכן מרים — המרכזיה מחייגת ליעד ומחברת אותם.
על מסך הטלפון של הסוכן מופיע שם היעד (אם נשלח targetName).

פרמטרי הבקשה

click2call — חיוג בלחיצה

action=click2call

פרמטר	סוג	חובה	תיאור
action	string	חובה	ערך קבוע: `click2call`
apiKey	string	חובה	מפתח ה‑API של החשבון. מתקבל מהצוות הטכני עם הגדרת הגישה.
extension	string	חובה	מספר השלוחה הפנימי של הסוכן (למשל `101`). חייב להיות שלוחה ששייכת לחשבון של ה‑apiKey ששלחת — אחרת הבקשה תידחה (errorCode 4).
target	string	חובה	מספר היעד לחיוג. ראה פרק סוגי מספרי יעד. דוגמה `0501234567`, `205`, `0990880101`
targetName	string	אופציונלי	שם תצוגה שיופיע על מסך הטלפון של הסוכן (לדוגמה שם הלקוח מה‑CRM). אם לא נשלח — יוצג מספר היעד.
ringSec	integer	אופציונלי	כמה שניות להמתין לתשובת השלוחה לפני ביטול השיחה. ברירת מחדל: `30`. טווח: `5–120` שניות.

דוגמת URL (GET)

https://app.ipsales.co.il/ivrFilesApi.php?action=click2call&apiKey=YOUR_API_KEY&extension=101&target=0501234567&targetName=%D7%99%D7%95%D7%A1%D7%A3

דוגמת POST (JSON body)

POST https://app.ipsales.co.il/ivrFilesApi.php
Content-Type: application/json

{
  "action":     "click2call",
  "apiKey":     "YOUR_API_KEY",
  "extension":  "101",
  "target":     "0501234567",
  "targetName": "יוסף לקוח",
  "ringSec":    30
}

דוגמת cURL

curl -X POST "https://app.ipsales.co.il/ivrFilesApi.php" \
     -H "Content-Type: application/json" \
     -d '{
       "action":     "click2call",
       "apiKey":     "YOUR_API_KEY",
       "extension":  "101",
       "target":     "0501234567",
       "targetName": "יוסף לקוח"
     }'

סוגי מספרי יעד נתמכים

הפרמטר target מקבל שלושה סוגי מספרים — המערכת מזהה אוטומטית באיזה סוג מדובר:

1. מספר טלפון ישראלי

מספר ישראלי תקין — סלולרי או קווי. נתמכים פורמטים שונים, וכולם מנורמלים אוטומטית לפורמט ישראלי תקני.

נתמך 0501234567 +972501234567 00972501234567

מספרים מחו"ל לא נתמכים. בקשה למספר זר תידחה עם errorCode: 3.

2. שלוחה פנימית במרכזיה

מספר שלוחה פנימי בן 3 ספרות בטווח 100–999 — לחיבור שיחה בין שתי שלוחות באותה מרכזיה.

דוגמה 205 317

3. מספר תצוגה של שלוחה

מספר חיוג מלא של שלוחה בפורמט 099088 + ספרות. שימושי במצבים שבהם נדרש לחייג ישירות לזיהוי המלא של השלוחה ולא דרך הסיומת הקצרה.

דוגמה 0990880101 0990880205

אם target אינו תואם לאף אחד משלושת הסוגים — הבקשה נדחית עם errorCode: 3 ("מספר טלפון ישראלי לא תקין").

תשובות השרת

תשובה מוצלחת

HTTP 200 — בקשת חיוג נשלחה בהצלחה למרכזיה

status: "OK"

errorCode: 0

callId: מזהה ייחודי של השיחה (לשמירה ב‑CRM לקישור עם הקלטות)

extension: השלוחה שצולצלה

target: מספר היעד המנורמל

targetName: שם התצוגה (אם נשלח)

// תשובה מוצלחת
{
  "status":     "OK",
  "errorCode":  0,
  "callId":     "a1b2c3d4-...",
  "extension":  "101",
  "target":     "0501234567",
  "targetName": "יוסף לקוח"
}

מומלץ לשמור את ה‑callId בכרטיס הלקוח / רישום הפעילות ב‑CRM — זה המזהה שמקשר אחר‑כך לרשומת ההקלטה ולפרטי השיחה במערכת.

תשובת שגיאה

HTTP 200 — שגיאה לוגית (ולידציה / הרשאה / זמינות)

status: "ERROR"

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

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

// דוגמת שגיאה — שלוחה לא נמצאה
{
  "status":    "ERROR",
  "errorCode": 4,
  "note":      "שלוחה לא נמצאה או לא שייכת לחשבון"
}

קודי שגיאה

errorCode	סיבה	פתרון
`1`	פרמטר `extension` חסר	הוסף את מספר השלוחה לבקשה
`2`	פרמטר `target` חסר	הוסף את מספר היעד לבקשה
`3`	מספר היעד אינו תקין	ודא ש‑`target` הוא מספר ישראלי תקין, שלוחה 100–999, או 099088 + ספרות
`4`	השלוחה לא נמצאה או לא שייכת לחשבון	בדוק שמספר השלוחה קיים אצלך, ושה‑`apiKey` שייך לחשבון שמחזיק בה
`6`	המרכזיה אינה זמינה / Timeout	בעיה זמנית. נסה שנית; אם נמשך — פנה לתמיכה הטכנית
400 / 401 / 402 / 404	שגיאה שהוחזרה מהמרכזיה (חסר שדה במרכזיה, טוקן פנימי, שלוחה לא רשומה במרכזיה, או כשל פנימי)	בד"כ זמני. אם חוזר באופן עקבי — פנה לתמיכה הטכנית עם ה‑`callId` והשעה

טיפ למפתחים: בודקים את status === "OK" בתשובה — אל תסתמכו רק על HTTP 200, כי שגיאות לוגיות מוחזרות גם הן בקוד 200 עם status: "ERROR".