# الوصول إلى واجهة برمجة التطبيقات (API)

واجهة برمجة التطبيقات (API) هي وسيلة تتيح لأنظمة البرمجيات المختلفة التواصل مع بعضها البعض. تتيح لك واجهة برمجة تطبيقات <span data-t="appName">Your AI Connector</span> (أو لمطورك) إنشاء جهات اتصال، وإرسال رسائل، وإدارة قوائم، واستقبال رسائل واردة من قنوات مخصصة تلقائياً — كل ذلك دون الحاجة لاستخدام لوحة التحكم.


**لماذا تستخدم واجهة برمجة التطبيقات (API)؟** إذا كنت ترغب في ربط التطبيق بأداة لا تحتوي على تكامل مدمج، أو كنت بحاجة إلى أتمتة المهام المتكررة على نطاق واسع، فإن واجهة برمجة التطبيقات هي الطريقة المثلى للقيام بذلك.

::: note
**ملاحظة:** هذه الصفحة ذات طبيعة تقنية أكثر. إذا كنت صاحب عمل ولست مطوراً، فقد ترغب في مشاركة هذه الصفحة مع فريقك التقني أو مع مطور مستقل.
:::


---

## إنشاء مفتاح واجهة برمجة التطبيقات (API Key) الخاص بك

::: note
**ملاحظة:** الوصول إلى واجهة برمجة التطبيقات هو ميزة مدفوعة متاحة في الخطط المؤهلة. إذا كانت خطتك لا تتضمن هذه الميزة، فسيتم رفض طلبات واجهة برمجة التطبيقات مع استجابة `403`. تحقق من خطتك أو اتصل بالدعم إذا لم تكن متأكداً مما إذا كان الوصول إلى واجهة برمجة التطبيقات مفعلاً.
:::


1. في الشريط الجانبي الأيسر، انقر على **الإعدادات** (أيقونة الترس).
2. في الشريط الجانبي للإعدادات، ضمن مجموعة **التكاملات** (Integrations)، انقر على **مفتاح واجهة برمجة التطبيقات** (API Key).


3. إذا لم يكن لديك مفتاح بعد، انقر على **Generate API key**.
4. إذا كان لديك مفتاح بالفعل، فسيظهر مخفياً تحت **Your key**. إذا كان مفتاحك يدعم ذلك، انقر على **Show** لإظهاره، ثم **Copy** لنسخه — ستظهر لك رسالة تأكيد.
5. احفظ المفتاح في مكان آمن — ستحتاج إليه في كل طلب API.


::: note
**ملاحظة:** قد تظهر لبعض الحسابات عبارة "Your key can't be displayed" بدلاً من عناصر التحكم بالإظهار/النسخ — يحدث هذا للمفاتيح التي تم إنشاؤها قبل أن يتمكن التطبيق من إعادة عرضها. لا يزال المفتاح يعمل بشكل طبيعي؛ ولن تحتاج إلى **Regenerate** (الموجودة أسفل بطاقة المفتاح في نفس القسم) إلا إذا كنت بحاجة فعلية لرؤية النص الصريح للمفتاح مرة أخرى. تؤدي إعادة التوليد إلى إبطال المفتاح القديم فوراً وتعطيل أي تكامل يستخدمه حتى تقوم بلصق المفتاح الجديد — لذا قم بتحديث تكاملاتك مباشرة بعد ذلك.
:::


::: warning
**هام:** مفتاح واجهة برمجة التطبيقات الخاص بك يشبه كلمة المرور — فهو يمنح وصولاً كاملاً إلى حسابك. لا تشاركه علناً أو تنشره في أي مكان يمكن للآخرين رؤيته فيه. إذا كنت تعتقد أن مفتاحك قد تعرض للاختراق، قم بإعادة إنشائه على الفور.
:::


> **أعضاء الفريق:** ينتمي مفتاح واجهة برمجة التطبيقات (API key) إلى مالك الحساب، لذا إذا قمت بتسجيل الدخول كعضو فريق مدعو (بما في ذلك المسؤول)، فسيظهر القسم ملاحظة بدلاً من المفتاح. قم بتسجيل الدخول كمالك للحساب لعرضه أو نسخه أو إعادة إنشائه — وينطبق ذلك أيضاً على المفاتيح ذات النطاق المحدد.

> **أين تجده:** **مفتاح واجهة برمجة التطبيقات** (API Key) هو قسم خاص به ضمن الإعدادات ← التكاملات، منفصل عن **خطافات الويب** (Webhooks). إذا أخبرك دليل أو زميل بالبحث عن المفتاح ضمن "خطافات الويب"، فابحث في القسم المجاور بدلاً من ذلك.

---

## عنوان URL الأساسي

تستخدم جميع طلبات واجهة برمجة التطبيقات عنوان الويب الأساسي التالي:

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

---

## المصادقة

يجب أن يتضمن كل طلب مفتاح واجهة برمجة التطبيقات الخاص بك حتى تعرف المنصة أنك أنت. الطريقة الأبسط هي إضافته إلى نهاية عنوان الويب:

```
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).

---

## عمليات واجهة برمجة التطبيقات الشائعة

### إنشاء جهة اتصال

**الطلب:**

```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
**ملاحظة:** إذا كانت جهة الاتصال التي تحمل نفس رقم الهاتف موجودة بالفعل، فإن واجهة برمجة التطبيقات **لا** تنشئ جهة الاتصال هذه ولا تعيدها — بل تعيد `{ "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، يتم إرسال الرسائل من خلال البث والحملات ووكلاء الذكاء الاصطناعي.
:::


---

### تلقي الرسائل الواردة (قناة مخصصة)

استقبل الرسائل من أنظمة خارجية كقناة مخصصة. هذه هي الطريقة التي ترسل بها عمليات التكامل مثل 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` | قبول رسالة من نظام خارجي |

---

## تحديد معدل الطلبات

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.

---

## أفضل الممارسات

- **خزّن مفتاح واجهة برمجة التطبيقات الخاص بك بشكل آمن** — استخدم مدير كلمات مرور أو تكويناً من جانب الخادم، ولا تضعه أبداً في كود من جانب العميل يمكن لزائر المتصفح قراءته.
- **قم دائماً بتضمين رمز البلد** في أرقام الهواتف (`+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) — تلقي إشعارات في الوقت الفعلي من التطبيق (قسم منفصل عن مفتاح واجهة برمجة التطبيقات الخاص بك).
- [ربط مساعدي الذكاء الاصطناعي (MCP)](connect-ai-clients.md) — استخدم نفس مفتاح واجهة برمجة التطبيقات للسماح لـ Claude بإدارة حسابك.
- [نماذج عملاء فيسبوك](facebook-lead-forms.md) — استخدم واجهة برمجة التطبيقات مع منصات الأتمتة لجذب العملاء المحتملين.
- [تكامل GoHighLevel](ghl-integration.md) — مثال كامل لتكامل واجهة برمجة التطبيقات ثنائي الاتجاه.