بدء استخدام واجهة برمجة التطبيقات (API) #

تتيح لك واجهة برمجة تطبيقات REST الخاصة بـ Your AI Connector بناء تكاملك الخاص فوق حسابك. يمكنك إنشاء جهات اتصال والبحث عنها، وإدارة الحملات، والأسئلة الشائعة، والمهام والمواعيد، وإرسال الرسائل، وتسجيل خطافات الويب (webhooks)، وقراءة التحليلات، وربط قنوات المراسلة — كل ما تفعله لوحة التحكم، يمكن تنفيذه برمجياً.

هذه هي الصفحة الرئيسية لتوثيق واجهة برمجة التطبيقات. إذا كنت تقوم بربط Your AI Connector بأداة تحتوي بالفعل على تكامل مدمج، فقد لا تحتاج إلى واجهة برمجة التطبيقات على الإطلاق. واجهة برمجة التطبيقات مخصصة للتكاملات المخصصة والأتمتة على نطاق واسع.

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

يتم توجيه كل طلب إلى نفس عنوان الويب الأساسي، وجميع المسارات في هذه المستندات نسبية إليه:

https://api.youraiconnector.com/v1

لذا فإن نقطة نهاية الحملات هي https://api.youraiconnector.com/v1/campaigns، ونقطة نهاية جهات الاتصال هي https://api.youraiconnector.com/v1/contacts، وهكذا.

يجب أن تستخدم جميع الطلبات اتصالاً آمناً (HTTPS). يتم رفض طلبات HTTP العادية.

الحصول على مفتاح واجهة برمجة التطبيقات (API key) #

الوصول إلى واجهة برمجة التطبيقات هو ميزة مدفوعة. إذا كانت خطتك لا تتضمن ذلك، فسيُرجع كل طلب 403 مع هذا المحتوى:

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

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

المصادقة #

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

بالنسبة لبيئة الإنتاج، يُفضل استخدام إحدى صيغ الترويسة (Header) حتى لا يظهر مفتاحك أبداً في سجلات الخادم أو سجل المتصفح. صيغة معامل الاستعلام تعمل دائماً وهي الأبسط لاختبار لمرة واحدة.

راجع المصادقة للحصول على تفصيل كامل لكل طريقة، مع أمثلة وتوجيهات حول متى تستخدم أياً منها.

طلبك الأول #

إليك استدعاء كامل وفعال يسرد الحملات الموجودة في حسابك. يستخدم هذا الاستدعاء مفتاح واجهة برمجة التطبيقات (API key) الخاص بك ويعيد أحدث الحملات أولاً.

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

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

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

تبدو الاستجابة الناجحة كما يلي:

{
  "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، وما إلى ذلك):

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

تتكون الاستجابة الفاشلة من success: false مع رسالة error مفهومة للبشر ورمز error_code رقمي يطابق حالة HTTP:

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

تحقق دائماً من success (أو حالة HTTP) قبل قراءة البيانات. راجع الأخطاء والترقيم للحصول على جدول رموز الحالة الكامل وكيفية التنقل عبر مجموعات النتائج الكبيرة.

حدود المعدل #

تقتصر الطلبات الموثقة على 300 طلب في الدقيقة لكل مفتاح API. هناك أيضاً حد أقصى أوسع يبلغ 1,200 طلب في الدقيقة لكل حساب، ويتم احتساب كل طلب موثق يتم إجراؤه لهذا الحساب.

إذا تجاوزت أياً من الحدين، فستتلقى استجابة 429:

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

توقف مؤقتاً وأعد المحاولة بعد انتظار قصير. يمكنك أيضاً التحقق من استخدامك الحالي في أي وقت باستخدام GET https://api.youraiconnector.com/v1/api-keys/usage، والذي يعيد عدد الطلبات التي استخدمتها في النافذة الحالية وموعد إعادة تعيينها — وهو أمر مفيد لبناء آلية تقييد الطلبات من جانب العميل. راجع مفاتيح واجهة برمجة التطبيقات.

أدلة الموارد #

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

الوكلاء ونقاط الدخول والبث #

وكلاء الذكاء الاصطناعي، ونقاط الدخول، والبث كلها موجودة في مواصفات OpenAPI المنشورة، لذا يمكنك تصفح حقولها الدقيقة وتشغيل طلبات مباشرة عليها في مستكشف API. لكل منها دليل خاص بها: وكلاء الذكاء الاصطناعي، نقاط الدخول، والبث.

قراءة هذه المستندات بصيغة Markdown #

تحتوي كل صفحة في هذه المستندات على نسخة مطابقة بصيغة Markdown: خذ عنوان الصفحة وأضف /index.md إلى نهايته. لذا، هذه الصفحة متاحة أيضاً على https://docs.youraiconnector.com/api/getting-started/index.md، وتظهر كنص عادي بدلاً من صفحة ويب — وهو أمر مفيد عندما ترغب في لصق صفحة في مساعد ذكاء اصطناعي أو سحبها إلى برنامج نصي.

لتصفح المجموعة بأكملها، ابدأ من https://docs.youraiconnector.com/sitemap.xml، الذي يسرد كل صفحة ننشرها. لاحظ أن المستندات مستبعدة عمداً من محركات البحث، لذا فإن جلب هذه العناوين مباشرة هو الطريقة للوصول إليها برمجياً.

لا توجد نقطة نهاية للمستندات محمية بمفتاح ولا يوجد تنزيل مجمع حتى الآن — نسخ Markdown وخريطة الموقع هي الواجهة الكاملة، ولا يحتاج أي منهما إلى مفتاح API.

الخطوات التالية #

• المصادقة — اختر طريقة المصادقة المناسبة لعملية التكامل الخاصة بك.
• الأخطاء والترقيم — تعامل مع الإخفاقات وتصفح النتائج عبر الصفحات.
• الوصول إلى واجهة برمجة التطبيقات — أنشئ مفتاحك واطلع على أمثلة عملية.