الحسابات الفرعية

تمنح المنصة التي ترسل نيابةً عن عملائها حسابًا فرعيًا لكل عميل: مؤسسة Oblic مستقلة لها مرسلوها وقوالبها ورسائلها وتقاريرها. يعمل مفتاحك نيابةً عنها عند تحديدها. تتطلب إدارة الحسابات الفرعية مفتاحًا بدور Owner أو Admin يتضمن accounts:manage.


POST/external/v1/accounts

إنشاء حساب فرعي

  • اسم
    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.

GET/external/v1/accounts

عرض الحسابات الفرعية

تظهر جميع الحسابات الفرعية، بما فيها المعطّلة التي تكون فيها active بالقيمة false، بترتيب إنشائها. لا تتضمن القائمة أي مفاتيح.


DELETE/external/v1/accounts/{accountId}

تعطيل حساب فرعي

يعطّل الحساب الفرعي باستخدام 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 التي يرسلها الحساب الفرعي هي القوالب التي تشاركها معه. راجع القوالب.
هل كانت هذه الصفحة مفيدة؟