# גישת API

ממשק תכנות יישומים (API) הוא דרך המאפשרת למערכות תוכנה שונות לתקשר זו עם זו. ה-API של <span data-t="appName">Your AI Connector</span> מאפשר לך (או למפתח שלך) ליצור אנשי קשר באופן אוטומטי, לשלוח הודעות, לנהל רשימות ולקבל הודעות נכנסות מערוצים מותאמים אישית — הכל מבלי להשתמש בלוח הבקרה.


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

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


---

## יצירת מפתח ה-API שלך

::: note
**הערה:** גישת API היא תכונה בתשלום הזמינה בתוכניות מתאימות. אם התוכנית שלך אינה כוללת זאת, בקשות API יידחו עם תגובת `403`. בדוק/י את התוכנית שלך או פנה/י לתמיכה אם אינך בטוח/ה אם גישת ה-API מופעלת.
:::


1. בסרגל הצד השמאלי, לחץ/י על **הגדרות** (סמל גלגל השיניים).
2. בסרגל הצד של ההגדרות, תחת הקבוצה **אינטגרציות**, לחץ/י על **מפתח API**.


3. אם עדיין אין לך מפתח, לחץ על **Generate API key**.
4. אם כבר יש לך מפתח, הוא יוצג מוסתר תחת **Your key**. אם המפתח שלך תומך בכך, לחץ על **Show** כדי לחשוף אותו, ולאחר מכן על **Copy** כדי להעתיק אותו — תראה הודעת אישור קופצת.
5. שמור את המפתח במקום בטוח — תזדקק לו עבור כל בקשת API.


::: note
**הערה:** חלק מהחשבונות רואים "Your key can't be displayed" במקום פקד Show/Copy — זה קורה עבור מפתחות שנוצרו לפני שהאפליקציה יכלה להציג אותם שוב. המפתח עדיין עובד כרגיל; עליך להשתמש ב-**Regenerate** (מתחת לכרטיס המפתח, באותו מקטע) רק אם אתה באמת צריך לראות את הטקסט הגלוי שוב. יצירה מחדש מבטלת את המפתח הישן באופן מיידי ומשביתה כל אינטגרציה המשתמשת בו עד שתדביק את המפתח החדש — עדכן את האינטגרציות שלך מיד לאחר מכן.
:::


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


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

> **איפה למצוא אותו:** **מפתח API** הוא סעיף נפרד תחת הגדרות ← אינטגרציות, נפרד מ-**Webhooks**. אם מדריך או קולגה אומרים לך לחפש את המפתח תחת "Webhooks", חפש/י במקום זאת בסעיף הסמוך.

---

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

כל בקשות ה-API משתמשות בכתובת האינטרנט הבסיסית הבאה:

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

---

## אימות

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

```
https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
```

ניתן גם לשלוח את המפתח ככותרת בקשה (request header) במקום בתוך ה-URL (מומלץ עבור סביבת ייצור, כדי שהמפתח לא יופיע ביומני השרת):

```
X-API-Key: YOUR_API_KEY
```
```
Authorization: Bearer YOUR_API_KEY
```

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

> **מחפש את מדריכי המפתחים המלאים?** דף זה מהווה מבוא מהיר המכסה את הפעולות הנפוצות ביותר. למדריכים מלאים, צעד אחר צעד — הכוללים את כל המשאבים, עם דוגמאות ב-cURL, JavaScript ו-Python — עיין ב-[תחילת עבודה עם ה-API](../api/getting-started.md) וב-[תיעוד ה-API](../api/reference.md).

---

## פעולות API נפוצות

### יצירת איש קשר

**בקשה:**

```http
POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}
```

**שדות חובה:** `phoneNumber` (עם קידומת מדינה) נדרש תמיד כדי ליצור איש קשר. כתובת אימייל בלבד אינה מספיקה — בקשה ללא מספר טלפון תקין תידחה. האימייל הוא אופציונלי.

**תגובה:**

```json
{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}
```

שמור/י את `data.contactId` — תזדקק/י לו עבור הקריאה "הוספת איש קשר לרשימה".

::: note
**הערה:** אם איש קשר עם אותו מספר טלפון כבר קיים, ה-API **לא** יוצר או מחזיר את איש הקשר הזה — הוא מחזיר `{ "success": false, "error_code": 409 }`. חפש/י תחילה את איש הקשר הקיים באמצעות `GET https://api.youraiconnector.com/v1/contacts?phoneNumber=...`.
:::


---

### הוספת איש קשר לרשימה

```http
POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}
```

מצא את מזהה הרשימה (ID) באפליקציה תחת **אנשי קשר ← רשימות**, מתוך תפריט השורה של הרשימה (**העתק מזהה רשימה**).

---

### עדכון איש קשר

```http
PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}
```

רק השדות שכללת ישתנו. זוהי גם הדרך לטעינה מרוכזת של ערכי שדות מותאמים אישית לאחר ייבוא — עיין ב-[שדות מותאמים אישית, פרופיל ליד והערות](../get-started/custom-contact-fields.md#bulk-loading-custom-fields). פרטים מלאים ב-[API של אנשי קשר](../api/contacts.md).

---

### שליחת הודעה (ערוץ מותאם אישית)

```http
POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}
```

| שדה | חובה | תיאור |
|---|---|---|
| `customData.fromId` | כן | המזהה של איש הקשר בפלטפורמה שלך |
| `customData.customChannel` | כן | שם הערוץ המותאם אישית שלך |
| `customData.body` | כן | טקסט ההודעה לשליחה |
| `customData.campaignId` | לא | ניתוב ההודעה לקמפיין ספציפי |
| `customData.firstName` | לא | שם פרטי של איש הקשר (בשימוש בעת יצירת איש קשר חדש) |
| `customData.lastName` | לא | שם משפחה של איש הקשר |
| `customData.email` | לא | כתובת האימייל של איש הקשר |

::: note
**הערה:** נקודת קצה זו מיועדת להודעות בערוץ מותאם אישית. עבור WhatsApp, SMS, Instagram ו-Messenger, הודעות נשלחות דרך שידורים (Broadcasts), קמפיינים וסוכני AI.
:::


---

### קבלת הודעות נכנסות (ערוץ מותאם אישית)

קבלת הודעות ממערכות חיצוניות כערוץ מותאם אישית. כך אינטגרציות כמו GoHighLevel שולחות הודעות אל <span data-t="appName">Your AI Connector</span>. עיין ב[ערוצים מותאמים אישית](../messaging-channels/custom-channels.md) לפרטים מלאים.

```http
POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}
```

| שדה | נדרש | תיאור |
|---|---|---|
| `customData.messageSid` | כן | מזהה ייחודי להודעה זו (מונע כפילויות). ניתן להשתמש גם ב-`customData.id`. |
| `customData.fromId` | כן | המזהה של השולח במערכת החיצונית שלך. |
| `customData.toId` | כן | מזהה העסק שלך. |
| `customData.body` | כן | טקסט ההודעה. |
| `customData.channel` | לא | תווית עבור המקור (למשל, `"email"`, `"livechat"`, `"custom"`). |
| `customData.status` | לא | סטטוס הודעה. ברירת המחדל היא `"received"`. |
| `messageType` | לא | `"text"` עבור הודעות טקסט, `"reaction"` עבור תגובות אימוג'י. |

---

## סקירת פעולות זמינות

| פעולה | שיטה | כתובת | תיאור |
|---|---|---|---|
| יצירת איש קשר | `POST` | `/contacts` | הוספת איש קשר חדש לחשבון שלך |
| קבלת פרטי איש קשר | `GET` | `/contacts?phoneNumber=X` או `/contacts?email=X` | חיפוש איש קשר לפי מספר טלפון או אימייל |
| עדכון איש קשר | `PUT` | `/contacts/{contactId}` | עדכון כל שדה אצל איש קשר קיים |
| הוספת איש קשר לרשימה | `POST` | `/contacts/lists` | הוספת איש קשר קיים לרשימה ספציפית |
| שליחת הודעה | `POST` | `/send_custom_channel_message` | שליחת הודעה דרך ערוץ מותאם אישית |
| קבלת הודעה | `POST` | `/incoming_custom_channel_message` | קבלת הודעה ממערכת חיצונית |

---

## הגבלת קצב (Rate Limiting)

The API enforces rate limits to ensure platform stability. Exceeding your limit returns `429 Too Many Requests` — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in [import feature](../get-started/importing-contacts.md) or email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) for guidance.

---

## שיטות עבודה מומלצות

- **שמור את מפתח ה-API שלך בצורה מאובטחת** — השתמש במנהל סיסמאות או בהגדרות צד-שרת, לעולם לא בקוד צד-לקוח שגולש בדפדפן יכול לקרוא.
- **כלול תמיד את קידומת המדינה** במספרי טלפון (`+1` עבור ארה"ב, `+44` עבור בריטניה, `+31` עבור הולנד).
- **טפל בשגיאות בצורה אלגנטית** — בדוק קודי סטטוס וקרא את הודעות השגיאה המוחזרות.
- **טפל בכפילויות** — מספר טלפון כפול יחזיר `{ "success": false, "error_code": 409 }` במקום איש קשר חדש. חפש את איש הקשר תחילה אם עליך לעבוד איתו.
- **בדוק עם קבוצת נתונים קטנה** לפני הרצת פעולות מרוכזות.

---

## תגובות שגיאה

```json
{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}
```

| Status Code | Meaning |
|---|---|
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request — check your parameters |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — your plan doesn't include API access, or you lack permission |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Server error — email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) if this persists |

---

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

- [Webhooks](webhooks.md) — קבל התראות בזמן אמת מהאפליקציה (סעיף נפרד ממפתח ה-API שלך).
- [חיבור עוזרי AI (MCP)](connect-ai-clients.md) — השתמש באותו מפתח API כדי לאפשר ל-Claude לנהל את החשבון שלך.
- [טפסי לידים של פייסבוק](facebook-lead-forms.md) — השתמש ב-API עם פלטפורמות אוטומציה כדי ללכוד לידים.
- [אינטגרציית GoHighLevel](ghl-integration.md) — דוגמה לאינטגרציית API דו-כיוונית מלאה.