موارد المطورين

ما هو

BotBat هي منصة قائمة على مبدأ API أولاً، مما يعني أن كل ميزة متاحة في لوحة التحكم يمكن الوصول إليها أيضاً من خلال REST API شاملة. سواء كنت تبني تكاملات مخصصة، أو تقوم بأتمتة سير عمل الحملات، أو تزامن بيانات جهات الاتصال مع أدوات الطرف الثالث، فإن قسم موارد المطورين يعمل كمركز موحد لإدارة جميع التكاملات. من هنا يمكنك إنشاء وتدوير مفاتيح API، وفحص حدود معدل الطلبات، وتهيئة webhooks، وتنزيل حزم SDK، والتبديل بين بيئة الاختبار وبيئة الإنتاج.

تتبع المنصة معايير RESTful في جميع أنحائها، مع أجسام طلبات واستجابات بصيغة JSON، ومصادقة Bearer token، وترقيم صفحات قائم على المؤشر، ورموز أخطاء موحدة. كل مفتاح API تنشئه يكون مقيداً بصلاحيات محددة، مما يضمن أن كل تكامل لديه حق الوصول فقط إلى الموارد التي يحتاجها فعلاً. يدعم هذا التصميم كلاً من التكاملات البسيطة ذات الغرض الواحد (مثل تغذية تحليلات للقراءة فقط) والبنى المعقدة متعددة الأنظمة حيث تتفاعل عدة خدمات مع BotBat في وقت واحد.

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

متى تستخدمه

السيناريو	الوصف
بناء تكامل مخصص	اربط BotBat بنظام إدارة علاقات العملاء (CRM) أو نظام تخطيط موارد المؤسسة (ERP) أو منصة التجارة الإلكترونية أو أدواتك الداخلية باستخدام REST API لإدارة جهات الاتصال وإرسال الرسائل وتفعيل الحملات برمجياً.
إنشاء وإدارة مفاتيح API	أنشئ مفاتيح API بصلاحيات محددة (مثل القراءة فقط للتحليلات، والكتابة للرسائل) بحيث يمتلك كل تكامل الحد الأدنى من الصلاحيات التي يحتاجها.
إعداد سير عمل مدفوع بالأحداث	هيئ webhooks لتلقي إشعارات فورية عند حدوث أحداث في BotBat (تسليم رسالة، إنشاء جهة اتصال، اكتمال حملة) وتفعيل إجراءات لاحقة.
الاختبار قبل الإطلاق	استخدم بيئة الاختبار التجريبية للتحقق من صحة استدعاءات API وتسليم webhooks وتدفقات الرسائل دون التأثير على جهات الاتصال الحقيقية أو استهلاك رصيد الرسائل.
مراقبة استخدام API وحدود المعدل	تحقق من استهلاك API مقابل حدود المعدل لكل مفتاح ولكل مؤسسة لضمان بقاء تكاملاتك ضمن الحدود وتجنب انقطاع الخدمة.
تدوير بيانات الاعتماد	قم بتدوير مفاتيح API بشكل دوري أو إلغاء المفاتيح المخترقة فوراً. تدعم لوحة المعلومات إنشاء مفتاح بديل قبل إلغاء المفتاح القديم لتدوير دون توقف.

الخطوات

1. فتح موارد المطورين

انتقل إلى المطور في الشريط الجانبي الرئيسي. تعرض لوحة المعلومات ملخصاً لمفاتيح API النشطة ونقاط نهاية webhook المُهيأة ومخطط استخدام يوضح حجم استدعاءات API الأخيرة.

2. إنشاء مفتاح API

انقر على إنشاء مفتاح API. في نموذج الإنشاء، أدخل اسماً وصفياً للمفتاح (مثل "تكامل CRM" أو "لوحة التحليلات")، ثم حدد الصلاحيات التي يجب أن يمتلكها المفتاح. تشمل الصلاحيات المتاحة contacts:read وcontacts:write وmessages:send وcampaigns:read وcampaigns:write وwebhooks:manage وغيرها. تتوافق كل صلاحية مع مجموعة محددة من نقاط نهاية API. انقر على إنشاء لتوليد المفتاح.

بمجرد إنشائه، يتم عرض قيمة المفتاح مرة واحدة فقط. انسخه فوراً وخزّنه في مكان آمن مثل مدير الأسرار أو خزنة مشفرة. لا يمكن استرجاع المفتاح بعد إغلاق مربع الحوار.

3. مراجعة حدود المعدل

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

الخطة	الطلبات في الثانية (لكل مفتاح)	الطلبات في الدقيقة (لكل مؤسسة)
المبتدئة	5	300
الاحترافية	20	1,200
المؤسسات	50	5,000

عند تجاوز حد المعدل، تُرجع API الاستجابة HTTP 429 مع ترويسة Retry-After تشير إلى عدد الثواني التي يجب الانتظار قبل إعادة المحاولة.

4. إعداد webhook

انتقل إلى قسم Webhooks وانقر على إضافة نقطة نهاية. أدخل عنوان HTTPS لخادمك، وحدد أنواع الأحداث التي تريد تلقيها (مثل message.delivered وcontact.created وcampaign.completed)، ثم احفظ. ينشئ BotBat مفتاح توقيع يستخدمه خادمك للتحقق من صحة الحمولات الواردة. للاطلاع على التفاصيل الكاملة حول تهيئة webhook، راجع توثيق Webhooks.

5. استكشاف توثيق API

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

6. تنزيل حزمة SDK

في قسم حزم SDK، قم بتنزيل مكتبات العملاء بلغة البرمجة المفضلة لديك. تغلف كل حزمة SDK واجهة REST API بأساليب مألوفة للغة، وتتولى المصادقة، وتنفذ إعادة المحاولة التلقائية، وتتضمن تعريفات TypeScript/الأنواع حيثما ينطبق ذلك.

اللغة	مدير الحزم	أمر التثبيت
JavaScript / Node.js	npm	npm install @botbat/sdk
Python	pip	pip install botbat
PHP	Composer	composer require botbat/sdk
Java	Maven	أضف تبعية com.botbat:sdk

7. تفعيل بيئة الاختبار التجريبية

بدّل إلى وضع بيئة الاختبار في لوحة معلومات المطورين. في وضع الاختبار، تُنفذ استدعاءات API مقابل بيانات اختبار معزولة، ويتم محاكاة الرسائل (لا تُسلّم فعلياً إلى مستلمين حقيقيين)، وتُنشأ أحداث webhook بحمولات اختبارية. يتيح لك ذلك تطوير واختبار تكاملك بالكامل من البداية إلى النهاية دون أي خطر على بيانات الإنتاج أو استهلاك رصيد الرسائل.

تتضمن بيئة الاختبار أيضاً محاكي الأحداث الذي يتيح لك تفعيل أحداث webhook محددة يدوياً عند الطلب. هذا مفيد بشكل خاص لاختبار الحالات الحدية مثل فشل تسليم الرسائل أو أحداث تجاوز حد المعدل أو سيناريوهات دمج جهات الاتصال التي يصعب إعادة إنتاجها بشكل طبيعي.

8. مراقبة استخدام API

تعرض لوحة الاستخدام حجم استدعاءات API عبر الزمن، مقسماً حسب نقطة النهاية والمفتاح. تبرز انتهاكات حدود المعدل وارتفاعات الأخطاء واتجاهات زمن الاستجابة. استخدم هذه البيانات لتحديد التكاملات التي قد تحتاج إلى تحسين، أو المفاتيح التي يجب إيقافها، أو مشكلات السعة التي تتطلب ترقية الخطة.

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

الخطأ	لماذا هو مهم	كيفية تجنبه
كشف مفاتيح API في الكود من جانب العميل	يمكن سرقة المفاتيح المضمنة في JavaScript الواجهة الأمامية أو تطبيقات الهاتف المحمول أو المستودعات العامة واستغلالها.	استخدم مفاتيح API فقط في الكود من جانب الخادم. خزّنها في متغيرات البيئة أو مدير الأسرار.
إنشاء مفتاح واحد بجميع الصلاحيات	المفتاح المخترق الذي يمتلك جميع الصلاحيات يمنح المهاجم تحكماً كاملاً في حساب BotBat الخاص بك.	اتبع مبدأ الحد الأدنى من الصلاحيات. أنشئ مفاتيح منفصلة لكل تكامل، كل منها بالصلاحيات التي يحتاجها فقط.
عدم التعامل مع استجابات تجاوز حد المعدل	تجاهل استجابات HTTP 429 يسبب فشل الطلبات ويمكن أن يؤدي إلى حظر مؤقت لعنوان IP.	نفّذ منطق التراجع التدريجي الذي يحترم ترويسة Retry-After في استجابات 429.
تخطي بيئة الاختبار	الاختبار مقابل بيئة الإنتاج يرسل رسائل حقيقية وينشئ جهات اتصال حقيقية ويستهلك رصيداً حقيقياً.	تحقق دائماً من صحة التكاملات في وضع الاختبار أولاً قبل التبديل إلى الإنتاج.
نسيان تدوير مفاتيح API	تراكم المخاطر على المفاتيح طويلة العمر بمرور الوقت، خاصة إذا غادر أعضاء الفريق الذين كان لديهم حق الوصول المؤسسة.	قم بتدوير المفاتيح كل 90 يوماً. استخدم سير عمل التدوير دون توقف: أنشئ المفتاح الجديد، حدّث تكاملك، ثم ألغِ المفتاح القديم.

تلميح

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

• لوحة معلومات المطوّرين
• قائمة مفاتيح API
• إنشاء مفتاح API
• نطاقات الصلاحيات
• حدود المعدل
• قائمة Webhooks
• حزم SDK
• تبديل بيئة الاختبار
• لوحة الاستخدام