واجهة API v2 مع OAuth
يتعامل الإصدار الجديد من واجهة Oblic مع الرحلات والشرائح والرسائل التي تراها في Oblic، ضمن مساحة العمل التي يربطها المستخدم. يعتمد رموز وصول OAuth 2.1 بدلاً من مفاتيح API ويعمل بصلاحيات دور المستخدم. تواصل /external/v1 العمل بمفاتيح API.
مستند OpenAPI لهذا الإصدار هو external-v2.json، ويعرضه مرجع OpenAPI بوصفه الإصدار 2.
الحصول على رمز وصول
لا تقبل API v2 مفتاح API مطلقاً؛ إرساله يعيد 401 API_KEY_NOT_ACCEPTED. بدلاً من ذلك يربط المستخدم تطبيقك بإحدى مساحات عمله، ويعمل التطبيق نيابة عنه فيها.
يلزم نشر Oblic مع خادم تفويض OAuth مفعّل، وإدراج API v2 مورداً مسموحاً، وتهيئة مفاتيح التوقيع وصفحة الموافقة، وتسجيل عميلك. أكد التوفر مع دعم Oblic قبل التكامل؛ عناوين URL التوضيحية لا تثبت أن النشر مهيأ.
- سجّل تطبيقك. أرسل إلى دعم Oblic اسمه وعناوين URI لإعادة التوجيه ونطاقات الصلاحيات المطلوبة للحصول على معرّف عميل. العملاء عامّون: لا يوجد سر للعميل، وكل تفويض يستخدم PKCE. لا تستخدم الواجهة إلا خوادم أو تطبيقات أصلية؛ لا يُسمح بأي أصل متصفح عند نقطة الرموز أو الواجهة.
- وجّه المستخدم لتسجيل الدخول. افتح نقطة التفويض مع
resourceالذي يحدد API v2، وscope=read sendلإرسال الرسائل، أوscope=readللقراءة فقط. يسجّل المستخدم دخوله إلى Oblic ويختار مساحة العمل ويوافق على النطاقات. - استبدل رمز التفويض عند نقطة الرموز باستخدام
resourceنفسه. - استدع الواجهة باستخدام
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 |
| PKCE | S256 فقط |
| رمز الوصول | صالح لمدة ساعة افتراضياً |
| رمز التجديد | يُستبدل عند كل استخدام؛ وينتهي افتراضياً بعد 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 | رمز الخطأ | المعنى |
|---|---|---|
| 401 | MISSING_ACCESS_TOKEN | لم يُرسل رمز وصول |
| 401 | INVALID_ACCESS_TOKEN | انتهى الرمز أو صدر لمورد آخر أو يفتقر إلى read أو غادر صاحبه المؤسسة؛ جدّده أو أعد الاتصال |
| 401 | API_KEY_NOT_ACCEPTED | أُرسل مفتاح API؛ استخدمه مع /external/v1 |
| 403 | INSUFFICIENT_SCOPE | يفتقر الرمز للنطاق المطلوب المبيّن في WWW-Authenticate؛ أعد الاتصال ووافق عليه |
| 403 | FORBIDDEN | دور المستخدم لا يسمح بالعملية |
| 403 | EMAIL_SUSPENDED | بريد الحساب معلّق بسبب الارتدادات أو شكاوى الرسائل المزعجة، كما في /external/v1 |
| 400 | BAD_REQUEST, INVALID_IDEMPOTENCY_KEY | معلمة أو ترويسة أو جسم مفقود أو غير قابل للقراءة |
| 400 | اسم الحقل مثل TO | أحد حقول الجسم غير صالح |
| 402 | INSUFFICIENT_BALANCE | يتطلب إرسال SMS أو WhatsApp تسويقي رصيداً في المحفظة الدافعة؛ لا تُرفض رموز الدخول أو الرسائل المعاملاتية أو الردود بسبب محفظة فارغة |
| 404 | JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUND | ليس ضمن مساحة العمل أو لم يُرسل عبر الواجهة |
| 404 | NOT_FOUND | هذا المسار غير موجود |
| 405 | METHOD_NOT_ALLOWED | المسار لا يقبل طريقة الطلب؛ تسرد Allow الطرق المقبولة |
| 415 | UNSUPPORTED_MEDIA_TYPE | لم يُرسل الجسم بصيغة application/json |
| 422 | UNVERIFIED_SENDER | مرسل البريد غير موثّق |
| 429 | RATE_LIMITED, QUOTA_EXCEEDED | تجاوز البريد الحدود الساعية أو الحصة الشهرية، كما في /external/v1؛ تحدد Retry-After موعد المحاولة |
قد تُرفض SMS أو WhatsApp لسبب محدد أيضاً، كما في /external/v1: قالب غير معتمد أو رقم ألغى التسويق أو غير متصل أو حد تم بلوغه؛ وتُرفق Retry-After عندما تفيد المحاولة لاحقاً.