# API עבור סוכנויות

כסוכנות, באפשרותך להשתמש באותו REST API שבו משתמשים הלקוחות שלך, אך להפנות בקשות בודדות לאחד מ**חשבונות המשנה** המנוהלים על ידך במקום לחשבון שלך. זה מאפשר לך לבנות כלים שמבצעים אונבורדינג (onboarding) ללקוח מקצה לקצה — יצירת הקמפיינים שלו, אימון ה-AI שלו על בסיס ידע, ייבוא אנשי הקשר שלו, חיבור ערוצי ההודעות שלו ורכישת מספרי טלפון — הכל מבלי להיכנס ידנית לכל חשבון משנה.

דף זה מכסה רק את ההתנהגות הספציפית לסוכנויות: כיצד לפעול בשם חשבון משנה באמצעות הפרמטר `sub_account_id`. עבור היסודות (יצירת מפתח, אימות, כתובת URL בסיסית, פורמט שגיאות, מגבלות קצב), התחל עם המדריך [גישה ל-API](../integrations/api-access.md). כל מה שכתוב שם תקף גם כאן — אתה מבצע אימות עם מפתח ה-API של **חשבון הסוכנות שלך**.

::: note
**הערה:** דף זה הוא טכני. אם אינך מפתח, שתף אותו עם האדם שמבצע עבורך את האינטגרציה.
:::


***

## כיצד עובדת הפעולה "בשם"

כברירת מחדל, כל בקשת API פועלת על החשבון שבבעלותו מפתח ה-API — חשבון הסוכנות שלך. כדי לפעול במקום זאת על חשבון לקוח מנוהל, הוסף לבקשה את הפרמטר האופציונלי `sub_account_id`, והגדר אותו למזהה החשבון של אותו לקוח.

- **השמטת `sub_account_id`** → הבקשה פועלת על חשבון הסוכנות שלך.
- **הכללת `sub_account_id`** → הבקשה פועלת על חשבון המשנה ההוא, אך רק לאחר שהפלטפורמה מאשרת שחשבון המשנה אכן שייך לך.

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

### היכן למקם אותו

- **נקודות קצה מסוג GET / DELETE** ← העבר אותו כפרמטר שאילתה: `?sub_account_id=THE_SUB_ACCOUNT_ID` (לצד ה-`apiKey` שלך, אם אתה מבצע אימות באמצעות שאילתה).
- **נקודות קצה מסוג POST / PUT / PATCH** ← כלול אותו בגוף הבקשה בפורמט JSON כ-`"sub_account_id": "THE_SUB_ACCOUNT_ID"`.
- **עוזרי AI** ← אין צורך להגדיר דבר. ה-[שרת MCP](../integrations/connect-ai-clients.md) נושא את אותה הגדרה בכלי הקריאה שלו, כך שחיבור אחד עם מפתח הסוכנות שלך יכול לדווח על כל לקוח: פשוט ציין את שם הלקוח בבקשה שלך ("כמה אנשי קשר יש ל-Bella's Bistro?"). פעולות כתיבה זמינות גם הן: כל נקודת קצה שמקבלת `sub_account_id` נחשפת ככלי, כך שתוכל ליצור, לשנות ולשלוח בשם הלקוח מאותו חיבור.

### מציאת מזהה של חשבון משנה

ה-`sub_account_id` הוא המזהה הייחודי של חשבון הלקוח. ניתן לקבל את רשימת חשבונות המשנה שלכם ואת המזהים שלהם מנקודות הקצה של ה-API מסוג **SubAccounts** (ראו את המדריך [חשבונות משנה](sub-accounts.md)) או מדף **חשבונות משנה** בסרגל הצד.

***

## הבעלות מאומתת תמיד

כאשר אתה מעביר `sub_account_id`, הפלטפורמה בודקת שהחשבון הוא חשבון משנה אמיתי **ושהוא** שייך לסוכנות שלך. רק אז הבקשה עוברת.

אם המזהה אינו מוכר, אינו חשבון משנה, או שייך לסוכנות אחרת, הבקשה תיכשל עם תגובת **`404`**:

```json
{
  "success": false,
  "error_code": 404,
  "error": "Sub-account not found."
}
```

> **למה 404 ולא 403?** תגובת "אסור" (forbidden) תגלה לגורם חיצוני שהמזהה קיים אך אינו שייך לו. החזרת אותו `404` עבור "לא קיים" ו-"לא שייך לך" מבטיחה שלא ניתן להשתמש בנקודת הקצה כדי לגלות אילו מזהי חשבונות שייכים לסוכנויות אחרות. התייחס ל-`404` כאן כאל "זה אינו חשבון משנה שאתה מנהל".

***

## היכן `sub_account_id` נתמך

`sub_account_id` מתקבל כמעט בכל נקודת קצה של **משאב** — כל קריאה שיוצרת, קוראת, מעדכנת או מוחקת נתונים השייכים לחשבון. בפועל, באפשרותך להקצות ולהריץ את כל ההגדרה של חשבון משנה באמצעות מפתח הסוכנות שלך:

- **הגדרת AI** — קמפיינים, סוכנים, שאלות נפוצות (FAQs), מקורות בסיס ידע (סריקת אתרים **ו**העלאת מסמכים), קבוצות בסיס ידע, שידורים, פונקציות מותאמות אישית, שרתי MCP
- **אנשי קשר ו-CRM** — אנשי קשר (כולל ייבוא), רשימות, תגיות, משימות, עסקאות, פגישות, אירועים
- **ערוצים ומספרים** — חיבור WhatsApp / WhatsApp Web / Telegram / Instagram & Messenger / LINE, חיפוש / רכישה / ניהול מספרי טלפון, תבניות WhatsApp, ניתוב ערוצים
- **הודעות ותוכן** — שליחת הודעות, סשנים של צ'אט, ייצוא צ'אטים, סיכומים יומיים
- **הגדרות ואינטגרציות** — Webhooks, הגדרות ווידג'ט צ'אט, הגדרות White-label, הגדרות BYOK SMS והגדרות חשבון אחרות, ניתוח נתונים (Analytics)

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

### היכן זה לא חל

מספר נקודות קצה הן ברמת הסוכנות או מופנות לעצמן ומתעלמות מ-`sub_account_id`:

- **ניהול תתי-החשבונות עצמם** — נקודות הקצה של SubAccounts (יצירה / רשימה / עדכון של תת-חשבון) ונקודת הקצה של מגבלת ההוצאות BYOK כבר מציינות את שם תת-החשבון בנתיב ה-URL שלהן. [נקודות הקצה של תמחור ומדיניות](#set-per-client-ai-pricing-and-policy) ו[נקודות הקצה של ניטור צ'אט](#read-a-sub-accounts-conversations) פועלות לפי אותו דפוס.
- **העתקת סוכן בין חשבונות** — `POST /v1/subaccounts/agents/copy` מציין את שני החשבונות עצמם, כאשר הוא לוקח את חשבון היעד כ-`targetUserId`. ראו את [הדוגמה המעשית](#worked-example-ship-a-template-agent-into-every-new-client) להלן. (ה-`POST /v1/subaccounts/campaigns/copy` הישן יותר פועל באותה דרך אך הוא אינו מומלץ לשימוש יחד עם שאר ה-[Campaigns API](../api/campaigns.md).)
- **התאמת קרדיטים, ושני סיכומי הנתונים ברמת הסוכנות** — [`POST /v1/subaccounts/credits`](#grant-or-deduct-credits-directly) מזהה את תת-החשבון באמצעות `email` במקום זאת; [`GET /v1/subaccounts/credit-usage`](#read-credit-usage-and-campaign-health-across-your-book) ו-`GET /v1/subaccounts/campaign-status` מדווחים על כל תת-חשבון בבת אחת, כך שאין חשבון יחיד למקד אליו.
- **החשבון של הסוכנות שלכם** — ניהול מפתחות API, דיווח על שימוש בסוכנות, ניהול צוות ו[דרגות התמחור](#manage-your-pricing-tiers-over-the-api) שלכם פועלים תמיד על חשבון הסוכנות שלכם.
- **Webhooks של הודעות נכנסות** — נקודות קצה שמערכות חיצוניות שולחות אליהן הודעות (*post*) קשורות לחשבון שהגדיר אותן באמצעות פרטי הגישה שלו, כך שאין מה להפנות מחדש.

> הרשימה המעודכנת תמיד, הניתנת לקריאה על ידי מכונה, של הפרמטרים שכל נקודת קצה מקבלת נמצאת בהפניית ה-API בלוח הבקרה שלכם (**הגדרות ← אינטגרציות ← מפתח API**) ובמפרט ה-OpenAPI בכתובת `GET /v1/docs/openapi.yaml`. אנו מפיצים שינויי API לעיתים קרובות — התייחסו אליהם כמקור האמת.

::: master-only
<figure><img src="../.gitbook/assets/v2-api-access-key-section.png" alt="דף הגדרות מפתח API עם מפתח מוסתר ובקרת יצירה מחדש"><figcaption><p>הגדרות → אינטגרציות → מפתח API — המפתח של הסוכנות שלכם נמצא כאן, לצד הקישור למדריך ה-API המלא.</p></figcaption></figure>
:::

***

## דוגמה מעשית: חיבור Instagram ו-Messenger עבור חשבון משנה

חיבור Instagram ו-Messenger הוא תהליך מבוסס דפדפן. אתה מתחיל אותו באמצעות ה-API, מעביר את כתובת ה-URL להסכמה שחזרה ללקוח (או פותח אותה עבורו), ממתין שהוא יאשר בדפדפן שלו, ואז בוחר איזה דף לחבר — כל זאת תוך מיקוד בחשבון המשנה שלו באמצעות `sub_account_id`.

### שלב 1 — התחלת החיבור

קרא לנקודת הקצה של החיבור עם ה-`sub_account_id` של הלקוח בגוף הבקשה. לא נשלחים כאן אישורים; הפלטפורמה מחזירה כתובת URL להסכמה שהלקוח חייב לפתוח בדפדפן, בתוספת אסימון מתאם (correlation token) חד-פעמי.

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sub_account_id": "abc123def456"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/channels/meta/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sub_account_id: "abc123def456",
  }),
});

const data = await res.json();
// data.oauth_url -> open this in the client's browser
```

**Python**

```python
import requests

res = requests.post(
    "https://api.dmchamp.com/v1/channels/meta/connect",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "sub_account_id": "abc123def456",
    },
)

data = res.json()
# data["oauth_url"] -> open this in the client's browser
```

**תגובה:**

```json
{
  "success": true,
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "8sFq2yV0kQ7m4n1pZr3tWb6cXe9hJl2aD5gK7uN0oI",
  "expires_at": "2026-06-10T12:30:00.000Z"
}
```

שלח את הלקוח ל-`oauth_url` בדפדפן כדי לאשר. ה-`state_token` מתאם בין ניסיון זה והוא סוד לטווח קצר — אל תתעד אותו בלוגים. הניסיון יפוג ב-`expires_at`; אם פג תוקפו, התחל מחדש.

### שלב 2 — ביצוע סקר (Polling) עד לטעינת הדפים

לאחר שהלקוח מאשר, בצעו תשאול (polling) לנקודת הקצה של הסטטוס (עם אותו `sub_account_id`, הפעם כפרמטר שאילתה) עד להופעת הדפים הניתנים לחיבור.

**cURL**

```bash
curl "https://api.dmchamp.com/v1/channels/meta/status?apiKey=YOUR_API_KEY&sub_account_id=abc123def456"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.dmchamp.com/v1/channels/meta/status?sub_account_id=abc123def456",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);

const data = await res.json();
// Wait until data.status === "pages_loaded", then read data.pages
```

**Python**

```python
import requests

res = requests.get(
    "https://api.dmchamp.com/v1/channels/meta/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"sub_account_id": "abc123def456"},
)

data = res.json()
# Wait until data["status"] == "pages_loaded", then read data["pages"]
```

**תגובה:**

```json
{
  "success": true,
  "status": "pages_loaded",
  "pages": [
    {
      "id": "1098765432101234",
      "name": "Acme Studio",
      "category": "Hair Salon",
      "instagram_business_account": {
        "id": "17841400000000000",
        "username": "acme.studio"
      }
    }
  ],
  "selected_page": null
}
```

השדה `status` עובר דרך `pending` → `token_received` → `pages_loaded` → `connected`. המתן ל-`pages_loaded` לפני בחירת דף. שני מצבי שגיאה סופיים יכולים להופיע גם במקום התקדמות: `failed` ו-`expired` (הלקוח סירב להסכמה, או שחלף חלון הזמן של כ-30 דקות של אסימון המצב) — שדה `reason` כלול כאשר אחד מהם מתרחש. הפסק את התשאול והתחל מחדש בשלב 1 אם אתה רואה אחד מהם; אל תמתין ל-`pending` לנצח. אסימוני גישה לדף לעולם אינם מוחזרים.

### שלב 3 — בחירת הדף לחיבור

בחרו אחד ממזהי הדפים משלב 2 ובחרו אותו. בחירת דף מחברת גם את אינסטגרם וגם את מסנג'ר עבור אותו דף. כללו את `sub_account_id` בגוף הבקשה שוב.

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/channels/meta/select-page?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_id": "1098765432101234",
    "sub_account_id": "abc123def456"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/channels/meta/select-page", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    page_id: "1098765432101234",
    sub_account_id: "abc123def456",
  }),
});

const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.dmchamp.com/v1/channels/meta/select-page",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "page_id": "1098765432101234",
        "sub_account_id": "abc123def456",
    },
)

data = res.json()
```

**תגובה:**

```json
{
  "success": true,
  "page_id": "1098765432101234",
  "instagram_business_account_id": "17841400000000000"
}
```

זה הכל — אינסטגרם ומסנג'ר מחוברים כעת לחשבון המשנה של הלקוח. סיפקתם רק את `page_id`; אישור הגישה הבסיסי נפתר בשרת ולעולם אינו עובר דרך האינטגרציה שלכם.

***

## דוגמה עובדת: רכישת מספר עבור חשבון משנה

רכישת מספר עובדת באותו אופן: חפשו עם `sub_account_id` בשאילתה, ולאחר מכן בצעו רכישה איתו בגוף הבקשה. נקודות זכות ינוכו מיתרת **חשבון המשנה**, והמספר יוקצה לחשבון המשנה.

**חיפוש (cURL):**

```bash
curl "https://api.dmchamp.com/v1/phone-numbers/available?apiKey=YOUR_API_KEY&country_code=US&sub_account_id=abc123def456"
```

**רכישה (JavaScript):**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+14155551234",
    country_code: "US",
    display_name: "Support line",
    sub_account_id: "abc123def456",
  }),
});

const data = await res.json();
```

**רכישה (Python):**

```python
import requests

res = requests.post(
    "https://api.dmchamp.com/v1/phone-numbers",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "phone_number": "+14155551234",
        "country_code": "US",
        "display_name": "Support line",
        "sub_account_id": "abc123def456",
    },
)

data = res.json()
```

**תגובה:**

```json
{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "whatsapp_status": "PURCHASED",
  "outgoing_status": "PURCHASED",
  "status": "PURCHASED",
  "purchase_credits": 11.5,
  "monthly_credits": 11.5
}
```

המספר מוקצה במצב `PURCHASED` ורישום שולח ה-WhatsApp נמשך ברקע. בצע תשאול ל-`GET /v1/phone-numbers/{phoneNumber}/status?sub_account_id=abc123def456` עד שהסטטוס יגיע ל-`ONLINE` לפני השליחה.

***

## דוגמה מעשית: העברת סוכן תבנית לכל לקוח חדש

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

### שלב 1 — העתקת הסוכן פנימה

`POST /v1/subaccounts/agents/copy`

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts/agents/copy?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_TEMPLATE_AGENT_ID",
    "targetUserId": "abc123def456",
    "newName": "Inbound Instagram Leads",
    "copyFaqs": true
  }'
```

התגובה נושאת את ה-id של הסוכן החדש ב-`data.agent_id`. השאלות הנפוצות, מאגר הידע וספריית המדיה עוברים יחד איתו; תבניות ה-WhatsApp, הפוסטים החברתיים המחוברים ואנשי הקשר של חשבון המקור אינם עוברים במכוון. רשימת שדות מלאה נמצאת ב-[AI Agents API](../api/agents.md#copy-an-agent-into-a-sub-account-agencies).

שימו לב שנקודת קצה זו מקבלת `targetUserId` במקום `sub_account_id` — היא מציינת את שני החשבונות בעצמה. שתי הקריאות להלן משתמשות בפרמטר ה-`sub_account_id` הרגיל.

### שלב 2 — הפעלה

העותק תמיד מגיע כשהוא מושהה, כך שהוא לא יכול לשלוח הודעות לאף אחד עד שתאשרו זאת. זהו גם הרגע לקבוע את דרגת ה-AI שאתם רוצים שהלקוח יהיה בה; היא נשארת שם, כך שאין צורך להחיל אותה מחדש לפי לוח זמנים.

```bash
curl -X PATCH "https://api.dmchamp.com/v1/agents/NEW_AGENT_ID/active?apiKey=YOUR_API_KEY&sub_account_id=abc123def456" \
  -H "Content-Type: application/json" \
  -d '{ "active": true }'

curl -X PUT "https://api.dmchamp.com/v1/agents/NEW_AGENT_ID?apiKey=YOUR_API_KEY&sub_account_id=abc123def456" \
  -H "Content-Type: application/json" \
  -d '{ "anthropic_model": "max" }'
```

כדי למנוע מהלקוח לשנות את הדרגה לאחר מכן, [נעלו את הדרגות המותרות](#set-per-client-ai-pricing-and-policy) בתת-החשבון במקום לשלוח את הערך מחדש.

### שלב 3 — הפניית הערוצים של הלקוח אליו

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

```bash
curl -X PUT "https://api.dmchamp.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY&sub_account_id=abc123def456" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "NEW_AGENT_ID" }'
```

מכאן ואילך, הודעה ראשונה מאיש קשר לא מוכר בערוץ זה תיקלט על ידי הסוכן שהועתק באופן אוטומטי. ראו [הפניית ערוץ לסוכן](../api/entry-points.md#point-a-channel-at-an-agent) עבור הערוצים האחרים וניתוב לפי מספר.

> **הגדירו את אזור הזמן של הלקוח בעת יצירת תת-החשבון.** העבירו את `time_zone_id` ב-`POST /v1/subaccounts`. שעות הפעילות של הקמפיין מוערכות לפי אזור הזמן של תת-החשבון עצמו, כך שלקוח שנוצר ללא אזור זמן יקרא את לוח הזמנים שלו לפי UTC — מה שמשנה בשקט את הזמנים שבהם מותר לעוזר להשיב.

***

## דלג על אשף ההגדרה עבור לקוח שאתה מגדיר בעצמך

`POST /v1/subaccounts`

כברירת מחדל, בפעם הראשונה שבעל חשבון משנה חדש מתחבר, הוא מועבר דרך אשף הגדרה מודרך. עבור לקוחות שאתה מבצע עבורם את העבודה — שבהם אתה בונה את הקמפיין ומחבר את הערוצים לפני שהלקוח מתחבר אי פעם — העבר `guided_onboarding: false` בעת יצירת החשבון. הם ינחתו בלוח הבקרה במקום זאת, והערך **אשף ההגדרה** יוסתר מסרגל הצד שלהם.

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@example.com",
    "first_name": "Alex",
    "last_name": "Client",
    "business_name": "Client Co",
    "guided_onboarding": false,
    "usage_limits": { "monthly_credits": 500 }
  }'
```

השמיטו את השדה (או שלחו `true`) והאשף יתנהג בדיוק כפי שהתנהג תמיד, כך שאינטגרציות קיימות אינן זקוקות לשינוי. כדי להחזיר ללקוח את האשף מאוחר יותר, הציגו מחדש את הפריט `guided_onboarding` עם `PUT /v1/subaccounts/{subAccountUid}/menu-visibility` (להלן) — נראות התפריט קובעת אם האשף נגיש, `guided_onboarding` שולט רק בהפניה מחדש של הכניסה הראשונה.

***

## השבתת משימות, סיכומים יומיים או ספריית המדיה עבור לקוח

`POST /v1/subaccounts`

שלושת אלו מופעלים עבור כל לקוח חדש אלא אם ציינת אחרת, והם מתנהגים אחרת מכל תכונה אחרת במדריך זה: הם מבוססים על **ביטול הסכמה** (opt-out), ולא על הצטרפות (opt-in). השמטתם מ-`features` אינה מספיקה כשלעצמה, מכיוון שרשימת ה-`features` של אינטגרציה ישנה פשוט לא הזכירה אותם מעולם — אין לנו דרך להבדיל בין "הסוכנות כיבתה את זה" לבין "הרשימה הזו נכתבה לפני שהאפשרות הייתה קיימת".

לכן, יש לציין זאת במפורש באמצעות `feature_settings`:

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@example.com",
    "first_name": "Alex",
    "last_name": "Client",
    "business_name": "Client Co",
    "feature_settings": {
      "tasks": false,
      "daily_summaries": false,
      "ai_media_library": true
    }
  }'
```

כל מפתח הוא אופציונלי; כל מה שתשמיט יישאר מופעל. עם `tasks: false` ה-AI מפסיק ליצור משימות עבור אותו לקוח ולא נשלחים אימיילים מסוג "נוצרה משימה חדשה"; עם `daily_summaries: false` הסיכום הלילי לעולם לא נוצר ולא נשלח בדוא"ל.

`feature_settings` הוא הדבר היחיד שמכבה את שלושת אלו בעת היצירה. השמטתם מ-`features` לא עושה דבר כשלעצמה, ללא קשר לאופן שבו שאר הרשימה שלך נראית — זה מכוון, כדי שאינטגרציה ישנה לא תאבד את שלושתם בשקט.

כדי לשנות זאת לאחר מכן, שלח את רשימת ה-`features` המלאה ל-`PUT /v1/subaccounts/{subAccountUid}/features` — שם, נוכחות ברשימה מפעילה תכונה והיעדרות מכבה אותה.

***

## כניסה אוטומטית של לקוחות לחשבון המשנה שלהם (SSO)

`POST /v1/subaccounts/{subAccountUid}/sso-link`

קריאה אחת עם מפתח ה-API של הסוכנות שלך מחזירה כתובת URL מוכנה לפתיחה, שמחברת את הלקוח ישירות לחשבון המשנה שלו — ללא מסך התחברות, ללא שלב סיסמה, וללא צורך לבנות דבר מעבר לכך. ניתן לפתוח אותה בלשונית חדשה, כהפניה (redirect), או בתוך iframe במוצר שלך.

| שדה | נדרש | תיאור |
|---|---|---|
| `redirect` | לא | דף בתוך האפליקציה שאליו תרצה שהלקוח יגיע, לדוגמה `"/chats"` או `"/agents"`. מוחזר כ-`deep_link_url` בתגובה. |
| `app_base_url` | לא | מארח לוח הבקרה עבור הקישור. ברירת המחדל היא דומיין ה-white-label של האפליקציה שלך (או דומיין הפלטפורמה אם אין לך כזה). חייב להיות `https`. |

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/sso-link" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redirect": "/chats" }'
```

**תגובה**

```json
{
  "success": true,
  "url": "https://app.yourdomain.com/auth?redirect=%2Fchats#token=eyJhbGciOi…",
  "deep_link_url": "https://app.yourdomain.com/chats",
  "expires_at": "2026-07-22T15:04:05.000Z",
  "sub_account_uid": "SUB_ACCOUNT_UID"
}
```

איך להשתמש בזה נכון:

- **דילוג אחד.** פתיחת `url` מחברת את הלקוח ומעבירה אותו ישירות לדף ה-`redirect` בלוח הבקרה — ללא מסך התחברות וללא דף ביניים. `deep_link_url` מציין את אותו יעד עבור אינטגרטורים המעדיפים לנווט למסגרת באופן מפורש לאחר ההתחברות; ברגע שהסשן קיים, כל נתיב בלוח הבקרה יעבוד בהקשר של דפדפן זה.
- **הנפקה לפי דרישה, פתיחה מיידית.** הקישור מכיל פרטי התחברות ותוקפו פג לאחר כשעה. בקש אותו בצד השרת ברגע שהלקוח לוחץ, ולעולם אל תשמור או תשלח אותו בדוא"ל.
- אסימון ההתחברות עובר בתוך ה-fragment של ה-URL (`#…`), שדפדפנים לעולם אינם שולחים לשרתים, והוא מוסר משורת הכתובת ברגע שהוא מנוצל.
- **חשבונות המשנה שלך בלבד.** נקודת הקצה מסרבת לכל חשבון שאינו בבעלות הסוכנות שלך.
- קישור שפג תוקפו מציג שגיאה ברורה עם נתיב לניסיון חוזר — הנפק קישור חדש.

***

## הסתרת פריטי ניווט בחשבון משנה

`PUT /v1/subaccounts/{subAccountUid}/menu-visibility`

שולט באילו פריטי סרגל צד והגדרות חשבון משנה רואה — שימושי כאשר אתה מטמיע את לוח הבקרה ורוצה רק את הממשקים שהמוצר שלך עדיין לא מכסה. כל מה שלא מופיע ברשימה נשאר גלוי; שלח `null` כערך ה-`menuVisibility` המלא כדי לאפס הכל למצב גלוי. הסתרת פריט מסתירה את כניסת התפריט — שלב זאת עם התכונות שאתה מעניק לחשבון המשנה לצורך חסימה קשיחה.

**cURL**

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/menu-visibility" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "menuVisibility": {
      "side_nav": { "Dashboard": false, "Campaigns": false, "Automations": false },
      "settings_nav": { "team": false }
    }
  }'
```

**תגובה**

```json
{
  "success": true,
  "data": {
    "subAccountUid": "SUB_ACCOUNT_UID",
    "menuVisibility": {
      "side_nav": { "Dashboard": false, "Campaigns": false, "Automations": false },
      "settings_nav": { "team": false }
    }
  }
}
```

`side_nav` מקבל 13 מפתחות אלו, התואמים לשמות הפריטים בסרגל הצד: `Dashboard`, `DailySummaries`, `Chats`, `Contacts`, `Deals`, `Tasks`, `Automations`, `Campaigns`, `Appointments`, `Settings`, `Help`, `CreditsCounter` (יתרת האשראי המוצגת בסרגל הצד) ו-`guided_onboarding` (אשף ההגדרה). שלושה מפתחות נוספים — `AiInsights`, `Sub Accounts` ו-`Agency Reselling` — מתקבלים אך אינם מבצעים דבר: הם היו רלוונטיים רק ללוח הבקרה הקלאסי שיצא משימוש, לכן הגדרתם אינה משפיעה על חשבונות המשנה שלך. מפתחות חסרים משמעותם פריטים גלויים; כאשר אתה נכנס לחשבון המשנה בעצמך, פריטים מוסתרים מוצגים באופן זמני כדי שתוכל תמיד לשנות את ההגדרות בחזרה.

הסתרת דף מהתפריט לעולם אינה מעניקה גישה אליו. `Automations` דורש שתכונת ה-`automations` תהיה מורשית בחשבון המשנה — הגדר את המפתח ל-`true` בלעדיה והדף עדיין לא יופיע. `Tasks` ו-`DailySummaries` עובדים בצורה הפוכה: הם מופעלים עבור כל לקוח אלא אם תכבה אותם (ראה [השבתת משימות, סיכומים יומיים או ספריית המדיה עבור לקוח](#turn-tasks-daily-summaries-or-the-media-library-off-for-a-client)).

***

## בחר אילו סוגי ערוצים לקוח יכול לחבר

`PUT /v1/subaccounts/{subAccountUid}/features`

מתגי **סוגי ערוצים** (Channel Types) שאתה רואה ברמת תוכנית הם מזהי תכונות רגילים, לכן ניתן להגדיר אותם לכל לקוח דרך ה-API במקום דרך לוח הבקרה. זהו אחד מנקודות הקצה (endpoints) שמציינות את חשבון המשנה בתוך ה-URL שלו, לכן הוא לא דורש `sub_account_id`.

| מזהה תכונה | ערוץ |
|---|---|
| `channel_chat_widget` | ווידג'ט צ'אט לאתר |
| `channel_whatsapp_api` | WhatsApp Business API |
| `channel_whatsapp_web` | WhatsApp Web (מספר מקושר ב-QR) |
| `channel_instagram` | Instagram |
| `channel_messenger` | Facebook Messenger |
| `channel_telegram` | Telegram |
| `channel_line` | LINE |
| `channel_viber` | Viber |
| `channel_email` | תיבת דואר אלקטרוני |
| `channel_sms` | SMS |
| `channel_imessage` | iMessage |

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/features" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "features": [
      "channels_3",
      "channel_chat_widget",
      "channel_whatsapp_web",
      "channel_instagram",
      "image_understanding",
      "contact_tagging",
      "incoming_campaigns",
      "webhooks"
    ]
  }'
```

שלושה דברים שחשוב להקפיד עליהם:

- **הקריאה מחליפה את כל רשימת התכונות.** שלח את כל התכונות שהלקוח צריך לשמור, לא רק את אלו שאתה משנה. אותם מזהים עובדים כ-`features` ב-`POST /v1/subaccounts` בעת יצירת החשבון.
- **סוגי ערוצים ומספר ערוצים הם חסמים נפרדים, ושניהם חלים.** `channels_1` / `channels_3` / `channels_unlimited` שולטים ב-*כמה* חיבורים; מזהי ה-`channel_*` שולטים ב-*אילו סוגים*. הדוגמה לעיל אומרת "עד 3 חיבורים, ורק ווידג'ט צ'אט, WhatsApp Web או Instagram".
- **שליחת מזהי `channel_*` ריקים משמעותה ללא הגבלת ערוצים.** זוהי ההתנהגות המקורית, וזו הסיבה שלקוחות קיימים לא הושפעו כאשר תכונה זו הושקה. שלח מזהה אחד או יותר וכל השאר יוצגו כנעולים בדף הערוצים של הלקוח עם הערת שדרוג במקום כפתור "חיבור". ערוצים שהלקוח כבר חיבר ימשיכו לעבוד.

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

***

## הגדרת מגבלה מדויקת של חברי צוות עבור לקוח

`PUT /v1/subaccounts/{subAccountUid}/limits`

התכונות של `team_seats_*` מציעות רק שלבי סולם מוגדרים מראש (3 / 5 / 10 / ללא הגבלה). כדי להעניק ללקוח מספר **מדויק** של מושבי צוות — 2, 7, 15, או כל מספר אחר — הגדר במקום זאת את `usage_limits.team_seats_limit`. הגדרה זו גוברת על הערכים המוגדרים מראש, והפלטפורמה אוכפת אותה בכל הזמנה, הוספה ישירה ואישור הזמנה: ברגע שהמגבלה מגיעה למיצוי, הזמנות נוספות נדחות בצד השרת.

- מספר שלם חיובי הוא המכסה המדויקת.
- `0` פירושו שחברי צוות **אינם כלולים** — הלקוח אינו יכול להזמין איש.
- `-1` פירושו ללא הגבלה.
- `null` מנקה את המגבלה המותאמת אישית וחוזר להסתמך על כל ערך מוגדר מראש של `team_seats_*` שקיים ברשימת התכונות.

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

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/limits" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "usageLimits": { "team_seats_limit": 7 }
  }'
```

ניתן להגדיר זאת גם בעת היצירה: `POST /v1/subaccounts` מקבל `usage_limits.team_seats_limit` עם אותה סמנטיקה. כדי לקרוא את הערך הנוכחי, משוך את חשבון המשנה עם `GET /v1/subaccounts?email=...` והסתכל על `usage_limits.team_seats_limit` (בהיעדר ערך/`null` = הגדרות ברירת המחדל קובעות). אותו נקודת קצה מעדכנת גם את `credits`, `monthly_credits`, `roll_over_to_next_month`, `rollover_cap_months`, `rollover_expiry_days` ו-`byok_monthly_limit_usd` — שלח רק את המפתחות שברצונך לשנות.

**כיצד זה משפיע על מגבלות המושבים בתוכניות SaaS.** תוכניות ה-SaaS שלך יכולות לכלול הקצאת מושבים משלהן (המוגדרת בעורך התוכניות — ראה [מושבי צוות בתוכנית](agency-accounts.md#step-3--set-up-pricing-tiers)), אשר מוחלת באופן אוטומטי כאשר לקוח נרשם. מגבלה שאתה מגדיר דרך נקודת קצה זו נחשבת להקצאה **ידנית**: רכישת תוכנית מחליפה אותה בהקצאת המושבים של התוכנית עצמה (רכישה זו היא בחירה מפורשת בתוכנית), אך **חידושים חודשיים אוטומטיים לעולם אינם דורסים מגבלה ידנית** — כך שחריגה חד-פעמית שאתה מעניק ללקוח נשמרת לאורך מחזור החיוב שלו. ניקוי המגבלה הידנית באמצעות `null` מחזיר את השליטה בשדה לתוכנית בחידוש הבא שלה.

**הגבל את מה שלקוח מעביר בין חידושים.** שני מפתחות `usage_limits` נוספים נמצאים לצד `roll_over_to_next_month`. שניהם מתקבלים על ידי `POST /v1/subaccounts` גם בעת היצירה, ו-`null` מנקה את שניהם.

| מפתח | מה הוא עושה |
|---|---|
| `rollover_cap_months` | חודשי הקצבה שהלקוח רשאי לשמור. מספר מ-0 עד 120, שברים מותרים (`0.5` = חצי חודש). בכל חידוש, היתרה שלא נוצלה מצומצמת לכל היותר למספר זה כפול ההקצבה שהחידוש מעניק, לפני הוספת הקרדיטים החדשים; `0` לא מעביר דבר. |
| `rollover_expiry_days` | מספר ימים שלם, 1 עד 3650. קרדיטים שלא נוצלו למשך זמן זה נמחקים בחידוש הראשון לאחר שהגיעו לגיל זה. ניצול תמיד נגרע מהקרדיטים הישנים ביותר תחילה, כך שלקוח שמנצל את ההקצבה שלו בכל חודש לעולם לא יאבד דבר. |

אם לא יוגדרו, שניהם יחזרו להגדרות התוכנית של הלקוח; ערך שנשלח כאן יגבר על זה של התוכנית. רק קרדיטים חוזרים (ההקצבה החודשית וקרדיטי התוכנית) כפופים להם: תוספות, טעינות אוטומטיות ותוספות חד-פעמיות לעולם אינן מוגבלות או פוקעות. כל צמצום נרשם בהיסטוריית הקרדיטים של הלקוח כ-**Rollover Cap Credit Adjustment** או **Expired Credits Credit Adjustment** ולעולם לא נחשב כשימוש. המקבילות ברמת התוכנית הן `rollover_cap_months` ו-`rollover_expiry_days` בשכבת תמחור — ראה [השדות בשכבה](#the-fields-on-a-tier) ו-[הגבלת מה שמועבר](sub-accounts.md#capping-what-rolls-over).

***

## הגדרת תמחור ומדיניות AI לכל לקוח

`PUT /v1/subaccounts/{subAccountUid}/max-tier` · `/ai-tiers` · `/max-rate` · `/action-pricing` · `/insider-rate` · `/locked-bot-fields` · `/notifications` · `/zero-credit-reply`

שמונה מתגים נוספים לכל לקוח, לצד `/limits`, `/features` ו-`/menu-visibility` לעיל. כל אחד לוקח את ה-uid של חשבון המשנה ב-URL (ללא `sub_account_id` גוף/פרמטר שאילתה — היעד כבר מצוין בנתיב) והוא מוגדר באותו אופן: מפתח הסוכנות שלך, וחשבון המשנה חייב להיות שייך לסוכנות שלך.

**באילו מודלי AI לקוח יכול להשתמש**

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/max-tier" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

`{ "enabled": boolean }` רושם את הלקוח לתוך (או מחוץ) לדרגת Max AI — התשתית שלנו במחיר המחירון של הפלטפורמה. הפעלת אפשרות זו עבור לקוח BYOK משנה את עלות ה-AI שלו מ-"חינם על המפתח שלי" ל-"מחויב ממאגר הקרדיטים שלי", כך שמדובר בהחלטה מכוונת לכל לקוח ולא בברירת מחדל כלל-סוכנותית.

כדי להגביל באילו דרגות הקמפיינים והסוכנים של לקוח יכולים לבחור בכלל (במקום רק לחסום את Max), השתמש ב-`ai-tiers`:

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/ai-tiers" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "allowed_ai_tiers": ["standard", "economy"] }'
```

`allowed_ai_tiers` הוא מערך שנלקח מ-`standard`, `economy`, `max`, `mini` — הוא מחליף את רשימת המותרים (allow-list) של הלקוח. שלח `null` (או `[]`) כדי לנקות את ההגבלה ולאפשר להם לבחור כל דרגה. זה חשוב מכיוון שתת-חשבון שבוחר דרגת AI משלו מוציא ממאגר הקרדיטים **שלך**, לכן זהו המנוף לקביעת אילו מודלים לקוח מסוג משווק יכול להפעיל על חשבונך.

**תגובת המתנה בזמן שללקוח אין קרדיטים**

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/zero-credit-reply" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "message": "Thanks for your message, we will get back to you shortly." }'
```

כאשר היתרה של הלקוח (או המאגר שלך) ריקה, ה-AI לא יכול לענות ואיש הקשר לא שומע דבר. עם `enabled: true`, כל איש קשר שכותב במהלך ההשבתה מקבל את `message` פעם אחת (מקסימום 500 תווים, נשלח כפי שהוא בכל ערוץ), וה-AI עונה לשיחות אלו באמת ברגע שהקרדיטים חוזרים. `enabled: false` שומר את הטקסט שנשמר למועד מאוחר יותר; `enabled: false` ללא `message` מסיר את ההגדרה. אותו מתג כמו **Holding reply when out of credits** בחלון העריכה של חשבון המשנה — ראה [תגובת המתנה בזמן שללקוח אין קרדיטים](sub-accounts.md#a-holding-reply-while-a-client-is-out-of-credits).

**מה לקוח משלם עבור כל פעולת AI, ותוספת העמלה של WhatsApp**

שתי דרכים להגדיר את התעריף מול הלקוח שלך, מהפשוטה ביותר ועד המפורטת ביותר:

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/max-rate" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rate": 0.35 }'
```

`rate` הוא המחיר בקרדיטים שהיתרה העצמית של תת-החשבון שורפת עבור כל פעולת AI במודל Max — תוספת העמלה שלך מול הלקוח מעבר למה שהמאגר שלך משלם בפועל. `null` מנקה את העקיפה חזרה למחיר המחירון של הפלטפורמה. התעריף חייב להיות לפחות מה שפעולת Max עולה למאגר שלך (כך שלעולם לא תוכל לתמחר לקוח מתחת לעלות שלך) ולא יותר מ-10 קרדיטים; בקשה מחוץ לטווח זה תידחה עם הודעת שגיאה המציינת את הרף המינימלי המחושב.

עבור תמחור לפי סוג פעולה במקום תעריף Max אחיד, השתמש ב-`action-pricing`:

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/action-pricing" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actionPricing": {
      "AI_MESSAGE": 0.6,
      "CHAT_SUMMARY": 0.15,
      "wa_carrier_multiplier": null
    }
  }'
```

`actionPricing` הוא מיזוג (MERGE) לתוך המפה הקיימת של הלקוח — מפתח שלא ציינת נשאר כפי שהיה, ו-`null` מבטל את המפתח הזה חזרה לברירת המחדל שלו. המפתחות המוכרים:

| מפתח | מחירים |
|---|---|
| `AI_MESSAGE` | תשובת AI |
| `AI_TOOL_USE` | קריאת כלי AI |
| `EVALUATION_CALL` | מעבר הערכת צ'אט |
| `INTERRUPTION_HANDLING` | טיפול בהפרעה באמצע תשובה |
| `CONTACT_TAG` | תג איש קשר שהוקצה על ידי AI |
| `CHAT_SUMMARY` | סיכום צ'אט |
| `wa_carrier_multiplier` | מכפיל עמלה המוחל על כל עמלת WhatsApp שאינה AI שהלקוח משלם: שכירות חודשית של מספר, דמי משלוח בנתיב מנוהל, ועלויות העברה של Meta/Twilio עבור תבניות. |

שיעורים לכל פעולה חייבים להיות מספר הגדול מ-0 ועד 10; `wa_carrier_multiplier` חייב להיות לפחות `1` (ללא הנחה מתחת לעלות) ועד 10. שליחת מפתח לא מזוהה, או ערך מחוץ לטווח, תדחה את הבקשה כולה ותציין כל מפתח בעייתי, כך ששגיאת הקלדה לעולם לא תגרום לשמירה שקטה של מחיר שאינו מוחל בפועל.

אם אתה חבר ב-[Champions Circle](https://skool.com/dm-champions), `insider-rate` מעביר את שיעור ה-20% הנחה שלך ב-Max/Lead Finder ללקוח אחד במקום להחיל אותו על כל הסוכנות:

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/insider-rate" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

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

**נעל חלקים מתוכנית העבודה (playbook) של לקוח**

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/locked-bot-fields" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "locked_bot_fields": ["instructions", "rules"] }'
```

`locked_bot_fields` הוא מערך שנלקח מ-`instructions`, `goal`, `rules`, `personality`, `conclude_unless` — הוא מחליף את רשימת הנעילות של הלקוח. חלק נעול נדחה בצד השרת אם ה-SUB-ACCOUNT עצמו מנסה לשנות אותו (ישירות, או באמצעות מפתח API), בעוד שאתה (דרך `sub_account_id`) ומנהל המערכת בלוח הבקרה של הלקוח עדיין יכולים לערוך הכל. שלח `null` (או `[]`) כדי לבטל את הנעילה של הכל. שימושי עבור לקוחות בשיטת "עשה זאת עבורי" (done-for-you) שבהם אתה הבעלים של תוכנית העבודה ונשפט על התוצאה.

**הגדר את העדפות ההתראות של לקוח בשמו**

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/notifications" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": {
      "settings": {
        "credit_alerts": { "enabled": true, "channels": ["email", "in_app"] },
        "new_contacts": { "enabled": false }
      }
    }
  }'
```

`notifications` מחליף את כל מערך העדפות ההתראות של הלקוח (לא מיזוג לפי מפתח — שלח כל קטגוריה שברצונך לשמור, בהתאם לאופן שבו דף ההגדרות של חשבון המשנה שומר אותן). כל קטגוריה תחת `settings` מקבלת `enabled` (בוליאני) ועד שלושה `channels` מתוך `email`, `in_app`, `webhook`. שלח `null` כדי לאפס לברירות המחדל של הפלטפורמה.

כל שבע נקודות הקצה מגיבות ב-`{ "success": true, "data": { "subAccountUid": "...", ...the field(s) you set... } }`, ומתועדות ביומן ביקורת עם הערך שלפני/אחרי. שגיאות נפוצות: `403` אם החשבון שלך אינו חשבון סוכנות/מפתח או שחשבון המשנה אינו מנוהל על ידך, `400` אם זה אינו חשבון משנה של סוכנות או שערך כלשהו מחוץ לטווח.

***

## השהיית לקוח שהשעה את המנוי שלו

`POST /v1/subaccounts/{subAccountUid}/pause` · `POST /v1/subaccounts/{subAccountUid}/unpause`

כאשר לקוח משעה את המנוי שלו איתך, השהה את החשבון שלו במקום למחוק אותו: כל מה שהוא שולח נעצר מיד — הודעות יוצאות, שידורים, תשובות AI בכל ערוץ — וכאשר הוא מתחבר, הוא יראה מסך נעילה של **חשבון מושהה** (עם הודעה אופציונלית ממך) במקום את האפליקציה. שום דבר לא נמחק או מתנתק: סוכנים, קמפיינים, ערוצים מחוברים, אנשי קשר והיסטוריית צ'אט נשארים בדיוק כפי שהם, כך שביטול ההשהיה מחזיר את הלקוח בדיוק לנקודה שבה עצר — ללא צורך בהגדרה מחדש.

| שדה | חובה | תיאור |
|---|---|---|
| `message` | לא | מוצג ללקוח במסך הנעילה שלו. השאר ריק עבור הניסוח המוגדר כברירת מחדל. |
| `reason` | לא | הערה פנימית של הסוכנות הנשמרת עם ההשהיה וביומן הביקורת — לעולם לא מוצגת ללקוח. |

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/pause" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Your account is on hold — contact us to reactivate it.", "reason": "Subscription suspended per client email" }'
```

**תגובה**

```json
{
  "success": true,
  "data": {
    "subAccountUid": "SUB_ACCOUNT_UID",
    "paused": true,
    "level": "hard_blocked"
  }
}
```

כאשר הלקוח חוזר, `POST /v1/subaccounts/SUB_ACCOUNT_UID/unpause` (ללא גוף הודעה) מסיר את הנעילה — שליחת הודעות ותשובות AI מתחדשות מיד.

כדאי לדעת:

- **זהו אותו מצב כמו מתג החסימה הקשיחה (Hard blocked) בלוח הבקרה** ([חסימה / השהיה של תת-חשבון](sub-accounts.md#blocking-pausing-a-sub-account)) — לקוח שהושהה דרך ה-API מופיע כחסום בלוח הבקרה ולהיפך, וביטול השהיה מסיר חסימה שבוצעה מכל צד. ניתן לקרוא את המצב הנוכחי מהשדה `agency_block` ב-`GET /v1/subaccounts` (`level` של `"none"`, `"soft_blocked"` או `"hard_blocked"`).
- **שתי הקריאות הן אידמפוטנטיות.** השהיית לקוח שכבר מושהה רק מרעננת את ההודעה, הסיבה וחותמת הזמן; ביטול השהיה ללקוח פעיל לא משנה דבר.
- **הלקוח לא מקבל אימייל באופן אוטומטי** — סוכנויות רבות משתמשות במיתוג לבן (white-label), לכן העדכון על כך נשאר באחריותך.
- **החיוב שלך ב-DM Champ נותר ללא שינוי.** השהיית לקוח משפיעה רק על מערכת היחסים שלך איתו.
- **עוזרי AI יכולים לעשות זאת גם**: [שרת ה-MCP](../integrations/connect-ai-clients.md) חושף נקודות קצה אלו ככלים `pause_subaccount` ו-`unpause_subaccount`.

***

## הענקת או הפחתת קרדיטים ישירות

`POST /v1/subaccounts/credits`

מוסיף או מסיר כמות מדויקת של קרדיטים מיתרת חשבון משנה אחד — המקבילה ב-API להתאמת קרדיט ידנית בלוח הבקרה. זהו שינוי יתרה חד-פעמי, נפרד מהגדרות ה-`monthly_credits`, `roll_over_to_next_month`, `rollover_cap_months` ו-`rollover_expiry_days` החוזרות ב-[`PUT /v1/subaccounts/{subAccountUid}/limits`](#set-an-exact-team-member-limit-for-a-client).

זוהי נקודת הקצה היחידה בדף זה שמזהה את חשבון המשנה לפי **דוא"ל** ולא לפי `sub_account_id`.

| שדה | חובה | תיאור |
|---|---|---|
| `email` | כן | כתובת הדוא"ל של חשבון המשנה, כפי שהיא מופיעה תחת הסוכנות שלך. |
| `amount` | כן | מספר קרדיטים שאינו אפס. מספר חיובי מוסיף, שלילי מפחית. |
| `description` | לא | מוצג לצד ההתאמה בהיסטוריית הקרדיטים של הלקוח. כברירת מחדל מוצגת השורה הכללית "הותאם על ידי הסוכנות דרך API". |

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts/credits" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "client@example.com", "amount": 500, "description": "Q3 bonus credits" }'
```

**תגובה**

```json
{
  "success": true,
  "data": {
    "email": "client@example.com",
    "previous_balance": 1200,
    "adjustment": 500,
    "new_balance": 1700
  }
}
```

`amount` שלילי שיביא את היתרה מתחת לאפס מסורב עם `400`, המודיע לך על היתרה הזמינה ועל מה שניסית לנכות. אם הלקוח נמצא בחיוב Stripe משלו (מצב מכירה חוזרת), סכום שנוסף נחשב גם כקרדיטים שהוא רכש, כך שהוא שורד את האיפוס החודשי הבא שלו באותו אופן שבו טעינה אמיתית הייתה שורדת; בלקוח מוקצה סטנדרטי הוא מטופל כחלק מההקצבה החוזרת שלו במקום זאת. כך או כך, הם תוספת חד-פעמית, לכן הגבלת העברה או תוקף שנקבעו בחשבון (או בתוכנית שלו) לעולם לא יצמצמו אותם — רק ההקצבה החוזרת וקרדיטי התוכנית כפופים לאלו.

***

## קריאת שיחות של חשבון משנה

`GET /v1/subaccounts/{subAccountUid}/chats` · `GET /v1/subaccounts/{subAccountUid}/chats/{contactId}/messages`

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

**הצגת אנשי קשר**

```bash
curl "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/chats?apiKey=YOUR_AGENCY_API_KEY&pageSize=25"
```

| פרמטר שאילתה | נדרש | תיאור |
|---|---|---|
| `pageSize` | לא | אנשי קשר בכל עמוד. ברירת המחדל היא 25, המקסימום הוא 50. |
| `lastActivityAt` | לא | סמן דפדוף (Pagination cursor) — העבר את ה-`lastActivityAt` של העמוד הקודם כדי להמשיך. |
| `searchQuery` | לא | סינון לפי שם איש קשר או מספר טלפון. |

**תגובה**

```json
{
  "success": true,
  "data": {
    "contacts": [
      {
        "contactId": "contact456",
        "firstName": "Jamie",
        "lastName": "Lee",
        "phoneNumber": "+14155551234",
        "email": "jamie@example.com",
        "channel": "whatsapp",
        "lastActivityAt": "2026-08-30T14:22:00.000Z",
        "lastMessage": { "body": "Thanks, that fixed it!", "direction": "inbound", "timestamp": "2026-08-30T14:22:00.000Z" },
        "isBotActive": true,
        "markChatClosed": false
      }
    ],
    "subAccountName": "Client Co",
    "subAccountEmail": "client@example.com",
    "hasMore": true,
    "lastActivityAt": "2026-08-30T14:22:00.000Z"
  }
}
```

אנשי הקשר מסודרים לפי הפעילות האחרונה ביותר תחילה. המשך לדפדף עם `lastActivityAt` כל עוד `hasMore` הוא `true`.

**קריאת הודעות של איש קשר אחד**

```bash
curl "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/chats/contact456/messages?apiKey=YOUR_AGENCY_API_KEY&pageSize=30"
```

| פרמטר שאילתה | נדרש | תיאור |
|---|---|---|
| `pageSize` | לא | הודעות בכל עמוד. ברירת המחדל היא 30, המקסימום הוא 100. |
| `beforeTimestamp` | לא | סמן דפדוף (Pagination cursor) — משוך הודעות ישנות יותר מחותמת זמן ISO זו. |

**תגובה**

```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "messageId": "msg789",
        "body": "Thanks, that fixed it!",
        "direction": "inbound",
        "timestamp": "2026-08-30T14:22:00.000Z",
        "status": "received",
        "channel": "whatsapp",
        "botReply": false,
        "mediaUrl": null,
        "mediaContentType": null,
        "name": "Jamie Lee",
        "role": null
      }
    ],
    "contactInfo": { "firstName": "Jamie", "lastName": "Lee", "phoneNumber": "+14155551234", "channel": "whatsapp" },
    "hasMore": false,
    "oldestTimestamp": "2026-08-30T14:22:00.000Z"
  }
}
```

ההודעות חוזרות מהחדשה ביותר לישנה ביותר; דפדף אחורה בהיסטוריה עם `beforeTimestamp`.

***

## קריאת ניצול קרדיט ובריאות קמפיינים בכל החשבונות שלך

`GET /v1/subaccounts/credit-usage` · `GET /v1/subaccounts/campaign-status`

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

**ניצול קרדיט**

```bash
curl "https://api.dmchamp.com/v1/subaccounts/credit-usage?apiKey=YOUR_AGENCY_API_KEY&from=2026-08-01&to=2026-08-31"
```

| פרמטר שאילתה | נדרש | תיאור |
|---|---|---|
| `from` / `to` | כן | טווח תאריכי ISO. |
| `subAccountId` | לא | השמט עבור סיכום ברמת הסוכנות, שורה אחת לכל חשבון משנה. כלול כדי לעבור למצב פירוט: הסיכום של חשבון המשנה הזה בתוספת רשומות השימוש הגולמיות והממוספרות שלו. |
| `limitCount` | לא | מצב פירוט בלבד. ברירת המחדל היא 500, המקסימום הוא 2000. |
| `startAfterTimestamp` | לא | מצב פירוט בלבד — סמן דפדוף. |

```json
{
  "success": true,
  "data": {
    "subAccounts": [
      {
        "subAccountId": "abc123def456",
        "subAccountName": "Client Co",
        "subAccountEmail": "client@example.com",
        "totalCreditsUsed": 842,
        "totalCostUsd": 3.15,
        "byReason": { "AI reply": 620, "Chat summary": 80 },
        "topCampaigns": [{ "campaignName": "Inbound Leads", "creditsUsed": 500 }]
      }
    ],
    "totals": { "totalCreditsUsed": 842, "totalCostUsd": 3.15, "totalRecords": 214 },
    "dateRange": { "from": "2026-08-01", "to": "2026-08-31" },
    "hasMore": false,
    "lastTimestamp": null
  }
}
```

העבר את `subAccountId` והתגובה תכלול גם את `records`: חיובים בודדים עם `amount`, `reason`, `campaignName`, `contactName` ו-`timestamp`. לקוח שמוציא כספים באמצעות מפתח BYOK משלו במקום הקרדיטים שלך, נתוני העלות/אסימונים שלו יוסתרו (`costsRedacted: true`) — זוהי טלמטריה של עלויות פלטפורמה, לא משהו שנועד להצגה לצופה בדרגת משווק. |

**סטטוס קמפיין**

```bash
curl "https://api.dmchamp.com/v1/subaccounts/campaign-status?apiKey=YOUR_AGENCY_API_KEY&pageSize=20"
```

| פרמטר שאילתה | נדרש | תיאור |
|---|---|---|
| `pageSize` | לא | תת-חשבונות בכל עמוד. ברירת מחדל 10, מקסימום 50. |
| `lastDocumentId` | לא | סמן (cursor) עבור דפדוף. |
| `searchQuery` | לא | סינון לפי שם תת-חשבון או אימייל. |

```json
{
  "success": true,
  "data": {
    "totalSubAccounts": 34,
    "subAccountsWithIssues": 3,
    "totalLiveCampaigns": 51,
    "totalPausedCampaigns": 6,
    "subAccounts": [
      {
        "userId": "abc123def456",
        "email": "client@example.com",
        "displayName": "Jamie Lee",
        "businessName": "Client Co",
        "totalCampaigns": 2,
        "liveCampaigns": 1,
        "pausedCampaigns": 1,
        "hasIssues": true,
        "issueDetails": ["1 campaign paused"],
        "lastCampaignActivity": "2026-08-29T09:00:00.000Z"
      }
    ],
    "hasMore": true,
    "lastDocumentId": "abc123def456",
    "pageSize": 20
  }
}
```

דגל `hasIssues` / `issueDetails` מסמן תת-חשבונות שכדאי לבדוק — למשל, קמפיין מושהה, או קמפיין שאין לו ערוץ מנותב. השתמש בזה כדי לבנות לוח בקרה לבדיקת תקינות עבור כל הלקוחות, במקום לפתוח כל לקוח בנפרד כדי להבחין בקמפיין תקוע.

> עבור הודעות ופעילות אשראי לאורך זמן עבור כל לקוח (סדרה מוכנה לתרשים ולא תמונת מצב של רגע נתון), עיין ב-`GET /analytics/agency-rollup` במדריך ה-Analytics API.

***

## שלח חשבון לקוח שכבר הוגדר

`PUT /v1/snapshots/default` · `POST /v1/snapshots/{snapshotId}/apply`

[תמונת מצב](snapshots.md) (snapshot) היא תבנית לשימוש חוזר: סוכן בינה מלאכותית אחד או יותר בתוספת בסיס הידע, הכלים והמדיה שלהם, שנלכדו מהחשבון שלך. שני נקודות קצה (endpoints) מכניסים אותה לתהליך ההקצאה שלך.

**אוטומטי — כל לקוח חדש מקבל אותה מלידה.** סמן תמונת מצב כברירת המחדל שלך פעם אחת, וכל חשבון שתצור מאותו רגע יגיע כשהיא מותקנת בו. זה מכסה חשבונות שנוצרו דרך `POST /v1/subaccounts`, חשבונות שאתה יוצר בלוח הבקרה, וחשבונות שנוצרים אוטומטית כאשר לקוח משלם דרך קישור התשלום שלך.

ראשית, מצא את מזהה (id) תמונת המצב:

```bash
curl "https://api.dmchamp.com/v1/snapshots" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"
```

לאחר מכן הגדר אותה כברירת מחדל:

```bash
curl -X PUT "https://api.dmchamp.com/v1/snapshots/default" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "snapshot_id": "SNAPSHOT_ID" }'
```

זו כל האינטגרציה. שלח `{"snapshot_id": null}` כדי לכבות אותה שוב. באפשרותך לעשות את אותו הדבר מלוח הבקרה על ידי לחיצה על הכוכב בדף **Snapshots**.

כדי לקרוא מה מסומן כרגע בכוכב (למשל, לפני שסקריפט הקצאה מחליט אם להגדיר אחד), `GET /v1/snapshots/default` מחזיר `{ "success": true, "data": { "default_snapshot_id": "SNAPSHOT_ID" } }` — `null` כאשר שום דבר אינו מסומן בכוכב. `GET /v1/snapshots` (משמש למציאת ה-id לעיל) מחזיר את אותו `default_snapshot_id` לצד מערך ה-`snapshots` המלא, כך שרוב האינטגרציות זקוקות רק לקריאה אחת. שדות אובייקט תמונת המצב המלאים נמצאים במדריך [Snapshots](snapshots.md).

**לפי דרישה — התקנה בחשבון אחד.** שימושי עבור קליטת לקוח קיים, או עבור מתן תבנית שנייה ללקוח במועד מאוחר יותר.

```bash
curl -X POST "https://api.dmchamp.com/v1/snapshots/SNAPSHOT_ID/apply" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sub_account_id": "SUB_ACCOUNT_UID" }'
```

השמט את `sub_account_id` והיא תותקן בחשבון הסוכנות שלך במקום זאת. בדומה לנקודות הקצה `/subaccounts`, אלו מציינות את חשבון היעד בנתיב או בגוף הבקשה במקום דרך הפרמטר הסביבתי `sub_account_id`.

כדאי לדעת לפני שמתחילים לבנות על זה:

- **סוכנים מותקנים מתחילים במצב מושהה.** חבר תחילה את הערוצים של הלקוח, ולאחר מכן הפעל את הסוכן. זה נכון גם עבור הנתיב האוטומטי וגם עבור הנתיב לפי דרישה.
- **הקצאה לעולם לא נכשלת בגלל תמונת מצב.** אם ההתקנה לא יכולה להסתיים, חשבון הלקוח עדיין נוצר וניתן לשימוש — הוא פשוט מגיע ריק וניתן להחיל את תמונת המצב לאחר מכן.
- **ערוצים, יומנים וחיבורי OAuth לעולם לא מועתקים.** כל חשבון מחבר את שלו. כלים המשתמשים במפתח API פשוט ממשיכים לעבוד מיד.
- **החלה פעמיים יוצרת עותק שני.** שום דבר לא נדרס.

***

## בניית התבנית עצמה באמצעות ה-API

`POST /v1/snapshots` · סוכנים, פונקציות מותאמות אישית ומדיה באמצעות ה-API

הסעיף שלעיל מפיץ תמונת מצב (snapshot) שמישהו בנה בלוח הבקרה. גם חלק העריכה חשוף, כך שניתן להריץ את כל התהליך — הרכבת ההגדרה הראשית פעם אחת, לכידתה והעברתה לכל לקוח — מתוך קוד.

החלקים, לפי הסדר שבו סקריפט הקצאה משתמש בהם:

1. **צרו את הפונקציות המותאמות אישית שלכם.** `POST /v1/custom-functions` יוצרת אחת; `GET /v1/custom-functions` מציג את מה שיש לכם, ו-`GET`, `PUT` ו-`DELETE` ב-`/v1/custom-functions/{customFunctionId}` קוראים, מעדכנים ומסירים אחת. `POST /v1/custom-functions/test` מריץ בדיקה (dry-run) להגדרה לפני שמירתה.
2. **צרו ועצבו את הסוכן.** `POST /v1/agents` יוצר אותו, `PUT /v1/agents/{agentId}` מעדכן אותו, ו-`PATCH /v1/agents/{agentId}/active` עם `{ "active": false }` שומר עליו במצב מושהה בזמן שאתם עובדים (אותה קריאה עם `true` מפעילה אותו). `GET /v1/agents` מציג אותם.
3. **תנו לסוכן את היכולות שלו.** `POST /v1/agents/{agentId}/custom-functions` עם `{ "custom_function_id": "..." }` מצמיד פונקציה לסוכן; ה-`DELETE /v1/agents/{agentId}/custom-functions/{customFunctionId}` התואם מנתק אותה.
4. **מלאו את ספריית המדיה.** `POST /v1/agents/{agentId}/media-library` מעלה פריט (JSON עם `base64Data`, `mimeType`, `title`, `description`); `GET` מציג את הפריטים של הסוכן, ו-`PATCH`/`DELETE` ב-`/{itemId}` מעדכנים או מסירים אחד.
5. **לכדו זאת כתמונת מצב (snapshot).**

```bash
curl -X POST "https://api.dmchamp.com/v1/snapshots" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Master setup v1",
    "agent_ids": ["AGENT_ID"],
    "include_knowledge": true,
    "include_tools": true,
    "include_media": true
  }'
```

משם זה ממשיך לסעיף הקודם: סמנו אותו כברירת מחדל כך שכל לקוח חדש ייוולד איתו, או החילו אותו לפי דרישה. פעולות תחזוקה נמצאות לצד זה: `PATCH /v1/snapshots/{snapshotId}` עם `{ "name": "..." }` משנה שם של תמונה, `DELETE /v1/snapshots/{snapshotId}` מוחק אחת (ומסיר את סימון ברירת המחדל אם היא הייתה כזו), ו-`GET /v1/snapshots/apply-targets` מציג כל חשבון שאליו ניתן להתקין.

נקודות הקצה של הסוכן, הפונקציה המותאמת אישית והמדיה מקבלות כולן את `sub_account_id`, כך שאותן קריאות יכולות גם לתחזק סוכן ישירות בתוך חשבון של לקוח אחד. קריאות תמונת מצב (snapshot) פועלות תמיד על חשבון הסוכנות שלכם — התבנית נשארת אצלכם. סכימות מלאות של בקשות ותגובות עבור כל אלו נמצאות ב-[API Reference](../api/reference.md).

***

## ניהול דרגות התמחור שלכם דרך ה-API

`GET /v1/agency/pricing-tiers` · `POST /v1/agency/pricing-tiers` · `PATCH /v1/agency/pricing-tiers/{tierIndex}` · `DELETE /v1/agency/pricing-tiers/{tierIndex}`

ניתן לקרוא ולשנות את התוכניות שאתם מוכרים ב-**SaaS Mode → Pricing Tiers** מתוך הקוד, כך שפאנל הניהול או סקריפט ההקצאה שלכם יוכלו להוסיף תוכנית, לעדכן מחיר או לספק קישור לתשלום מבלי שאף אחד יצטרך לפתוח את לוח הבקרה. בצעו אימות עם מפתח ה-API של הסוכנות שלכם כמו בכל קריאה אחרת בדף זה; נקודות קצה אלו הן ברמת הסוכנות, ולכן הן אינן מקבלות `sub_account_id`. כל פעולת כתיבה מריצה את אותה אימות ואת אותו סנכרון מוצר ומחיר מול Stripe כמו בשמירה בלוח הבקרה, כך שתוכנית שנוצרה כאן אינה שונה מתוכנית שהגדרתם ידנית.

### הצגת הדרגות שלכם

```bash
curl "https://api.dmchamp.com/v1/agency/pricing-tiers" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "data": {
    "tiers": [
      {
        "tierIndex": 0,
        "credits": 1000,
        "price_cents": 2900,
        "currency": "usd",
        "label": "Starter",
        "billing_interval": "month",
        "trial_days": 14,
        "trial_credits": 250,
        "trial_card_required": false,
        "trial_hard_expiry": true,
        "stripe_price_id": "price_1PxAbC…",
        "stripe_product_id": "prod_QxAbC…",
        "checkout_url": "https://app.yourdomain.com/v1/checkout?id=YOUR_AGENCY_UID&tierIndex=0"
      }
    ],
    "count": 1,
    "max_tiers": 20
  }
}
```

כל דרגה חוזרת עם ה-**`tierIndex`** שלה — המיקום שלה ברשימת התוכניות שלכם, שבאמצעותו שלוש הקריאות האחרות מתייחסות אליה — ועם **`checkout_url`** מוכן לשיתוף, אותו קישור שמופיע בלשונית **Payments**, המפנה כבר ל-[דומיין ה-White Label](white-labeling.md) שבו התוכנית נמכרת.

### הוספת דרגה

גוף הבקשה הוא אובייקט דרגה אחד; הוא מתווסף לסוף הרשימה שלכם.

```bash
curl -X POST "https://api.dmchamp.com/v1/agency/pricing-tiers" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Starter",
    "credits": 1000,
    "price_cents": 2900,
    "currency": "usd",
    "billing_interval": "month",
    "trial_days": 14,
    "trial_credits": 250,
    "trial_card_required": false,
    "trial_hard_expiry": true,
    "features": ["channels_3", "channel_whatsapp_web", "webhooks"]
  }'
```

התגובה מכילה את הדרגה שנוצרה, כולל ה-`tierIndex` שבו היא מוקמה וה-`checkout_url` שלה.

### עריכת דרגה

שלחו רק את השדות שברצונכם לשנות; כל שאר הפרטים בתוכנית יישארו כפי שהיו.

```bash
curl -X PATCH "https://api.dmchamp.com/v1/agency/pricing-tiers/0" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "price_cents": 3900, "trial_hard_expiry": true }'
```

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

### מחיקת דרגה

```bash
curl -X DELETE "https://api.dmchamp.com/v1/agency/pricing-tiers/2" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"
```

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

### השדות בדרגה

| שדה | מה זה |
|---|---|
| `label` / `description` | שם התוכנית, והשורה האופציונלית המוצגת בדף התשלום שלך. |
| `credits` | קרדיטים שהלקוח מקבל **לחודש** בתוכנית חודשית או שנתית, ו-**לתקופת חיוב** בתוכנית שבועית. |
| `price_cents` | מחיר למרווח חיוב, ביחידת המטבע הקטנה ביותר (`2900` = $29.00). בתוכנית שנתית זהו המחיר של כל השנה. |
| `currency` | קוד ISO באותיות קטנות — `usd`, `eur`, `gbp` וכן הלאה. |
| `billing_interval` / `billing_interval_count` | `month` (ברירת המחדל), `year`, או `week` עם ספירה של 1–52 עבור "כל N שבועות". |
| `trial_days` | אורך תקופת ניסיון חינם, 0 עד 90. `0` (או השארתו ריק) אומר ללא תקופת ניסיון. |
| `trial_credits` | קרדיטים שהלקוח מתחיל איתם את תקופת הניסיון. כברירת מחדל ל-`credits` של התוכנית. |
| `trial_card_required` | `false` מאפשר ללקוח להתחיל את תקופת הניסיון ללא הזנת כרטיס. כברירת מחדל ל-`true`. |
| `trial_hard_expiry` | `true` מחזיר קרדיטי ניסיון שלא נוצלו למאגר שלך ונועל את חשבון הלקוח כאשר תקופת ניסיון מסתיימת ללא שדרוג. כברירת מחדל ל-`false` — ראה [Hard expiry after trial](agency-accounts.md#step-3--set-up-pricing-tiers). |
| `rollover_cap_months` | חודשי הקצבה שלקוחות בתוכנית זו רשאים להעביר בין חידושים — מספר מ-0 עד 120, שברים מותרים. `0` לא מעביר דבר; `null` (ברירת המחדל) אומר ללא הגבלה. ראה [Capping what rolls over](sub-accounts.md#capping-what-rolls-over). |
| `rollover_expiry_days` | ימים שאחריהם קרדיטים שלא נוצלו נמחקים בחידוש הבא — מספר שלם מ-1 עד 3650. `null` (ברירת המחדל) אומר שהם לעולם לא פוקעים. |
| `features` / `feature_settings` | מה לקוחות בתוכנית זו מקבלים — אותם מזהי תכונות כמו [Choose which channel types a client can connect](#choose-which-channel-types-a-client-can-connect). |
| `team_seats_limit` | מושבי צוות שהתוכנית מעניקה: מספר מדויק, `0` ללא, `-1` ללא הגבלה. |
| `white_label_config` | באילו מ-[דומייני ה-white label](white-labeling.md#up-to-three-white-labels) שלך התוכנית נמכרת. |

שדות תקופת הניסיון משמעותיים רק בתוכנית שיש בה תקופת ניסיון: שמור שכבה (tier) עם `trial_days: 0` והם יוסרו. מזהי המוצר והמחיר של Stripe עבור התוכנית מנוהלים עבורך ולא ניתן להגדירם ידנית.

שלושה דברים שחשוב להקפיד עליהם:

- **אינדקסי שכבות (Tier indexes) הם מיקומים, לא מזהים קבועים.** מחיקת תוכנית מזיזה כל תוכנית שאחריה מיקום אחד אחורה, לכן יש לאחזר מחדש את הרשימה לאחר כל שינוי — ולהעתיק מחדש את קישורי התשלום שפרסמת, בדיוק כפי שהיית עושה לאחר מחיקת תוכנית בלוח הבקרה.
- **יש להגדיר תחילה את מצב SaaS.** נקודות קצה אלו דורשות חשבון סוכנות עם מיתוג לבן (white labeling) ומפתח Stripe שכבר נשמר; ללא אלו, לא קיים חשבון Stripe שעליו יוכלו לשבת המוצר והמחיר של התוכנית.
- **המכסה היא עשרים תוכניות**, בדיוק כמו בלוח הבקרה. השדה `max_tiers` בתגובת הרשימה מציין את המגבלה הנוכחית.

סכימות הבקשה והתגובה המלאות נמצאות ב-[API Reference](../api/reference.md), תחת **Agency**.

***

## הגדר את המחיר לקרדיט דרך ה-API

`GET /v1/agency/credit-price` · `PATCH /v1/agency/credit-price`

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

### קריאת המחיר הנוכחי

```bash
curl "https://api.dmchamp.com/v1/agency/credit-price" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "data": {
    "price_per_credit_cents": 125,
    "price_per_credit_currency": "brl",
    "note": "USD 0.25 per credit at our reference rate",
    "minimum_cents": 60
  }
}
```

`minimum_cents` הוא המחיר הנמוך ביותר שהפלטפורמה מאפשרת במטבע זה, כך שמשימה יכולה לבדוק מחיר חדש לפני שליחתו. כל שלושת הערכים הם `null` עד להגדרת מחיר.

### שינוי המחיר

```bash
curl -X PATCH "https://api.dmchamp.com/v1/agency/credit-price" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "price_per_credit_cents": 130, "currency": "brl" }'
```

שלח רק את מה שברצונך לשנות. `price_per_credit_cents` הוא המחיר ביחידת המטבע הקטנה ביותר (`130` = R$1.30); `currency` הוא קוד ISO באותיות קטנות; `note` היא שורה אופציונלית של עד 200 תווים המוצגת ללקוחות ישירות מתחת למחיר לקרדיט בדף החיוב שלהם — שימושי למחיר ייחוס במטבע אחר, כגון *"0.25 דולר ארה"ב לקרדיט לפי שער הייחוס שלנו"*. שלח `"note": ""` כדי להסיר אותה. התגובה היא באותו מבנה כמו בקריאה לעיל, כך שמשימה יכולה להשוות ולדלג על הכתיבה כאשר דבר לא השתנה.

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

### תן למשימה מפתח שלא יכול לעשות דבר אחר

הזנת מפתח הסוכנות המלא שלך למתזמן מעניקה גישה רחבה יותר ממה שעדכון מחיר דורש. במקום זאת, צור **מפתח מוגבל (scoped key)** המוגבל לאזור **מחיר קרדיט סוכנות**: מפתח זה יכול לקרוא ולשנות את המחיר לכל קרדיט ותו לא — הוא אינו יכול לגשת לחשבונות משנה, תוכניות, קרדיטים או לחיבור ה-Stripe שלך.

```bash
curl -X POST "https://api.dmchamp.com/v1/api-keys" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "FX price updater", "scopes": { "read_only": false, "tags": ["Agency Credit Price"] } }'
```

התגובה נושאת את המפתח החדש ב-`api_key` **פעם אחת בלבד** — הוא לא יוצג שוב לעולם, לכן שמור אותו מיד. הגדר `"read_only": true` עבור מפתח שצריך רק לקרוא את המחיר, והוסף `"expires_at"` (תאריך בפורמט ISO) אם ברצונך שהוא יפסיק לעבוד מעצמו. רק המפתח של בעל החשבון יכול ליצור מפתחות מוגבלים; הצג או בטל אותם באמצעות `GET /v1/api-keys` ו-`DELETE /v1/api-keys/{id}`.

***

## אפשר לתת-חשבון לקרוא את התמחור שלך

`GET /v1/subaccounts/agency-pricing`

כל נקודת קצה אחרת בדף זה נקראת עם **מפתח הסוכנות שלך**, תוך מיקוד אופציונלי בלקוח באמצעות `sub_account_id`. זו פועלת הפוך: היא נקראת עם **מפתח ה-API של תת-החשבון עצמו**, ללא `sub_account_id`, כך שדף הטעינה של הלקוח (או אינטגרציה שאתה בונה עבורו) יכול להציג את מה שאתה גובה ממנו מבלי לראות לעולם את חשבון הסוכנות שלך.

```bash
curl "https://api.dmchamp.com/v1/subaccounts/agency-pricing" \
  -H "X-API-Key: THE_SUB_ACCOUNTS_OWN_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "data": {
    "tiers": [{ "credits": 1000, "price_cents": 2900, "currency": "usd" }],
    "price_per_credit_cents": 125,
    "price_per_credit_currency": "brl",
    "price_per_credit_note": "USD 0.25 per credit at our reference rate",
    "agency_display_name": "Client Co's Growth Partner"
  }
}
```

זה משקף בדיוק את מה ש-[`GET /v1/agency/pricing-tiers`](#list-your-tiers) ו-[`GET /v1/agency/credit-price`](#read-the-current-price) מחזירים עבורך כסוכנות, פחות כל מה שהלקוח לא צריך לראות (מזהי Stripe, `max_tiers`, וכן הלאה). זה עובד רק עבור חשבון שהוא אכן תת-חשבון עם סוכנות מקושרת — קריאה לזה מחשבון הסוכנות שלך תחזיר שגיאת הרשאה.

***

## דברים שחשוב לזכור

- **השתמש במפתח הסוכנות שלך.** בצע אימות לכל קריאה באמצעות מפתח ה-API של חשבון הסוכנות שלך — לא של חשבון המשנה. הפרמטר `sub_account_id` הוא זה שמפנה את הפעולה.
- **הזיכויים מגיעים מחשבון המשנה.** רכישות וחיובים חוזרים יורדים מיתרת הזיכוי של חשבון המשנה הממוקד, לא מהיתרה שלך.
- **השגיאה `404` פירושה "לא חשבון המשנה שלך".** בדוק שוב את ה-id וודא שמדובר בחשבון שאתה מנהל.
- **הפרמטר הוא אופציונלי בכל מקום שבו הוא מתקבל.** אם תשמיט אותו, אותו endpoint יפעל על חשבון הסוכנות שלך, כך שתוכל לעשות שימוש חוזר באינטגרציה אחת עבור שניהם.

***

## קשור

- [גישת API](../integrations/api-access.md) — אימות, כתובת URL בסיסית, שגיאות, מגבלות קצב.
- [תת-חשבונות](sub-accounts.md) — הצגה וניהול של החשבונות שאליהם ניתן להתמקד.
- [טעינה אוטומטית של תת-חשבון](sub-account-auto-recharge.md) — הענקת אשראי לתת-חשבון באמצעות webhook + API.
- [API של קמפיינים](../api/campaigns.md) — יצירה, עדכון והעתקה של קמפיינים, כולל התייחסות מלאה לשדות.
- [API של חיבור ערוצים](../api/channels.md) — חיבור ערוצים של לקוח וניתובם לקמפיין.
- מדריך Analytics API (בסעיף ה-API) — ריכוז תת-חשבונות של סוכנות וכל נקודת קצה אחרת של דיווח.
- [תמונות מצב](snapshots.md) — מה תמונת מצב לוכדת וכיצד לבנות אחת בלוח הבקרה.