# API חשבון — מספרים וחיוב API לאוטומציה **ברמת החשבון**: ניהול מספרים (DID), סיכום שימוש וחיוב, ורכישת מספרים — בכל המערכות שתחת החשבון, עם מפתח אחד. החיובים הם ברמת החשבון (כרטיס ברירת-המחדל), ולכן האימות הוא במפתח **חשבון**. > **שלוחות SIP אינן כאן.** שלוחה היא ישות ברמת *מערכת*, ולכן היא מנוהלת דרך **מפתח > ה-API של המערכת** — ראו **[מדריך API שלוחות SIP](sipApiDocs.html)** (`sipApiDocs.md`). --- ## בסיס ואימות - **כתובת בסיס:** `https://api.tlivr.com/accountApi.php` - **אימות:** מפתח החשבון באחת מהדרכים: כותרת `X-Account-Key: `, כותרת `Authorization: Bearer `, או פרמטר `accountKey=`. - **פורמט:** פרמטרים סקלריים ב-query; אפשר גם גוף JSON. תשובה תמיד JSON: `{"ok":true, ...}` / `{"ok":false,"error":""}`. > את מפתח החשבון יוצרים מתוך האיזור האישי: לשונית **"מפתחים"** (לבעל החשבון בלבד). > שם גם מפעילים את הפעולות בתשלום וקובעים תקרה חודשית. ### שערי-בטיחות - **קריאה** (רשימות/סיכומים) — פתוחה תמיד עם מפתח תקף. - **כתיבה ללא חיוב** (יעד מספר, העברת מספר) — דורשת הפעלת *"כתיבה דרך API"* → אחרת `api_writes_disabled`. - **קנייה בתשלום** (`number_buy`) — דורשת בנוסף *"התר קניית מספרים"* **וגם** תקרה חודשית שנקבעה; חריגה → `api_cap_exceeded`. ### זרימת קליטת סוכן חדש (שני מפתחות) 1. **שלוחת SIP** — `sipCreate` דרך **מפתח המערכת** (ראו [sipApiDocs](sipApiDocs.html)). 2. **מספר** — `number_buy` דרך **מפתח החשבון** (כאן). 3. **יעד** — `number_target` (כאן): מכוונים את המספר אל השלוחה הפנימית שנוצרה. --- ## זהות, מערכות ושימוש ### `me` ``` GET /accountApi.php?action=me ``` ```json { "ok":true, "account":{"id":1234,"name":"הסעות ישראל בע״מ"}, "systems_count":2, "has_charge_card":1, "api":{"enabled":1,"numbers_purchase":1,"monthly_cap":500,"month_spent":84.5} } ``` ### `systems` ``` GET /accountApi.php?action=systems ``` ```json { "ok":true, "systems":[ {"system_id":41,"kind":"pbx","label":"מוקד ראשי","primary_number":"0765674900","is_primary":1} ]} ``` `system_id` הוא המזהה שבו משתמשים בכל שאר הפעולות (וגם במפתח המערכת ל-SIP). ### `usage` פר-מערכת (חבילה, חיוב חודשי, ארנק, חריגה, מספרים, שלוחות) + צבירה וחיובי החודש. ``` GET /accountApi.php?action=usage # כל המערכות GET /accountApi.php?action=usage&system_id=41 ``` ```json { "ok":true, "systems":[{"system_id":41,"label":"מוקד ראשי","plan":"בסיס","monthly":99,"wallet":12.5,"overage":0,"numbers":3,"extensions":8}], "total_monthly":99, "charged_this_month":183.0, "api_spent_this_month":84.5, "api_monthly_cap":500 } ``` --- ## מספרים (DID) ### `numbers` ``` GET /accountApi.php?action=numbers # כל המערכות GET /accountApi.php?action=numbers&system_id=41 ``` ```json { "ok":true, "numbers":[ {"number":"0765674900","system_id":41,"is_primary":1,"label":"ראשי","status":"in_use","target_extension":""}, {"number":"0765674901","system_id":41,"is_primary":0,"label":"סוכן דני","status":"in_use","target_extension":"201"} ]} ``` `target_extension` = היעד הפנימי שאליו המספר מנותב (ריק = תפריט/עץ ראשי). ### `number_groups` ``` GET /accountApi.php?action=number_groups ``` קבוצות שאפשר לקנות מהן מספר, עם מחיר ומלאי פנוי (`free_count`) ו-`id` לשימוש בקנייה. ### `number_options` ``` GET /accountApi.php?action=number_options&system_id=41&group_id=3 ``` ```json { "ok":true, "items":[{"number":"0765674950","monthly":15,"setup":0,"now":9.68}], "monthly":15, "setup":0, "prorated_now":9.68 } ``` `now` = הסכום שייגבה כעת (יחסי ליום בחודש + הקמה). ### `number_buy` *(בתשלום · דורש הפעלה + תקרה)* חיוב מיידי לכרטיס ברירת-המחדל (יחסי-לחודש + הקמה), שיוך המספר למערכת, ופתיחת חיוב חודשי — בדיוק כמו קנייה באתר. ``` POST /accountApi.php?action=number_buy Content-Type: application/json { "system_id":41, "group_id":3, "number":"0765674950" } ``` ```json { "ok":true, "number":"0765674950", "charged":9.68, "monthly":15, "setup":0 } ``` שגיאות: `api_writes_disabled`, `api_purchase_disabled`, `api_cap_not_set`, `api_cap_exceeded`, `number_not_available`, `card_required`. ### `number_target` *(כתיבה)* מכוון מספר אל **שלוחה / צומת פנימי** במערכת (למשל: כל מספר סוכן → השלוחה שלו). ``` POST /accountApi.php?action=number_target { "number":"0765674901", "extension":"201" } // "" לניקוי → עץ ראשי ``` ### `number_move` *(כתיבה)* ``` POST /accountApi.php?action=number_move { "number":"0765674901", "to_system_id":57 } ``` --- ## סיכום פעולות | פעולה | שיטה | סוג | תיאור | |---|---|---|---| | `me` | GET | קריאה | זהות החשבון + סטטוס API | | `systems` | GET | קריאה | רשימת המערכות | | `usage` | GET | קריאה | סיכום שימוש פר-מערכת + חשבון | | `numbers` | GET | קריאה | המספרים + סטטוס ויעד | | `number_groups` | GET | קריאה | קבוצות זמינות לרכישה | | `number_options` | GET | קריאה | מספרים פנויים + מחיר | | `number_buy` | POST | בתשלום | קניית מספר + שיוך | | `number_target` | POST | כתיבה | יעד פנימי למספר | | `number_move` | POST | כתיבה | העברת מספר בין מערכות | לניהול **שלוחות SIP** (יצירה/עריכה/מחיקה/רשימה/זיהוי-יוצא) — ראו **[מדריך API שלוחות SIP](sipApiDocs.html)**, במפתח ה-API של המערכת.