# API שלוחות SIP — ברמת מערכת יצירה וניהול מלא של שלוחות SIP (חשבונות רישום לטלפון רך/מכשיר) דרך API: רשימה, שליפה, יצירה, עריכה, מחיקה, החלפת סיסמה, בדיקת מכסה, וזיהויי-יוצא כולל אימות טלפון חדש. שלוחה היא ישות **ברמת מערכת** — ולכן האימות הוא במפתח ה-API של **המערכת** (לא מפתח החשבון). > מפתח ה-API של המערכת מנוהל בתוך המערכת עצמה. למספרים, חיוב ורכישה — ראו > **[מדריך API חשבון](accountApiDocs.html)** (`accountApiDocs.md`), עם מפתח החשבון. --- ## בסיס ואימות - **כתובת בסיס:** `https://api.tlivr.com/ivrFilesApi.php` - **אימות:** `apiKey=` (פרמטר GET או שדה POST). המפתח מזהה את המערכת — כל השלוחות שייכות אוטומטית למערכת של המפתח, ואין גישה לשלוחות של מערכת אחרת. - **פורמט:** GET עם query, או POST (form / JSON). תשובה תמיד JSON. - **מעטפת תשובה:** הצלחה `{"status":"OK", ...}` · שגיאה `{"status":"ERROR","errorCode":,"note":""}`. ## אובייקט שלוחה | שדה | תיאור | |---|---| | `id` | מזהה השלוחה — משמש לכל הפעולות על שלוחה קיימת | | `name` | שם תצוגה (נציג/עמדה) | | `extension` | שלוחה פנימית במערכת (2–6 ספרות) — זה המספר שאליו מכוונים מספרים ותפריטים | | `display_number` | זיהוי-יוצא בשיחות מהשלוחה (ריק = ברירת המחדל של המערכת) | | `username` / `password` / `server` | פרטי החיבור להזנה בטלפון הרך / במכשיר (Zoiper, Linphone, MicroSIP, טלפון IP) | | `online` | `1` = המכשיר רשום כעת (רישום ב-45 השניות האחרונות), `0` = לא רשום | ## מכסת שלוחות לכל מערכת מכסת שלוחות. ברירת המחדל: **2** שלוחות ללא חבילת שיחות-יוצאות פעילה, **10** עם חבילה כזו. לפי בקשה ניתן לקבוע למערכת מכסה אחרת או לבטל את המכסה — פנו לתמיכה. את המצב העדכני מחזירות הפעולות `sipLimit` ו-`sipList`: ```json "limit": { "used":3, "max":10, "unlimited":false, "remaining":7 } ``` כשאין הגבלה: `"max":null, "unlimited":true, "remaining":null`. מחיקת שלוחה משחררת מקום במכסה מיד. --- ## הפעולות | פעולה | סוג | תיאור | |---|---|---| | `sipList` | קריאה | כל השלוחות + מצב המכסה | | `sipGet` | קריאה | שלוחה אחת לפי `id` | | `sipLimit` | קריאה | מצב המכסה בלבד | | `sipCreate` | כתיבה | יצירת שלוחה | | `sipUpdate` | כתיבה | עריכה (רק השדות שנשלחו) | | `sipDelete` | כתיבה | מחיקה | | `sipResetPassword` | כתיבה | סיסמה חדשה לשלוחה | | `sipCallerIdOptions` | קריאה | זיהויי-יוצא מותרים | | `sipCallerIdVerifyStart` | כתיבה | שליחת קוד אימות לטלפון שרוצים להוסיף כזיהוי-יוצא | | `sipCallerIdVerifyConfirm` | כתיבה | אישור הקוד והוספת הטלפון | ### רשימת שלוחות — `sipList` ``` GET /ivrFilesApi.php?apiKey=KEY&action=sipList ``` ```json { "status":"OK", "limit":{"used":1,"max":2,"unlimited":false,"remaining":1}, "extensions":[ {"id":88,"name":"דני","extension":"201","display_number":"0765674901", "username":"…","password":"…","server":"172.104.203.87","online":1} ]} ``` ### שלוחה אחת — `sipGet` ``` GET /ivrFilesApi.php?apiKey=KEY&action=sipGet&id=88 ``` ```json { "status":"OK", "extension":{"id":88,"name":"דני","extension":"201", "…":"…", "online":1} } ``` | פרמטר | חובה | תיאור | |---|---|---| | `id` | חובה | מזהה השלוחה | ### מצב המכסה — `sipLimit` ``` GET /ivrFilesApi.php?apiKey=KEY&action=sipLimit ``` ```json { "status":"OK", "limit":{"used":1,"max":2,"unlimited":false,"remaining":1} } ``` מומלץ לבדוק לפני יצירה אוטומטית בכמויות. ### יצירת שלוחה — `sipCreate` ``` POST /ivrFilesApi.php?apiKey=KEY&action=sipCreate { "name":"סוכן חדש", "extension":"202", "callerId":"0765674901" } ``` ```json { "status":"OK", "extension":{"id":91,"server":"172.104.203.87","username":"…","password":"…","extension":"202"} } ``` | פרמטר | חובה | תיאור | |---|---|---| | `name` | חובה | שם תצוגה (נציג/עמדה) | | `extension` | חובה | שלוחה פנימית, 2–6 ספרות, ייחודית במערכת | | `callerId` | רשות | זיהוי-יוצא — מספר של המערכת או טלפון מאומת (ראו `sipCallerIdOptions`). שם חלופי: `display_number` | ה-`id` שמוחזר הוא המזהה לכל הפעולות הבאות. אם המכסה מלאה — שגיאה `limit_reached`. ### עריכת שלוחה — `sipUpdate` ``` POST /ivrFilesApi.php?apiKey=KEY&action=sipUpdate { "id":91, "name":"דני כהן" } ``` ```json { "status":"OK", "id":91, "extension":{"id":91,"name":"דני כהן","extension":"202", "…":"…"} } ``` | פרמטר | חובה | תיאור | |---|---|---| | `id` | חובה | מזהה השלוחה | | `name` | רשות | שם חדש (לא ריק) | | `extension` | רשות | שלוחה פנימית חדשה (2–6 ספרות, ייחודית) | | `callerId` | רשות | זיהוי-יוצא חדש; מחרוזת ריקה `""` = ביטול זיהוי ייעודי | **עדכון חלקי:** רק השדות שנשלחו משתנים; כל השאר נשאר כפי שהיה. התשובה מחזירה את השלוחה המעודכנת. ### מחיקת שלוחה — `sipDelete` ``` POST /ivrFilesApi.php?apiKey=KEY&action=sipDelete { "id":91 } ``` ```json { "status":"OK", "id":91 } ``` המכשיר הרשום מפסיק לעבוד, ומקום מתפנה במכסה. ניתובים שכוונו לשלוחה הפנימית יש לעדכן. ### החלפת סיסמה — `sipResetPassword` ``` POST /ivrFilesApi.php?apiKey=KEY&action=sipResetPassword { "id":91 } ``` ```json { "status":"OK", "extension":{"id":91,"server":"172.104.203.87","username":"…","password":"<חדשה>","extension":"202"} } ``` לשימוש כשיש חשש שהסיסמה דלפה, או בהחלפת עובד. שם המשתמש, השלוחה הפנימית, הזיהוי-היוצא והניתובים נשארים; רק הסיסמה מתחלפת. מכשיר שרשום עם הסיסמה הישנה יתנתק ברענון הרישום הבא — יש להזין בו את הסיסמה החדשה. ### זיהויי-יוצא מותרים — `sipCallerIdOptions` ``` GET /ivrFilesApi.php?apiKey=KEY&action=sipCallerIdOptions ``` ```json { "status":"OK", "system_numbers":[{"number":"0765674900","label":"ראשי"}], "verified":["0501234567"] } ``` `system_numbers` = מספרי המערכת (מותרים תמיד). `verified` = טלפונים שאומתו. כל ערך משתי הרשימות חוקי כ-`callerId` ב-`sipCreate`/`sipUpdate`. ### אימות טלפון לזיהוי-יוצא — `sipCallerIdVerifyStart` + `sipCallerIdVerifyConfirm` כדי להשתמש בטלפון שאינו מספר של המערכת (למשל הנייד של הסוכן) כזיהוי-יוצא, יש לאמת אותו פעם אחת. **שלב 1 — שליחת קוד:** ``` POST /ivrFilesApi.php?apiKey=KEY&action=sipCallerIdVerifyStart { "phone":"0501234567" } ``` ```json { "status":"OK", "sentTo":"050•••••67" } ``` הטלפון מקבל שיחה קצרה — אין צורך לענות; **6 הספרות האחרונות של המספר המתקשר הן הקוד**. הקוד תקף ל-10 דקות. מגבלה: בקשה אחת לדקה ועד 12 ביום לאותו טלפון. **שלב 2 — אישור:** ``` POST /ivrFilesApi.php?apiKey=KEY&action=sipCallerIdVerifyConfirm { "phone":"0501234567", "code":"123456" } ``` ```json { "status":"OK", "phone":"0501234567", "system_numbers":[…], "verified":["0501234567"] } ``` עד 5 ניסיונות לקוד; אחר כך יש לשלוח קוד חדש. מעכשיו אפשר להגדיר את הטלפון כ-`callerId`. --- ## קודי שגיאה | errorCode | note | משמעות | |---|---|---| | 1 | `limit_reached` | הגעת למכסת השלוחות של המערכת (ראו `sipLimit`) | | 2 | `name_required` | חסר שם / שם ריק | | 3 | `extension_invalid` | שלוחה פנימית לא תקינה (2–6 ספרות) | | 4 | `extension_taken` | השלוחה הפנימית כבר תפוסה במערכת | | 5 | `cid_not_allowed` | זיהוי-יוצא שאינו מספר של המערכת ולא אומת | | 6 | `not_found` | השלוחה לא קיימת / לא שייכת למערכת זו | | 7 | `no_free_extension` | אין כרגע חשבון SIP פנוי — פנו לתמיכה | | 8 | `system_not_resolved` | המערכת לא זוהתה | | 9 | `id_required` | חסר `id` | | 10 | `phone_invalid` | מספר טלפון לא תקין | | 11 | `rate_limited` | יותר מדי בקשות קוד לטלפון זה — נסו מאוחר יותר | | 12 | `send_failed` | שליחת הקוד נכשלה — נסו שוב | | 13 | `missing_fields` | חסר `phone` או `code` | | 14 | `otp_not_found` | אין קוד פעיל לטלפון — שלחו קוד | | 15 | `otp_expired` | הקוד פג — שלחו קוד חדש | | 16 | `otp_locked` | יותר מדי ניסיונות — שלחו קוד חדש | | 17 | `otp_wrong` | קוד שגוי | | 18 | `rotate_unsupported` | לא ניתן להחליף סיסמה לשלוחה זו — פנו לתמיכה | | 19 | `rotate_failed` | החלפת הסיסמה נכשלה — נסו שוב | | 99 | `internal_error` | תקלה פנימית — נסו שוב או פנו לתמיכה | > פרטי החיבור (`password`) נחשפים רק דרך ה-API של המערכת ולבעליה — אין לשתף אותם. --- ## זרימת קליטת סוכן חדש 1. **`sipLimit`** — וידוא שיש מקום במכסה. 2. **`sipCreate`** (כאן, מפתח המערכת) — מקבלים `id`/`username`/`password`/`server`, מזינים אצלכם לסוכן. 3. **`number_buy`** ([מדריך API חשבון](accountApiDocs.html), מפתח החשבון) — הקצאת מספר למערכת. 4. **`number_target`** (מדריך API חשבון) — כיוון המספר לשלוחה שנוצרה (`extension`). 5. אימות רישום: `sipGet` → `online:1`. ## עזיבת סוכן - להעביר את העמדה לסוכן אחר: `sipUpdate` (שם חדש) + `sipResetPassword` — המספר והניתובים נשמרים. - לסגור את העמדה: `sipDelete`.