# תחילת עבודה עם ה-API

ה-REST API של <span data-t="appName">DM Champ</span> מאפשר לך לבנות אינטגרציה משלך על גבי החשבון שלך. באפשרותך ליצור ולחפש אנשי קשר, לנהל קמפיינים, שאלות נפוצות, משימות ופגישות, לשלוח הודעות, לרשום Webhooks, לקרוא נתונים אנליטיים ולחבר ערוצי הודעות — כל מה שניתן לעשות בלוח הבקרה, מונע על ידי קוד.

זהו דף המרכז של תיעוד ה-API. אם אתה מחבר את <span data-t="appName">DM Champ</span> לכלי שכבר כולל אינטגרציה מובנית, ייתכן שלא תזדקק ל-API כלל. ה-API מיועד לאינטגרציות מותאמות אישית ולאוטומציה בהיקף נרחב.

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


---

## כתובת בסיס (Base URL)

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

```
https://api.dmchamp.com/v1
```

אז נקודת הקצה של סוכני ה-AI היא `https://api.dmchamp.com/v1/agents`, נקודת הקצה של אנשי הקשר היא `https://api.dmchamp.com/v1/contacts`, וכן הלאה.

כל הבקשות חייבות להשתמש בחיבור מאובטח (HTTPS). בקשות HTTP רגילות נדחות.

---

## קבלת מפתח API

גישת API היא **תכונה בתשלום**. אם התוכנית שלך אינה כוללת אותה, כל בקשה תחזיר `403` עם גוף ההודעה הבא:

```json
{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}
```

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

---

## אימות

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

| שיטה | כיצד | הכי מתאים ל- |
|---|---|---|
| פרמטר שאילתה | `?apiKey=YOUR_API_KEY` | בדיקות מהירות, כתובות URL בדפדפן, הגדרות ישנות |
| כותרת (Header) | `X-API-Key: YOUR_API_KEY` | אינטגרציות בסביבת ייצור |
| כותרת Bearer | `Authorization: Bearer YOUR_API_KEY` | אינטגרציות בסביבת ייצור |
| אסימון Firebase ID | `Authorization: Bearer <ID token>` | הפעלות של אפליקציות צד ראשון בלבד |

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

עיין ב-[אימות](authentication.md) לפירוט מלא של כל שיטה, עם דוגמאות והנחיות מתי להשתמש בכל אחת.

---

## הבקשה הראשונה שלך

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

**cURL**

```bash
curl "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY&view=summary"
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/agents?view=summary", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.agents);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.dmchamp.com/v1/agents",
    params={"view": "summary"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["agents"])
```

תגובה מוצלחת נראית כך:

```json
{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}
```

---

## תגובות הצלחה ושגיאה

כל תגובת JSON מכילה דגל `success` כך שתוכל לבצע הסתעפות לפיו מבלי לנתח קודי סטטוס.

תגובה מוצלחת היא `success: true` בתוספת הנתונים עבור נקודת הקצה ההיא (שם השדה משתנה — `campaigns`, `contacts`, `data`, וכן הלאה):

```json
{
  "success": true,
  "campaigns": []
}
```

תגובה שנכשלה היא `success: false` עם הודעת `error` קריאה לבני אדם ו-`error_code` מספרי התואם לסטטוס ה-HTTP:

```json
{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}
```

בדוק תמיד את `success` (או את סטטוס ה-HTTP) לפני קריאת הנתונים. עיין ב-[שגיאות ועימוד](errors-and-pagination.md) עבור טבלת קודי הסטטוס המלאה וכיצד לדפדף בין קבוצות תוצאות גדולות.

---

## מגבלות קצב

בקשות מאומתות מוגבלות ל-**300 בקשות לדקה** לכל מפתח API. קיימת גם תקרה רחבה יותר של **1,200 בקשות לדקה לכל חשבון**, המחשבת כל בקשה מאומתת שבוצעה עבור אותו חשבון.

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

אם תעבור את אחת מהמגבלות, תקבל תגובת `429`:

```json
{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}
```

המתן ונסה שוב לאחר הפסקה קצרה. באפשרותך גם לבדוק את השימוש הנוכחי שלך בכל עת באמצעות `GET https://api.dmchamp.com/v1/api-keys/usage`, שמחזיר כמה בקשות ניצלת בחלון הנוכחי ומתי הוא מתאפס — שימושי לבניית מנגנון הגבלה (throttling) בצד הלקוח. עיין ב-[מפתחות API](api-keys.md).

---

## מדריכי משאבים

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

| משאב | מה הוא מכסה |
|---|---|
| [סוכני AI](agents.md) | יצירה והגדרה של סוכני AI: הגדרות, שעות פעילות, ידע, כללי תיוג, כלים, מדיה וטיוטות |
| [נקודות כניסה](entry-points.md) | החלטה איזה סוכן AI יענה לשיחה חדשה: ברירות מחדל של ערוצים, סוכן אחד לכל מספר WhatsApp, מילות מפתח, כללי תגובות ועוקבים |
| [שידורים](broadcasts.md) | יצירה, תמחור, הפעלה, השהיה ושכפול של שליחות חד-פעמיות לרשימת אנשי קשר |
| [קמפיינים](campaigns.md) | יצירה, עדכון, שכפול, הפעלה, ארכוב ובדיקה של קמפיינים והגדרות הבוט שלהם |
| [אנשי קשר](contacts.md) | יצירה, חיפוש, הצגה ברשימה, עדכון, ייבוא, תיוג ומחיקה של אנשי קשר |
| [שאלות נפוצות](faqs.md) | ניהול ערכי שאלות ותשובות שבהם משתמש עוזר ה-AI שלך, וקישורם לקמפיינים |
| [מאגר ידע](knowledge-base.md) | ייבוא אתרים ומסמכים לידע של ה-AI שלך וריכוז שאלות נפוצות לקבוצות |
| [משימות](tasks.md) | יצירה וניהול של משימות CRM, שלבי לוח וסוגי משימות |
| [הודעות](messages.md) | שליחת הודעות יוצאות וקריאת היסטוריית שיחות |
| [פגישות](appointments.md) | קביעה, תזמון מחדש, ביטול ומחיקה של פגישות |
| [ערוצים](channels.md) | חיבור וניתוק של ערוצי הודעות, רכישת מספרים והגדרת סוכן ה-AI שיענה לשיחות חדשות בכל ערוץ |
| [תבניות](templates.md) | יצירה, הגשה ובדיקת סטטוס האישור של תבניות הודעות WhatsApp |
| [ניתוח נתונים](analytics.md) | קריאת נתונים סטטיסטיים יומיים של אירועי הודעות, ניצול קרדיטים וסיכום עלויות AI |
| [Webhooks](webhooks.md) | רישום נקודות קצה לקבלת התראות על אירועים בזמן אמת |
| [צוות](team.md) | ניהול חברי צוות, הזמנות, תפקידים, הרשאות ומחלקות |
| [מפתחות API](api-keys.md) | בדיקה, החלפה וביטול של מפתח ה-API שלך, בדיקת ניצול מגבלת הקצב ויצירת מפתחות נוספים עם גישה מוגבלת |

### סוכנים, נקודות כניסה ושידורים

סוכני AI, נקודות כניסה ושידורים נמצאים כולם במפרט ה-OpenAPI המפורסם, כך שתוכל לעיין בשדות המדויקים שלהם ולהריץ בקשות חיות מולם ב-[סייר ה-API](reference.md). לכל אחד מהם יש מדריך משלו: [סוכני AI](agents.md), [נקודות כניסה](entry-points.md) ו-[שידורים](broadcasts.md).

::: master-only
היותם במפרט אומר גם שנקודות קצה אלו מופיעות ככלים עבור כל עוזר AI שאתה [מחבר דרך MCP](../integrations/connect-ai-clients.md).
:::

---

## קריאת תיעוד זה כ-Markdown

לכל דף בתיעוד זה יש תאום בפורמט Markdown פשוט: קחו את כתובת הדף והוסיפו `/index.md` בסופה. לכן, דף זה זמין גם בכתובת `https://docs.dmchamp.com/api/getting-started/index.md`, והוא מוחזר כטקסט פשוט במקום כדף אינטרנט — שימושי כאשר ברצונכם להדביק דף בתוך עוזר בינה מלאכותית או למשוך אותו לתוך סקריפט.

עבור עוזר בינה מלאכותית או סקריפט שאמור לקרוא את כל הסט, קיימים שני קבצים מוכנים מראש:

- `https://docs.dmchamp.com/llms.txt` — האינדקס: כל דף עם סיכום בשורה אחת וקישור לתאום ה-Markdown שלו, מקובצים באותו אופן שבו הם מופיעים בסרגל הצד.
- `https://docs.dmchamp.com/llms-full.txt` — כל התיעוד בקובץ Markdown אחד. כל דף מתחיל בכותרת שלו ובשורה `Source:` המכילה את כתובת הדף, כך שעוזר יכול לציין מאיפה הגיעה תשובה.

שניהם קיימים גם עבור כל שפה, תחת קידומת השפה (`https://docs.dmchamp.com/nl/llms.txt`, `https://docs.dmchamp.com/es/llms-full.txt`, וכן הלאה). תן לעוזר שלך את הכתובת `llms.txt` והוא ימשוך את הדפים שהוא צריך, או תן לו את `llms-full.txt` כאשר הוא אמור לקבל את הכל בהקשר אחד. הם נבנים מחדש עם כל שינוי בתיעוד, כך שהם לעולם לא מתיישנים.

כדי לעבור על הדפים בעצמך, `https://docs.dmchamp.com/sitemap.xml` מפרט את כל הדפים שאנו מפרסמים. התיעוד מורחק בכוונה ממנועי חיפוש, לכן משיכת כתובות אלו ישירות היא הדרך להגיע אליו מתוך קוד.

שום דבר מזה לא דורש מפתח API: תאומי ה-Markdown, שני קבצי ה-`llms` ומפת האתר הם כל הממשק.

---

## צעדים הבאים

- [אימות](authentication.md) — בחר את שיטת האימות המתאימה לאינטגרציה שלך.
- [שגיאות ועימוד](errors-and-pagination.md) — טיפול בכשלים ודפדוף בין תוצאות.
- [גישת API](../integrations/api-access.md) — יצירת המפתח שלך וצפייה בדוגמאות עבודה.