مرجع API

ما هو

مرجع API الخاص بـ BotBat هو التوثيق التقني الشامل لواجهة REST API التي تشغّل كل ميزة في المنصة. يوفر مواصفات تفصيلية للمصادقة باستخدام Bearer tokens، واتفاقيات عنوان URL الأساسي والإصدارات، وصيغ الطلبات والاستجابات، وترقيم الصفحات القائم على المؤشر، ورموز الأخطاء الموحدة، وحدود المعدل لكل نقطة نهاية. كل عملية يمكنك تنفيذها في لوحة تحكم BotBat لها نقطة نهاية API مقابلة، مما يجعل من الممكن أتمتة سير عمل الرسائل وإدارة جهات الاتصال والحملات بالكامل.

تتبع API مبادئ التصميم RESTful. يتم تحديد الموارد بمسارات URL، وتشير طرق HTTP القياسية إلى العملية (GET للقراءة، POST للإنشاء، PUT/PATCH للتحديث، DELETE للحذف)، ويستخدم جميع تبادل البيانات صيغة JSON. استراتيجية الإصدارات قائمة على URL: الإصدار الحالي هو v1، والإصدارات المستقبلية ستستخدم /v2 و/v3 وما إلى ذلك، مما يضمن التوافق مع الإصدارات السابقة للتكاملات القائمة مع السماح لـ API بالتطور.

يتجاوز مرجع API التفاعلي، الذي يمكن الوصول إليه من قسم المطور في لوحة تحكم BotBat، التوثيق الثابت. يتضمن لوحة "جرّب الآن" المدمجة حيث يمكنك إنشاء الطلبات وتنفيذها مقابل بيئة الاختبار وفحص الاستجابة الكاملة بما في ذلك الترويسات ورموز الحالة وأجسام JSON. هذا يجعله أسرع طريقة لاستكشاف API وفهم سلوك كل نقطة نهاية قبل كتابة أي كود تكامل.

متى تستخدمه

السيناريو	الوصف
بدء تكامل API جديد	ابدأ هنا لفهم عنوان URL الأساسي وآلية المصادقة والأنماط الشائعة قبل كتابة أي كود.
البحث عن نقطة نهاية محددة	اعثر على صيغة الطلب الدقيقة والمعلمات المطلوبة والمعلمات الاختيارية وشكل الاستجابة المتوقع لأي عملية API.
تصحيح استجابة خطأ	ارجع إلى جدول رموز الأخطاء لفهم ما يعنيه رمز حالة HTTP معين وجسم الخطأ وكيفية حل المشكلة.
تنفيذ ترقيم الصفحات	تعلّم كيفية استخدام ترقيم الصفحات القائم على المؤشر للتنقل بكفاءة عبر مجموعات النتائج الكبيرة دون تفويت أو تكرار السجلات.
فهم حدود المعدل لكل نقطة نهاية	تحقق من حد المعدل لنقطة نهاية محددة لتصميم تردد طلبات تكاملك بشكل مناسب.
تأهيل مطورين جدد	شارك مرجع API مع أعضاء الفريق الجدد حتى يتمكنوا من الاعتماد على أنفسهم عند بناء أو صيانة التكاملات.

الخطوات

1. تحديد عنوان URL الأساسي

تستخدم جميع طلبات API عنوان URL الأساسي https://api.botbat.com/v1. يتم تضمين رقم الإصدار في مسار URL. عند إصدار نسخة جديدة، ستستمر نقاط نهاية v1 الحالية في العمل لفترة إهمال موثقة، مما يمنحك الوقت للترحيل.

2. مصادقة طلباتك

أدرج مفتاح API الخاص بك كـ Bearer token في ترويسة Authorization لكل طلب. الصيغة هي Authorization: Bearer YOUR_API_KEY. تتلقى الطلبات بدون رمز صالح استجابة HTTP 401. يتم إنشاء وإدارة مفاتيح API في لوحة معلومات المطورين. كل مفتاح مقيد بصلاحيات محددة، لذا تأكد من أن مفتاحك يمتلك الصلاحيات المطلوبة لنقاط النهاية التي تنوي استدعاءها.

3. تعيين ترويسات الطلب

يجب أن تتضمن جميع الطلبات Content-Type: application/json وAccept: application/json. يتم ترميز أجسام الطلبات بصيغة JSON، وتُرجع جميع الاستجابات بصيغة JSON. تستخدم عمليات الرفع الثنائية (مثل استيراد CSV) صيغة multipart/form-data بدلاً من ذلك.

4. إرسال طلب

أنشئ طلب HTTP بالطريقة المناسبة (GET، POST، PUT، PATCH، DELETE)، ومسار نقطة النهاية، ومعلمات الاستعلام للتصفية وترقيم الصفحات، وجسم طلب JSON لعمليات الإنشاء والتحديث. يوفر التوثيق التفاعلي مقتطفات كود جاهزة للنسخ بلغات cURL وJavaScript وPython وPHP لكل نقطة نهاية.

5. استخدام لوحة "جرّب الآن"

تتيح لك لوحة جرّب الآن في التوثيق التفاعلي تنفيذ الطلبات مباشرة من المتصفح. حدد نقطة نهاية، واملأ المعلمات وجسم الطلب، وأرفق مفتاح API الخاص ببيئة الاختبار، وانقر إرسال. تعرض اللوحة الاستجابة الكاملة بما في ذلك حالة HTTP وترويسات الاستجابة وجسم JSON.

هذه هي أسرع طريقة لاستكشاف نقاط النهاية غير المألوفة والتحقق من أن حمولات طلباتك مُنظمة بشكل صحيح قبل دمجها في قاعدة الكود الخاصة بك.

6. التعامل مع ترقيم الصفحات

تُرجع نقاط نهاية القوائم نتائج مرقمة. تتضمن كل استجابة مصفوفة data تحتوي على الصفحة الحالية من النتائج وحقل cursor. لاسترجاع الصفحة التالية، أدرج ?cursor=RETURNED_CURSOR كمعلمة استعلام في طلبك التالي. عندما يكون حقل cursor بقيمة null، تكون قد وصلت إلى نهاية مجموعة النتائج. حجم الصفحة الافتراضي هو 25 عنصراً، ويمكنك تعديله بمعلمة الاستعلام limit (الحد الأقصى 100).

7. تحليل الاستجابات الناجحة

تُرجع الاستجابات الناجحة HTTP 200 لعمليات القراءة والتحديث، أو HTTP 201 لعمليات الإنشاء. يحتوي جسم الاستجابة على البيانات المطلوبة. لنقاط نهاية المورد الواحد، تُرجع البيانات مباشرة. لنقاط نهاية القوائم، تتضمن الاستجابة data (مصفوفة من الموارد) وcursor (لترقيم الصفحات) وtotal (العدد الإجمالي للموارد المطابقة).

8. معالجة الأخطاء

تتضمن استجابات الأخطاء رمز حالة HTTP، وكائن error يحتوي على رمز code قابل للقراءة آلياً، ورسالة message قابلة للقراءة بشرياً، واختيارياً مصفوفة details لأخطاء التحقق. تحقق دائماً من رمز الحالة أولاً، ثم حلل جسم الخطأ للتفاصيل.

نقاط النهاية الرئيسية

API الحملات

الطريقة	نقطة النهاية	الوصف
GET	/v1/campaigns	عرض قائمة الحملات، قابلة للتصفية حسب الحالة ونطاق التاريخ
POST	/v1/campaigns	إنشاء حملة جديدة
GET	/v1/campaigns/:id	الحصول على تفاصيل الحملة
PUT	/v1/campaigns/:id	تحديث حملة
DELETE	/v1/campaigns/:id	حذف حملة مسودة
POST	/v1/campaigns/:id/send	إرسال أو جدولة حملة

تتيح لك API الحملات إنشاء وإدارة وإرسال الحملات برمجياً. يمكنك تصفية قوائم الحملات حسب الحالة (draft، scheduled، sending، completed، failed) وحسب نطاق التاريخ. تقبل نقطة نهاية POST /send معلمات جدولة اختيارية؛ حذفها يرسل الحملة فوراً.

API جهات الاتصال

الطريقة	نقطة النهاية	الوصف
GET	/v1/contacts	عرض قائمة جهات الاتصال، قابلة للتصفية حسب الشريحة والوسم والتاريخ
POST	/v1/contacts	إنشاء جهة اتصال
GET	/v1/contacts/:id	الحصول على تفاصيل جهة الاتصال
PUT	/v1/contacts/:id	تحديث جهة اتصال
DELETE	/v1/contacts/:id	حذف جهة اتصال
GET	/v1/contacts/search?q=	البحث في جهات الاتصال بالاسم أو البريد الإلكتروني أو رقم الهاتف
POST	/v1/contacts/import	استيراد جماعي لجهات الاتصال عبر رفع ملف CSV

تدعم API جهات الاتصال عمليات CRUD الكاملة بالإضافة إلى البحث والاستيراد الجماعي. تُجري نقطة نهاية البحث مطابقة تقريبية عبر حقول الاسم والبريد الإلكتروني ورقم الهاتف. تقبل نقطة نهاية الاستيراد ملف CSV عبر multipart/form-data وتُرجع معرّف مهمة يمكنك الاستعلام عنه لمعرفة حالة الاكتمال.

API الرسائل

الطريقة	نقطة النهاية	الوصف
POST	/v1/messages/send	إرسال رسالة إلى جهة اتصال
GET	/v1/messages/:id	الحصول على تفاصيل الرسالة وحالة التسليم

تتعامل API الرسائل مع إرسال الرسائل الفردية وتتبع حالتها. تتطلب نقطة نهاية الإرسال contact_id وchannel (مثل whatsapp أو sms) وإما template_id أو body للرسائل الحرة. تُرجع نقطة نهاية الحالة دورة حياة التسليم الكاملة: queued وsent وdelivered وread أو failed.

API المحادثات

الطريقة	نقطة النهاية	الوصف
GET	/v1/conversations	عرض قائمة المحادثات، قابلة للتصفية حسب الحالة والوكيل المُعيّن
GET	/v1/conversations/:id	الحصول على تفاصيل المحادثة مع سجل الرسائل
POST	/v1/conversations/:id/assign	تعيين محادثة لوكيل
POST	/v1/conversations/:id/resolve	حل محادثة

API القوالب

الطريقة	نقطة النهاية	الوصف
GET	/v1/templates	عرض قائمة قوالب الرسائل
POST	/v1/templates	إنشاء قالب
GET	/v1/templates/:id	الحصول على تفاصيل القالب
PUT	/v1/templates/:id	تحديث قالب
DELETE	/v1/templates/:id	حذف قالب
POST	/v1/templates/:id/submit	تقديم قالب للموافقة من WhatsApp

API الـ Webhooks

الطريقة	نقطة النهاية	الوصف
GET	/v1/webhooks	عرض قائمة نقاط نهاية webhook
POST	/v1/webhooks	إنشاء نقطة نهاية webhook
GET	/v1/webhooks/:id	الحصول على تفاصيل webhook
PUT	/v1/webhooks/:id	تحديث نقطة نهاية webhook
DELETE	/v1/webhooks/:id	حذف نقطة نهاية webhook

رموز الأخطاء الشائعة

حالة HTTP	رمز الخطأ	الوصف	الحل
400	invalid_request	جسم طلب مشوّه أو حقول مطلوبة مفقودة	تحقق من بنية جسم الطلب مقابل مخطط نقطة النهاية.
401	unauthorized	مفتاح API مفقود أو غير صالح	تحقق من أن ترويسة Authorization تحتوي على Bearer token صالح.
403	forbidden	مفتاح API يفتقر إلى الصلاحية المطلوبة لنقطة النهاية هذه	حدّث صلاحيات المفتاح في لوحة معلومات المطورين أو استخدم مفتاحاً مختلفاً.
404	not_found	المورد المطلوب غير موجود	تأكد من صحة معرّف المورد وأنه ينتمي إلى مؤسستك.
409	conflict	تعارض في حالة المورد (مثل إرسال حملة تم إرسالها بالفعل)	تحقق من الحالة الحالية للمورد قبل محاولة العملية.
422	validation_error	فشل التحقق من جسم الطلب؛ راجع مصفوفة details	أصلح الحقول المذكورة في مصفوفة details وأعد المحاولة.
429	rate_limited	تم تجاوز حد المعدل	انتظر عدد الثواني المحدد في ترويسة Retry-After، ثم أعد المحاولة.
500	internal_error	خطأ في الخادم	أعد المحاولة باستخدام التراجع الأسي مع التشويش، حتى 3 إلى 5 محاولات.

الأخطاء الشائعة

الخطأ	التأثير	التوصية
استخدام مفاتيح API بدون صلاحيات كافية	تفشل الطلبات مع خطأ 403، مما يعطل تكاملك.	تحقق من الصلاحيات المطلوبة في توثيق نقطة النهاية قبل إنشاء المفتاح.
تجاهل ترقيم الصفحات بالمؤشر	يتم إرجاع الصفحة الأولى فقط من النتائج، مما يؤدي إلى بيانات غير مكتملة.	قم دائماً بترقيم الصفحات حتى يكون cursor بقيمة null.
عدم التحقق من أجسام الطلبات قبل الإرسال	رحلات ذهاب وإياب غير ضرورية بسبب أخطاء 422.	تحقق من الحمولات من جانب العميل باستخدام المخططات من توثيق API.
ترميز إصدار API بشكل ثابت	يجعل ترقية الإصدارات صعبة وعرضة للأخطاء.	خزّن إصدار API في متغير تهيئة بحيث تتطلب الترقيات تغيير التهيئة فقط.
عدم تنفيذ منطق إعادة المحاولة لأخطاء 500	تسبب الأعطال المؤقتة فقدان بيانات دائم أو عمليات فائتة.	نفّذ التراجع الأسي مع التشويش، مع إعادة المحاولة 3 إلى 5 مرات لاستجابات مستوى 500.

تلميح

استخدم ميزة "جرّب الآن" التفاعلية في توثيق مرجع API لاختبار نقاط النهاية مباشرة من متصفحك باستخدام مفتاح API الخاص ببيئة الاختبار. هذه هي أسرع طريقة لفهم أشكال الطلبات والاستجابات قبل كتابة كود التكامل.

• الصفحة الرئيسية لمرجع API
• تفاصيل نقطة النهاية
• جرّب الآن
• ترقيم الصفحات
• رموز الأخطاء
• API الحملات
• API جهات الاتصال
• API الرسائل
• API المحادثات
• API القوالب
• API Webhooks