واجهة API v2 مع OAuth

يتعامل الإصدار الجديد من واجهة Oblic مع الرحلات والشرائح والرسائل التي تراها في Oblic، ضمن مساحة العمل التي يربطها المستخدم. يعتمد رموز وصول OAuth 2.1 بدلاً من مفاتيح API ويعمل بصلاحيات دور المستخدم. تواصل /external/v1 العمل بمفاتيح API.


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

لا تقبل API v2 مفتاح API مطلقاً؛ إرساله يعيد 401 API_KEY_NOT_ACCEPTED. بدلاً من ذلك يربط المستخدم تطبيقك بإحدى مساحات عمله، ويعمل التطبيق نيابة عنه فيها.

يلزم نشر Oblic مع خادم تفويض OAuth مفعّل، وإدراج API v2 مورداً مسموحاً، وتهيئة مفاتيح التوقيع وصفحة الموافقة، وتسجيل عميلك. أكد التوفر مع دعم Oblic قبل التكامل؛ عناوين URL التوضيحية لا تثبت أن النشر مهيأ.

  1. سجّل تطبيقك. أرسل إلى دعم Oblic اسمه وعناوين URI لإعادة التوجيه ونطاقات الصلاحيات المطلوبة للحصول على معرّف عميل. العملاء عامّون: لا يوجد سر للعميل، وكل تفويض يستخدم PKCE. لا تستخدم الواجهة إلا خوادم أو تطبيقات أصلية؛ لا يُسمح بأي أصل متصفح عند نقطة الرموز أو الواجهة.
  2. وجّه المستخدم لتسجيل الدخول. افتح نقطة التفويض مع resource الذي يحدد API v2، وscope=read send لإرسال الرسائل، أو scope=read للقراءة فقط. يسجّل المستخدم دخوله إلى Oblic ويختار مساحة العمل ويوافق على النطاقات.
  3. استبدل رمز التفويض عند نقطة الرموز باستخدام resource نفسه.
  4. استدع الواجهة باستخدام Authorization: Bearer <access token>.
خادم التفويضhttps://api.oblic.app (البيانات الوصفية عند /.well-known/oauth-authorization-server)
نقطة التفويضhttps://api.oblic.app/oauth2/authorize
نقطة الرموزhttps://api.oblic.app/oauth2/token
الموردhttps://api.oblic.app/external/v2
PKCES256 فقط
رمز الوصولصالح لمدة ساعة افتراضياً
رمز التجديديُستبدل عند كل استخدام؛ وينتهي افتراضياً بعد 30 يوماً دون استخدام و90 يوماً بعد الاتصال الأول

استبدال رمز التفويض

curl -X POST https://api.oblic.app/oauth2/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d code=THE_CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d resource=https://api.oblic.app/external/v2

لا يعمل هنا رمز صادر لمورد آخر مثل خادم MCP الخاص بـ Oblic. يعيد الطلب دون رمز صالح 401 مع ترويسة WWW-Authenticate التي تشير إلى البيانات الوصفية للمورد: https://api.oblic.app/.well-known/oauth-protected-resource/external/v2.

نطاقات الصلاحيات والأدوار

  • اسم
    read
    النوع
    scope
    وصف

    اطلب هذا النطاق دائماً؛ يُرفض الرمز الذي لا يتضمنه. يسمح بقراءة رحلات مساحة العمل وشرائحها والرسائل المرسلة عبر الواجهة.

  • اسم
    send
    النوع
    scope
    وصف

    يسمح بوضع إرسال البريد وSMS وWhatsApp في قائمة الانتظار باسم المؤسسة؛ ولا يعني أن المزوّد قد سلّمها. يرى المستخدم هذا النطاق في سطر مستقل قبل الموافقة عليه.

لا يتجاوز نطاق الصلاحيات دور المستخدم الذي يفحصه Oblic في كل طلب. سحب الدور أو إزالة المستخدم من المؤسسة يوقف وصول الرمز فوراً.

  • الرحلات والشرائح تخص مساحة العمل التي اختارها المستخدم؛ يمكن لأي دور فيها قراءتها.
  • الرسائل المرسلة عبر الواجهة تخص مساحة العمل الافتراضية للمؤسسة، كما مع مفتاح API. يتطلب الإرسال نطاق send ودور Owner أو Admin أو Editor في المساحة الافتراضية؛ وتكفي أي عضوية دور فيها للقراءة.

لا يخضع الرمز لقائمة عناوين IP المسموح بها لمفاتيح API في المؤسسة؛ يُستخدم من خوادم تطبيقك وتحده أدوار المستخدم ونطاقاته المعتمدة.


نقاط الواجهة

تتضمن كل استجابة {"status": "success", "data": …, "errors": null}، أو "status": "error" مع الأخطاء.

الطريقةالمسارالوظيفة
GET/external/v2/journeysحملات مساحة العمل وأتمتاتها وروبوتات WhatsApp والرحلات المنشأة في Journeys، بالأحدث تعديلاً أولاً
GET/external/v2/journeys/{id}رحلة واحدة
GET/external/v2/segmentsقوائم مساحة العمل ثم شرائحها الديناميكية
GET/external/v2/segments/{id}شريحة واحدة
POST/external/v2/messages/emailيرسل بريداً من مرسل موثّق
POST/external/v2/messages/smsيرسل SMS مطابقاً لأحد قوالب DLT الخاصة بك
POST/external/v2/messages/whatsappيرسل قالب WhatsApp معتمداً أو رداً خلال 24 ساعة
GET/external/v2/messagesالرسائل المرسلة عبر الواجهة، بالأحدث أولاً، بمعلمات قائمة v1
GET/external/v2/messages/{messageId}رسالة مرسلة عبر الواجهة ونتيجتها

عرض الرحلات

  • اسم
    offset
    النوع
    integer
    وصف

    موضع بداية الصفحة؛ 0 افتراضياً.

  • اسم
    limit
    النوع
    integer
    وصف

    عدد الرحلات من 1 إلى 100؛ 50 افتراضياً.

  • اسم
    mode
    النوع
    string
    وصف

    campaign أو automation أو bot أو journey لرحلة منشأة في Journeys نفسه.

  • اسم
    status
    النوع
    string
    وصف

    الحالات المسموحة: draft أو scheduled أو live أو paused أو done.

  • اسم
    search
    النوع
    string
    وصف

    جزء من اسم رحلة.

يحدد nextOffset بداية الصفحة التالية، ويكون null في الصفحة الأخيرة.

عرض الرحلات

curl 'https://api.oblic.app/external/v2/journeys?status=live&limit=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

الاستجابة

{
  "status": "success",
  "data": {
    "journeys": [
      {
        "id": "CMP000R7ZM4Q2VXH00",
        "mode": "campaign",
        "name": "Weekly offer",
        "status": "live",
        "createdAt": "2026-10-01T09:30:00Z",
        "updatedAt": "2026-10-12T14:05:00Z"
      }
    ],
    "nextOffset": null
  },
  "errors": null
}

إرسال رسالة

الأجسام هي أجسام /external/v1/messages. يوضع الإرسال في قائمة الانتظار ويُجاب بـ 202 ومعرّف الرسالة. أعد استخدام ترويسة Idempotency-Key نفسها بطول 1 إلى 255 حرفاً، كما في إرسال v1: يعيد الطلب نفسه المعرّف الأول دون إرسال جديد، أما المفتاح نفسه مع رسالة مختلفة فيُرفض بـ 409 IDEMPOTENCY_CONFLICT. المفتاح يخص تطبيقك؛ استخدام القيمة نفسها من تطبيق آخر أو مفتاح API ينتج رسالته المستقلة.

إرسال بريد إلكتروني

curl -X POST https://api.oblic.app/external/v2/messages/email \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-4471-shipped' \
  -d '{
    "to": ["customer@example.com"],
    "subject": "Your order has shipped",
    "html": "<p>Your order 4471 is on its way.</p>"
  }'

الاستجابة

{
  "status": "success",
  "data": { "id": "msg_4f9c2a7e1b8d4e0f9a6c3b2d1e0f9a8b", "status": "queued" },
  "errors": null
}

اقرأ النتيجة عبر GET /external/v2/messages/{messageId}.


أخطاء الواجهة

حالة HTTPرمز الخطأالمعنى
401MISSING_ACCESS_TOKENلم يُرسل رمز وصول
401INVALID_ACCESS_TOKENانتهى الرمز أو صدر لمورد آخر أو يفتقر إلى read أو غادر صاحبه المؤسسة؛ جدّده أو أعد الاتصال
401API_KEY_NOT_ACCEPTEDأُرسل مفتاح API؛ استخدمه مع /external/v1
403INSUFFICIENT_SCOPEيفتقر الرمز للنطاق المطلوب المبيّن في WWW-Authenticate؛ أعد الاتصال ووافق عليه
403FORBIDDENدور المستخدم لا يسمح بالعملية
403EMAIL_SUSPENDEDبريد الحساب معلّق بسبب الارتدادات أو شكاوى الرسائل المزعجة، كما في /external/v1
400BAD_REQUEST, INVALID_IDEMPOTENCY_KEYمعلمة أو ترويسة أو جسم مفقود أو غير قابل للقراءة
400اسم الحقل مثل TOأحد حقول الجسم غير صالح
402INSUFFICIENT_BALANCEيتطلب إرسال SMS أو WhatsApp تسويقي رصيداً في المحفظة الدافعة؛ لا تُرفض رموز الدخول أو الرسائل المعاملاتية أو الردود بسبب محفظة فارغة
404JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUNDليس ضمن مساحة العمل أو لم يُرسل عبر الواجهة
404NOT_FOUNDهذا المسار غير موجود
405METHOD_NOT_ALLOWEDالمسار لا يقبل طريقة الطلب؛ تسرد Allow الطرق المقبولة
415UNSUPPORTED_MEDIA_TYPEلم يُرسل الجسم بصيغة application/json
422UNVERIFIED_SENDERمرسل البريد غير موثّق
429RATE_LIMITED, QUOTA_EXCEEDEDتجاوز البريد الحدود الساعية أو الحصة الشهرية، كما في /external/v1؛ تحدد Retry-After موعد المحاولة

قد تُرفض SMS أو WhatsApp لسبب محدد أيضاً، كما في /external/v1: قالب غير معتمد أو رقم ألغى التسويق أو غير متصل أو حد تم بلوغه؛ وتُرفق Retry-After عندما تفيد المحاولة لاحقاً.

هل كانت هذه الصفحة مفيدة؟