الحسابات الفرعية
تمنح المنصة التي ترسل نيابةً عن عملائها حسابًا فرعيًا لكل عميل: مؤسسة Oblic مستقلة لها مرسلوها وقوالبها ورسائلها وتقاريرها. يعمل مفتاحك نيابةً عنها عند تحديدها. تتطلب إدارة الحسابات الفرعية مفتاحًا بدور Owner أو Admin يتضمن accounts:manage.
إنشاء حساب فرعي
- اسم
name- النوع
- string
- وصف
مطلوب: اسم العميل، بحد أقصى 511 حرفًا.
- اسم
externalId- النوع
- string
- وصف
مطلوب: معرّف العميل في نظامك، بحد أقصى 100 من أحرف ASCII والأرقام والرموز
_و.و:و-. تستخدمه لاحقًا لتحديد الحساب الفرعي.
- اسم
issueKey- النوع
- boolean
- وصف
هل يُصدر للحساب الفرعي مفتاح API خاص به؛ القيمة الافتراضية
true.
إنشاء حساب فرعي
curl -X POST https://api.oblic.app/external/v1/accounts \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "name": "Asha Textiles", "externalId": "tenant-4821" }'
الاستجابة
{
"status": "success",
"data": {
"id": "ORG000R7ZM4Q2VXH00",
"name": "Asha Textiles",
"externalId": "tenant-4821",
"active": true,
"createdAt": "2026-10-24T09:30:00Z",
"apiKey": "obl_live_…"
},
"errors": null
}
apiKeyيظهر في هذه الاستجابة فقط: احفظه حينها، أو أنشئ الحساب الفرعي مجددًا للحصول على مفتاح آخر. هو مفتاح بدور User وبنطاقات الأذونات الافتراضية القديمة، التي تستثنيevents:write: يتيح الإرسال والقراءة وإدارة الهويات وقوائم جهات الاتصال، لكنه لا يتيح المسارات التي تتطلب مفتاح Owner أو Admin.- إرسال
externalIdنفسه مجددًا يعيد الحساب الفرعي نفسه، ويعيد تفعيله إن كان معطّلًا، دون تغيير اسمه. يُصدر كل طلب مفتاحًا آخر ما لم تكنissueKeyبالقيمةfalse. تبقى المفاتيح السابقة صالحة، باستثناء ما أُلغي عند تعطيل الحساب. - لا يملك الحساب الفرعي حسابات فرعية أخرى: محاولة إنشاء واحد أثناء العمل نيابةً عن حساب فرعي تعيد
403 SUB_ACCOUNT_NOT_ALLOWED.
عرض الحسابات الفرعية
تظهر جميع الحسابات الفرعية، بما فيها المعطّلة التي تكون فيها active بالقيمة false، بترتيب إنشائها. لا تتضمن القائمة أي مفاتيح.
تعطيل حساب فرعي
يعطّل الحساب الفرعي باستخدام id الخاص به في Oblic، لا externalId الخاص بك، ويلغي جميع مفاتيحه فورًا. إنشاؤه مجددًا باستخدام externalId يعيد تفعيله. إذا لم يكن الحساب الفرعي تابعًا للمؤسسة، تُعاد 404 ACCOUNT_NOT_FOUND.
العمل نيابةً عن حساب فرعي
أرسل X-Oblic-On-Behalf-Of بقيمة externalId للحساب الفرعي، فيُنفّذ الطلب باسمه كما لو استُخدم مفتاحه الخاص. يعمل مفتاحك الواحد لجميع العملاء، فلا تحتاج إلى الاحتفاظ بمفتاح لكل عميل.
الإرسال من حساب عميل
curl -X POST https://api.oblic.app/external/v1/messages/email \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'X-Oblic-On-Behalf-Of: tenant-4821' \
-H 'Content-Type: application/json' \
-d '{ "from": "hello@ashatextiles.example", "to": ["asha@example.org"], "subject": "Welcome", "html": "<p>Welcome!</p>" }'
- ما يخص الحساب الفرعي: يُرسل البريد من هوياته فقط؛ ورسائله وتقاريره وقوالبه وwebhooks تخصه، وكذلك قيم
Idempotency-Keyالخاصة به. - ما يخصك: تدفع محفظة مؤسستك تكاليف رسائله، وتسري قائمة عناوين IP المسموح بها لديك على الطلبات التي تنفّذها نيابةً عنه.
- يبقى دور مفتاحك نافذًا، لذا أدِر قوالب العميل أو webhooks أو رقم WhatsApp باستخدام مفتاحك بدور Owner أو Admin مع الترويسة.
- إذا لم يطابق
externalIdحسابًا فرعيًا نشطًا، تُعاد404 ACCOUNT_NOT_FOUND. - تُرسل أحداث webhook للحساب الفرعي إلى نقاطه النهائية إن وُجدت، وإلا فإلى نقاطك، مع
externalIdضمنaccountفي كل حدث. راجع Webhooks. - قوالب SMS التي يرسلها الحساب الفرعي هي القوالب التي تشاركها معه. راجع القوالب.