واجهة API
تتيح واجهة Oblic API لخوادمك إرسال البريد الإلكتروني وSMS وWhatsApp باسم مؤسستك ومراجعة النتائج، وتسجيل أنشطة جهات الاتصال في أنظمتك، وإدارة القوالب وهويات المرسل وقوائم جهات الاتصال والويب هوك والحسابات الفرعية المستخدمة. تستدعيها خوادمك بمفتاح API.
مستند OpenAPI لهذا الإصدار هو external-v1.json: يصف جميع المسارات والنطاقات المطلوبة وأجسام الطلبات المقبولة، كما يعرضها مرجع OpenAPI. تستخدم API v2 رموز وصول OAuth بدلاً من مفاتيح API.
عنوان URL الأساسي
تبدأ جميع المسارات بـ https://api.oblic.app/external/v1، باستثناء المسارات القديمة لقوائم جهات الاتصال التي تبدأ بـ https://api.oblic.app/external/contact-list/v1.
استدعاء الواجهة
المفتاح المستخدم في الاستدعاء
curl https://api.oblic.app/external/v1/key \
-H 'Authorization: Bearer YOUR_API_KEY'
- أرسل مفتاح API بصيغة
Authorization: Bearer <key>. تُنشأ المفاتيح في الإعدادات → تكامل API، ولكل مفتاح نطاقاته اللازمة. احتفظ بها على خوادمك: يستطيع أي شخص قراءة المفتاح الموجود في متصفح أو تطبيق جوال. راجع المصادقة. - تستخدم الاستجابة ذات الجسم غلاف JSON واحداً:
{"status": "success", "data": …, "errors": null}، أو"status": "error"مع الأخطاء، ولكل خطأ رمز (cd) ورسالة. راجع الأخطاء. - تتصرف المنصة نيابة عن عملائها عبر الحسابات الفرعية: مفتاح واحد والعميل المحدد في
X-Oblic-On-Behalf-Ofفي كل طلب. - أعد المحاولة ما دامت حالة المفتاح محفوظة، باستخدام
Idempotency-Keyنفسه وجسم الطلب نفسه. تُحفظ مفاتيح البريد وWhatsApp في Redis لمدة 24 ساعة؛ وقد يتيح فقدان التخزين المؤقت أو انتهاء المدة إرسالاً آخر. يبقى مفتاح SMS في صف الرسالة المخزن دون انتهاء زمني. هذا ليس ضماناً دائماً للتنفيذ مرة واحدة بالضبط. راجع الرسائل.
نجاح طلب الإرسال يعني قبوله، وليس تسليمه بواسطة المزود. يتطلب التسليم تفعيل الإرسال الصادر وتشغيل المستهلكين وإعداد المزودين. قبول طلب في نشر معطل الإرسال الصادر لا يعني أن الرسالة ستُرسل. لا توجد مهلة تسليم مضمونة.
الطوابع الزمنية
تتضمن طوابع الاستجابة التي تحدد لحظة زمنية إزاحة ISO 8601. مثلاً، يحدد 2026-10-30T20:00:00Z و2026-10-31T01:30:00+05:30 اللحظة نفسها. حلّل الإزاحة قبل عرض الوقت في منطقة القارئ الزمنية. يقوم new Date(value) في JavaScript وOffsetDateTime.parse(value) في Java بذلك؛ أما إضافة Z إلى قيمة بلا إزاحة أو تحليل اللحظة باستخدام LocalDateTime فلا يفعل ذلك.
تبقى القيمة التي تتضمن تاريخاً فقط تاريخاً. وللجدولة المحلية الصريحة عقد مستقل: يُربط وقت الساعة بحقل منطقة زمنية ولا يُفسر بمفرده على أنه لحظة زمنية.
نقاط النهاية
يشير «المطلوب» إلى النطاق الذي يحتاجه المفتاح للمسار؛ يكفي أحدها عند وجود عدة نطاقات. تتطلب بعض المسارات أيضاً مفتاحاً بدور المالك أو المسؤول. يمنح النطاق والدور الإذن، لكن إعداد الخدمة وأهلية المورد قد يؤديان إلى رفض الطلب رغم ذلك.
رسائل الواجهة
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
GET | /external/v1/messages | الرسائل المرسلة عبر الواجهة، الأحدث أولاً | messages:read |
POST | /external/v1/messages/email | إرسال بريد من مرسل موثّق باستخدام HTML خاص أو قالب | email:send |
POST | /external/v1/messages/sms | إرسال SMS يطابق أحد قوالب DLT للحساب | sms:send |
POST | /external/v1/messages/whatsapp | إرسال قالب WhatsApp معتمد أو رد خلال 24 ساعة | whatsapp:send |
GET | /external/v1/messages/{messageId} | رسالة مرسلة عبر الواجهة ونتيجتها | messages:read |
التقارير
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
GET | /external/v1/reports/summary | نتائج الرسائل المرسلة خلال فترة، حسب القناة والحالة | messages:read |
قوالب البريد الإلكتروني
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
GET | /external/v1/templates | قوالب البريد للحساب، الأحدث أولاً | email:send أو templates:manage |
POST | /external/v1/templates | إنشاء قالب بريد من HTML | templates:manage، مفتاح المالك أو المسؤول |
GET | /external/v1/templates/{id} | قالب بريد مع HTML والمتغيرات التي يقبلها | email:send أو templates:manage |
PUT | /external/v1/templates/{id} | استبدال قالب بريد منشأ من HTML | templates:manage، مفتاح المالك أو المسؤول |
DELETE | /external/v1/templates/{id} | حذف قالب بريد | templates:manage، مفتاح المالك أو المسؤول |
رؤوس SMS وقوالبها
لا يمكن تعديل سجل SMS إلا بحسابات السجل المُعدّة، حتى مع النطاق والدور المطلوبين. تسجل هذه المسارات رؤوساً وقوالب مسجلة مسبقاً لدى DLT؛ ولا تسجلها لدى DLT. تشمل القوائم القوالب المعتمدة، بما فيها غير النشطة؛ ولأهلية الإرسال ضوابط إضافية.
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
GET | /external/v1/sms/account | حدود SMS للحساب وما أرسله هذا الشهر | sms:send أو templates:manage |
GET | /external/v1/sms/senders | رؤوس DLT للحساب | sms:send أو templates:manage |
GET | /external/v1/sms/templates | قوالب DLT للحساب | sms:send أو templates:manage |
POST | /external/v1/sms/templates | تسجيل قالب مسجل مسبقاً لدى DLT في Oblic | templates:manage، مفتاح المالك أو المسؤول |
PUT | /external/v1/sms/senders/{senderId} | تسجيل رأس DLT أو تغيير تعيينه كافتراضي | templates:manage، مفتاح المالك أو المسؤول |
DELETE | /external/v1/sms/senders/{senderId} | حذف رأس DLT | templates:manage، مفتاح المالك أو المسؤول |
PUT | /external/v1/sms/templates/{id} | تعديل قالب DLT | templates:manage، مفتاح المالك أو المسؤول |
DELETE | /external/v1/sms/templates/{id} | حذف قالب DLT | templates:manage، مفتاح المالك أو المسؤول |
PUT | /external/v1/sms/templates/{id}/sharing | السماح بإرسال قالب لجميع الحسابات الفرعية أو المحددة منها أو عدم السماح لأي منها | templates:manage، مفتاح المالك أو المسؤول |
رقم WhatsApp وقوالبه
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
GET | /external/v1/whatsapp/connection | رقم WhatsApp المتصل بالحساب | whatsapp:send أو templates:manage |
POST | /external/v1/whatsapp/connection | ربط رقم WhatsApp Business للحساب أو استبداله | templates:manage، مفتاح المالك أو المسؤول |
DELETE | /external/v1/whatsapp/connection | فصل رقم WhatsApp للحساب | templates:manage، مفتاح المالك أو المسؤول |
GET | /external/v1/whatsapp/templates | قوالب WhatsApp للحساب مع مراجعة Meta لكل منها | whatsapp:send أو templates:manage |
POST | /external/v1/whatsapp/templates | تقديم قالب WhatsApp إلى Meta للمراجعة | templates:manage، مفتاح المالك أو المسؤول |
GET | /external/v1/whatsapp/recipients/{number} | ما يستطيع الحساب إرساله إلى رقم الآن | whatsapp:send أو templates:manage |
هويات المرسل
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
GET | /external/v1/identities | نطاقات المرسل وعناوينه وحالة توثيق كل منها | email:send أو identities:manage |
POST | /external/v1/identities | إضافة نطاق مرسل أو عنوان لتوثيقه | identities:manage |
DELETE | /external/v1/identities/{identityId} | حذف هوية مرسل | identities:manage |
قوائم جهات الاتصال
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
POST | /external/contact-list/v1/add | إنشاء قائمة جهات اتصال | contacts:manage |
POST | /external/contact-list/v1/{contactListId}/add | إضافة جهات اتصال إلى قائمة | contacts:manage |
GET | /external/contact-list/v1/{nextIndex}/{limit} | قوائم جهات الاتصال للحساب، صفحة تلو الأخرى | contacts:manage |
الأحداث
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
POST | /external/v1/events | تسجيل ما يصل إلى 100 حدث لجهات الاتصال، كالطلبات وسلات التسوق المتروكة | events:write |
الويب هوك للواجهة
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
GET | /external/v1/webhooks | نقاط نهاية الويب هوك للمؤسسة | webhooks:manage، مفتاح المالك أو المسؤول |
POST | /external/v1/webhooks | تسجيل نقطة نهاية ويب هوك أو العثور على المسجلة لعنوان URL نفسه | webhooks:manage، مفتاح المالك أو المسؤول |
GET | /external/v1/webhooks/deliveries | عمليات التسليم الفاشلة، الأحدث فشلاً أولاً | webhooks:manage، مفتاح المالك أو المسؤول |
GET | /external/v1/webhooks/{webhookId} | نقطة نهاية ويب هوك | webhooks:manage، مفتاح المالك أو المسؤول |
PUT | /external/v1/webhooks/{webhookId} | تغيير عنوان URL لنقطة نهاية أو أنواع أحداثها | webhooks:manage، مفتاح المالك أو المسؤول |
DELETE | /external/v1/webhooks/{webhookId} | إيقاف عمليات التسليم إلى نقطة نهاية | webhooks:manage، مفتاح المالك أو المسؤول |
POST | /external/v1/webhooks/deliveries/{deliveryId}/replay | إعادة وضع عملية تسليم فاشلة في الطابور | webhooks:manage، مفتاح المالك أو المسؤول |
الحسابات الفرعية للواجهة
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
GET | /external/v1/accounts | الحسابات الفرعية للمؤسسة | accounts:manage، مفتاح المالك أو المسؤول |
POST | /external/v1/accounts | إنشاء حساب فرعي أو العثور عليه عبر externalId، بمفتاح API خاص به | accounts:manage، مفتاح المالك أو المسؤول |
DELETE | /external/v1/accounts/{accountId} | تعطيل حساب فرعي وإلغاء مفاتيحه | accounts:manage، مفتاح المالك أو المسؤول |
مفتاح الواجهة
| الطريقة | المسار | الوظيفة | المطلوب |
|---|---|---|---|
GET | /external/v1/health | التحقق من وصول المفتاح إلى الواجهة | أي مفتاح بدور المالك أو المسؤول |
GET | /external/v1/info | المؤسسة التي يتصرف المفتاح نيابة عنها | أي مفتاح |
GET | /external/v1/key | المفتاح المستدعي: اسمه ودوره ونطاقاته وقدراته الحالية | أي مفتاح |