واجهة API

تتيح واجهة Oblic API لخوادمك إرسال البريد الإلكتروني وSMS وWhatsApp باسم مؤسستك ومراجعة النتائج، وتسجيل أنشطة جهات الاتصال في أنظمتك، وإدارة القوالب وهويات المرسل وقوائم جهات الاتصال والويب هوك والحسابات الفرعية المستخدمة. تستدعيها خوادمك بمفتاح 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إنشاء قالب بريد من HTMLtemplates:manage، مفتاح المالك أو المسؤول
GET/external/v1/templates/{id}قالب بريد مع HTML والمتغيرات التي يقبلهاemail:send أو templates:manage
PUT/external/v1/templates/{id}استبدال قالب بريد منشأ من HTMLtemplates: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 في Oblictemplates:manage، مفتاح المالك أو المسؤول
PUT/external/v1/sms/senders/{senderId}تسجيل رأس DLT أو تغيير تعيينه كافتراضيtemplates:manage، مفتاح المالك أو المسؤول
DELETE/external/v1/sms/senders/{senderId}حذف رأس DLTtemplates:manage، مفتاح المالك أو المسؤول
PUT/external/v1/sms/templates/{id}تعديل قالب DLTtemplates:manage، مفتاح المالك أو المسؤول
DELETE/external/v1/sms/templates/{id}حذف قالب DLTtemplates: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المفتاح المستدعي: اسمه ودوره ونطاقاته وقدراته الحاليةأي مفتاح
هل كانت هذه الصفحة مفيدة؟