Developer API — Connection

احصل على رمز مميز

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

استخدم الرمز المميز

قم بتضمين الرمز المميز في كل طلب:

Authorization: Bearer <access_token>

POST/api/v1/auth/login

طلب

{
  "email": "admin@yourorg.com",
  "password": "••••••••"
}

الرد 200

{
  "access_token": "eyJhbG...",
  "refresh_token": "dGhpcw...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

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

بيئة	عنوان URL الأساسي
كلاود (الولايات المتحدة)	`https://beta.connection.app/api/v1`
في الموقع	`https://<your-server>/api/v1`

نوع المحتوى
تستخدم جميع نصوص الطلبات والاستجابات نوع البيانات application/json. أضف Content-Type: application/json إلى الطلبات التي تحتوي على نص.

حالة	معنى
200	نجاح
201	مخلوق
400	طلب غير صالح - معلمات غير صالحة
401	غير مصرح به - رمز مميز مفقود أو منتهي الصلاحية
403	ممنوع - تصاريح غير كافية
404	غير موجود
500	خطأ في الخادم الداخلي

استجابة خطأ

{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}

مصادقة واجهة برمجة التطبيقات

المستخدمون

الأجهزة

القنوات

تواصل

جسر الصوت

المحادثات

محتوى

المواقع

الإشعارات الفورية

تخزين

عمليات الإنتاج بالجملة

التاريخ والوقت

POST/api/v1/loginقم بمصادقة المستخدم واستلم رمز المصادقة

POST/api/v1/login-deviceالتحقق من صحة الجهاز باستخدام UUID وعنوان MAC

POST/api/v1/logoutإبطال صلاحية رمز الجلسة الحالي

GET/api/v1/users/userاسترجع ملف تعريف المستخدم المسجل دخوله حاليًا

POST/api/v1/users/userإنشاء حساب مستخدم جديد

PATCH/api/v1/users/user/{uuid}تحديث ملف تعريف المستخدم (مثلاً: صورة الملف الشخصي)

GET/api/v1/devices/deviceعرض جميع الأجهزة

GET/api/v1/devices/device/{uuid}احصل على معلومات مفصلة عن الجهاز بما في ذلك البرامج الثابتة والإعدادات

PUT/api/v1/devices/association/{uuid}تحديث الارتباط بين المستخدم والجهاز

DELETE/api/v1/devices/association/{uuid}إزالة ارتباط المستخدم بالجهاز والإعدادات المخزنة

GET/api/v1/devices/device/{device_uuid}/settingsعرض الإعدادات المخزنة للجهاز

POST/api/v1/devices/device/{device_uuid}/settingsحفظ الإعدادات الخاصة بالجهاز

GET/api/v1/devices/device/{device_uuid}/statusاحصل على حالة الجهاز (الاتصال، البطارية، المستشعرات، حالة الصوت)

POST/api/v1/devices/device/{device_uuid}/statusانشر حالة الجهاز من الجهاز

GET/api/v1/devices/device/{device_uuid}/contextعرض قيم السياق المخزنة للجهاز

POST/api/v1/devices/device/{device_uuid}/ingest-contextاستلام بيانات نظام تحديد المواقع العالمي (GPS) وشبكة الواي فاي من الجهاز

GET/api/v1/devices/firmwareقائمة بإصدارات البرامج الثابتة المتوافقة مع إصدار معين من الأجهزة/البرامج

GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchجلب صورة البرامج الثابتة على أجزاء

GET/api/v1/devices/languageقائمة لغات وأصوات الأجهزة المدعومة

GET/api/v1/devices/storage_imageقم بتنزيل صورة تخزين الجهاز المخصصة للغة

POST/api/v1/devices/logاستلام ملف سجل من جهاز

POST/api/v1/devices/crashاستلام ملف تفريغ الذاكرة الأساسية من جهاز

PATCH/api/v1/devices/crash/{uuid}تحديث سجل الأعطال

POST/api/v1/devices/device/{device_uuid}/cbbpإرسال أمر CBBP إلى جهاز عبر الخادم

GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}استرجع حالة واستجابة أمر CBBP المرسل مسبقًا

نص الطلب عبارة عن مغلف أوامر CBBP. يتتبع كائن CBBPCommand المخزن حالة التسليم: غير مُحدد ← مُرسل ← مُستلم أو انتهت المهلة.

قم بإجراء استطلاع GET /cbbp/ للتحقق مما إذا كان الجهاز قد استقبل الأمر واستجاب له.

طلب — رسالة صادرة

{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}

الاستجابة - حالة قيادة CBBP

{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

GET/api/v1/channels/channelقائمة القنوات، مع إمكانية تصفيتها حسب نوع الكائن

POST/api/v1/channels/channelإنشاء قناة (ChannelGroup أو ChannelContact أو ChannelExternalNumber)

PATCH/api/v1/channels/channel/{uuid}تحديث مجموعة قنوات أو جهة اتصال قناة

DELETE/api/v1/channels/channel/{uuid}حذف قناة

DELETE/api/v1/channels/{uuid}حذف مجموعة قنوات

DELETE/api/v1/channels/by-type/{channelType}حذف جميع القنوات من نوع معين (حالياً قناة الاتصال)

GET/api/v1/channels/associationعرض روابط القنوات للمستخدم الحالي

POST/api/v1/channels/associationطلب الارتباط بقناة

PATCH/api/v1/channels/association/{uuid}قبول أو رفض أو تحديث إعدادات الارتباط

DELETE/api/v1/channels/association/{uuid}إزالة الارتباط بقناة

GET/api/v1/channels/historyاحصل على سجل الوصول إلى القناة مع ترقيم الصفحات للمستخدم الحالي

POST/api/v1/channels/historyإنشاء سجل تاريخ القناة

GET/api/v1/channels/searchابحث عن القنوات باستخدام سلسلة الاستعلام وفلتر النوع الاختياري

POST/api/v1/communicate/outgoing-makeابدأ قناة صادرة إلى ChannelPeople أو ChannelGroup أو ChannelContact أو ChannelContactNumber

POST/api/v1/communicate/incoming-acceptanceقبول أو رفض طلب الانضمام إلى قناة واردة

POST/api/v1/communicate/closeأغلق قناة الاتصال النشطة الحالية على الجهاز

POST/api/v1/communicate/vcp-activateقم بتشغيل بروتوكول الاتصال الصوتي (VCP) على الخادم والجهاز

POST/api/v1/communicate/vcp-deactivateقم بإلغاء تنشيط VCP، والعودة إلى أي قناة سابقة

POST/api/v1/communicate/recording-activateقم بتفعيل وضع التسجيل على الخادم والجهاز

POST/api/v1/communicate/content-startافتح قناة بث للمحتوى الصوتي

POST/api/v1/communicate/request-vocalizationقم بإنشاء صوت تحويل النص إلى كلام للنص المحدد، مع إمكانية ترجمته اختيارياً.

جسر الصوت

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

GET/api/v1/bridge/conversationsأدرج جميع محادثات الجسر

GET/api/v1/bridge/conversations/{uuid}احصل على محادثة مفصلة تتضمن نص المحادثة، والمشاركين، والملخص.

POST/api/v1/bridge/conversations/{conversation_uuid}/summaryإنشاء ملخص ذكاء اصطناعي للمحادثة

POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioقم بإنشاء ملف صوتي لملخص المحادثة

GET/api/v1/conversations/conversationقائمة بجلسات مولد الذكاء الاصطناعي، قابلة للتصفية حسب الشخصية والأداة

POST/api/v1/conversations/conversationإنشاء جلسة محادثة جديدة للذكاء الاصطناعي

GET/api/v1/conversations/conversation/{uuid}استرجع جلسة محادثة مع ملخص/تحديث اختياري عن حالة الغياب

DELETE/api/v1/conversations/conversation/{uuid}حذف جلسة محادثة

GET/api/v1/conversations/conversation/{uuid}/messagesقائمة الرسائل في المحادثة

POST/api/v1/conversations/conversation/{uuid}/messagesأضف رسالة مستخدم واحصل على رد من الذكاء الاصطناعي

GET/api/v1/content/categoriesاحصل على شجرة فئات المحتوى

GET/api/v1/content/contentعرض المحتوى المتاح ضمن فئة

GET/api/v1/content/popularاستعرض المحتوى الشائع لمدينة أو منطقة أو دولة معينة

POST/api/v1/location/determineتحديد خطوط الطول والعرض لتحديد المدينة والمنطقة والبلد

POST/api/v1/push-notifications/pushقم بتسجيل تطبيق جوال لتلقي إشعارات FCM الفورية (iOS، Android، الويب)

GET/api/v1/storage/retrieve/{path}تنزيل ملف مخزن عن طريق المسار

POST/api/v1/storage/remove-backgroundإزالة الخلفية من الصورة (إرجاع base64)

POST/api/v1/bulkتنفيذ عمليات متعددة لواجهة برمجة التطبيقات في طلب واحد، ويمكن اختيارياً كمعاملة ذرية واحدة.

GET/api/v1/current-datetimeأعد التاريخ والوقت الحاليين بتوقيت غرينتش +0

تنسيق الرسالة

يتكون كل تفاعل CBBP من رسالة أمر يتم إرسالها إلى الجهاز ورسالة نتيجة يتم إرجاعها من قبل الجهاز.

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

تتوفر وثائق البروتوكول الكاملة للشركاء المسجلين. اتصل بممثل شركة كونكشن أو تواصل مع developer@connectionbadge.com لطلب الوصول إلى مرجع أوامر CBBP الكامل، بما في ذلك مخططات الطلب/الاستجابة الكاملة، ورموز الخطأ، وأدلة التكامل.

رسالة الأمر

{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}

رسالة النتيجة

{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

بلوتوث (تطبيق)

إرسال أوامر CBBP مباشرة من تطبيق جوال عبر تقنية BLE. يتطلب ذلك أن يكون الجهاز مقترنًا وفي نطاق التغطية.

حزمة تطوير البرامج للأجهزة المحمولة

واي فاي أو بلوتوث عبر الخادم

يتم توجيه طلب POST إلى /devices//cbbp عبر واجهة برمجة تطبيقات REST. يقوم الخادم تلقائيًا بتوجيه الطلب إلى الجهاز عبر شبكة Wi-Fi أو Bluetooth حسب طريقة اتصال الشارة. هذا الإجراء شائع جدًا في عمليات التكامل مع الأنظمة الخلفية.

واجهة برمجة تطبيقات REST

قسم الإرسال الداخلي

إرسال CBBP على الجهاز أو بين العمليات. يستخدمه برنامج تشغيل الشارة لتوجيه الأوامر بين الأنظمة الفرعية الداخلية.

البرامج الثابتة فقط

البناء علىمنصة الاتصالات

واجهة برمجة تطبيقات REST

بروتوكول CBBP

روابط الويب

المصادقة

احصل على رمز مميز

استخدم الرمز المميز

عنوان URL الأساسي ونظام الإصدارات

الأخطاء ورموز الحالة

نظرة عامة على واجهة برمجة تطبيقات REST

المصادقة

المستخدمون

الأجهزة

وكيل CBBP

القنوات

تواصل

جسر الصوت

المحادثات

محتوى

المواقع

الإشعارات الفورية

تخزين

عمليات الإنتاج بالجملة

التاريخ والوقت

بروتوكول Combad الأساسي

تنسيق الرسالة

ينقل

بلوتوث (تطبيق)

واي فاي أو بلوتوث عبر الخادم

قسم الإرسال الداخلي

أوامر الطاقة

أوامر الواي فاي

أوامر البلوتوث

أوامر الإعدادات

أوامر البرامج الثابتة

أوامر الجهاز

أوامر الاتصال

الأوامر الصوتية

أوامر LED

الأوامر الداخلية

أوامر الهاتف المحمول

هل أنت مستعد للبناء؟

البناء على
منصة الاتصالات