نظرة عامة

تتيح Buluthat API دمج برامجكم الحالية (CRM وERP والتجارة الإلكترونية ومكتب الدعم) مع سنترالكم السحابي: النقر للاتصال، التحكم بالمكالمات، إدارة الطوابير، القائمة السوداء، الملفات الصوتية، حملات الاتصال الآلي، مهام المساعد الصوتي، ورمز التحقق الصوتي.

كل نقاط النهاية على HTTP عادي؛ والردود JSON. تُستخدم من أي لغة بعميل HTTP.

العنوان الأساسي: https://api.buluthat.com/api/

المصادقة

كل نقاط النهاية متشابهة مفتاح API الخاص بك يستخدم. المفتاح في اللوحة الحساب والدعم > مفاتيح API من الصفحة، ينشئه مفوّض الحساب؛ bt_ يبدأ بـ ولا يظهر إلا مرة واحدة لحظة إنشائه.

يُرسَل المفتاح في كل طلب ضمن الترويسة:

Authorization: Bearer bt_xxxxxxxx

Authorization إذا تعذّر ضبط الترويسة X-Api-Key: bt_xxxxxxxx تُقبل أيضًا. المفتاح في الرابط (?key=) الإرسال مغلق في المفاتيح الجديدة.

كل مفتاح مرتبط بحساب عميل واحد ولا يصل إلا إلى بيانات ذلك الحساب. في المفتاح النطاق معرَّف:

طلب خارج النطاق 403 scope_denied، وحدة مغلقة في حسابك 403 module_disabled يعود. للمفتاح قائمة IP المسموحة, تاريخ الانتهاء و توقيع الطلب HMAC الإلزامي يمكن تعريفها؛ كلها أمان API في الصفحة.

لا تستخدم مفتاحك في جانب المتصفح (JavaScript)؛ استدعِ دائمًا من خادمك. وإن ظننت أنه تسرّب فاختر من اللوحة "تجديد المفتاح > إغلاق القديم فورًا" ليصبح القديم غير صالح فورًا.

صيغة الطلب

• عمليات القراءة GET، العمليات التي تغيّر POST (في الملفات الصوتية PUT/DELETE).
• محتوى POST application/json أو application/x-www-form-urlencoded قد يكون.
• الإجراء في نقاط نهاية التكامل action يُختار بمعلمة (?action=create_campaign).
• الطوابع الزمنية بتوقيت تركيا (2026-09-18 10:12:03).
• أرقام الهواتف 05xxxxxxxxx, 5xxxxxxxxx أو 905xxxxxxxxx تُقبل بالصيغة؛ وتعود في الردود موحّدة.

صيغة الرد

تُرجع نقاط نهاية التكامل (autocall وvoicebot وvoice_otp) دائمًا غلافًا:

{ "ok": true, "data": { } }

{ "ok": false, "error": "Kampanya bulunamadı.", "code": "campaign_not_found" }

تتحدث نقاط نهاية السنترال (begin_call وqueues وblocked_numbers…) برمز حالة HTTP: عند النجاح 200 OK والنتيجة في المحتوى (مصفوفة JSON أو نص عادي)، وعند الخطأ 4xx ورسالة الخطأ بالتركية في المحتوى.

رموز الأخطاء

حدود المعدل

في الردود X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset تأتي الترويسات. عند التجاوز 429 Too Many Requests و Retry-After تعود الترويسة. وفي كل رد X-Request-Id شاركوا القيمة في طلبات الدعم.

بيئة الاختبار

لا توجد بيئة sandbox منفصلة؛ جرّبوا برقم داخلي للاختبار وحملة صغيرة في حسابكم. حملات الاتصال الآلي status: "draft" تنشئونه بـ و results/summary يمكنكم استدعاء نقاط النهاية دون وصول بيانات. وفي رمز التحقق الصوتي أرسلوا إلى رقمكم الخاص؛ ويجري الاحتساب وفق قواعد باقتكم.

الإصدارات والتغييرات

تبقى نقاط النهاية متوافقة مع الإصدارات السابقة؛ تُضاف حقول جديدة، ولا يتغير اسم الحقول الحالية ولا نوعها. وأي حقل سيُزال يُعلَن عنه في اللوحة وفي هذه الصفحة قبل 90 أيام على الأقل.

مساعدة

إن تعثرتم أثناء التكامل ففي مركز الدعم داخل اللوحة افتحوا سجلًا بموضوع "التكامل / API"؛ وأرفقوا مثال الطلب/الرد لننظر معًا.