مرجع API

تتألف Embed API من أربعة مسارات — إنشاء الندوات/سردها، والتسجيل في الندوات، والتسجيل في الدورات، وإنشاء رموز تضمين الدورات. وكلها ذات إصدار تحت /api/v1، مثل Send API، وتتشارك معها المصادقة بمفتاح bearer.

المصادقة

Authorization: Bearer mia_live_...

المفتاح المفقود أو غير الصالح يعيد 401 \{ "error": "Missing or invalid Authorization: Bearer <apiKey>" \} في كل مسار أدناه. وتُدار المفاتيح ضمن المطوّرون في لوحة التحكم — راجع البدء السريع.

POST /api/v1/webinars

ينشئ ندوة عبر الإنترنت. وتُفرض قيمة accessMode دائمًا على "registration" — فـ Embed API لا تتعامل إلا مع جلسات التسجيل العام، ولا تتعامل أبدًا مع جلسات البث المباشر المقصورة على المشتركين.

الحقل	النوع	مطلوب	ملاحظات
`title`	string	نعم	تُزال المسافات من طرفيه؛ وإن أصبح فارغًا بعد ذلك يُعاد `400`.
`scheduledAt`	number	لا	طابع زمني Unix بالمللي ثانية.
`courseId`	string	لا	يربط الندوة بدورة قائمة.
`capacity`	number	لا	يجب أن يكون `>= 0` إن وُجد. والتسجيلات التي تتجاوز السعة توضع في قائمة الانتظار، ولا تُرفض.

يعيد 201 \{ "webinar": LiveSession \}.

GET /api/v1/webinars

دون جسم. يعيد 200 \{ "webinars": LiveSession[] \} — كل جلسة في الحساب بقيمة accessMode: "registration"، مع استبعاد الجلسات المقصورة على المشتركين.

POST /api/v1/webinars/[id]/register

يسجّل مستخدمًا نهائيًا واحدًا في ندوة ويرسل رسالة التأكيد/قائمة الانتظار.

الحقل	النوع	مطلوب	ملاحظات
`email`	string	نعم	يجب أن يطابق نمط بريد إلكتروني أساسيًا، وإلا فـ `400 \{ "error": "A valid \`email` is required" }`.
`name`	string	نعم	تُزال المسافات من طرفيه، وحدّه الأقصى 200 حرف، وإلا فـ `400 \{ "error": "A \`name` is required" }`.

الأخطاء: 404 إن لم تكن الندوة موجودة أو لم تكن ملكك؛ و400 إن لم تكن قيمتها accessMode: "registration"؛ و409 إن كانت قد انتهت بالفعل.

الاستجابة:

{ "status": "confirmed", "joinUrl": "https://mailinapp.com/webinar/<id>/join?token=..." }

أو، بمجرد بلوغ السعة:

{ "status": "waitlisted", "joinUrl": null }

يُطلق التسجيل المؤكَّد رسالة دورة الحياة registered الخاصة بالندوة؛ أما التسجيل في قائمة الانتظار فيتلقى إشعار قائمة الانتظار البسيط بغض النظر عن أي ربط.

POST /api/v1/courses/[id]/enroll

يمنح الوصول إلى دورة لعنوان بريد إلكتروني أو يلغيه، بناءً على قرار الاستحقاق الخاص بك بدلًا من عملية دفع في MailInApp.

الحقل	النوع	مطلوب	ملاحظات
`email`	string	نعم	التحقق نفسه المتّبع في التسجيل؛ ويُحوَّل إلى أحرف صغيرة وتُزال المسافات من طرفيه قبل الاستخدام.
`active`	boolean	لا	القيمة الافتراضية `true`. وقيمة `false` تلغي الوصول.

404 إن لم تكن الدورة موجودة أو لم تكن ملكك. الاستجابة: 200 \{ "subscriberId": "...", "active": true \}.

المنح الجديد (active: true لمشترك لم يكن مستحقًا من قبل) يُطلق رسالة دورة الحياة enrolled الخاصة بالدورة. أما إلغاء الوصول فلا يرسل أبدًا بريدًا إلى المستخدم النهائي نيابة عنك.

POST /api/v1/courses/[id]/embed-token

ينشئ رمزًا موقّعًا قصير الأمد (5 دقائق) لتضمين بوابة الدورة، بعد إعادة التحقق من أن المشترك مستحق فعلًا.

الحقل	النوع	مطلوب	ملاحظات
`email`	string	نعم	التحقق نفسه المذكور أعلاه.

الأخطاء: 404 إن لم تكن الدورة موجودة، أو لم تكن ملكك، أو لم تكن بحالة published؛ و409 إن لم يكن الحساب قد طالب برابط عضوية /learn/<slug> بعد؛ و403 إن لم يكن هذا البريد مستحقًا حاليًا (استدعِ التسجيل أولًا).

الاستجابة: 200 \{ "portalUrl": "https://mailinapp.com/learn/<slug>/courses/<courseId>/embed?token=..." \}. وجّه إطار iframe في تطبيقك أو نافذة جديدة إلى portalUrl — فهو يسجّل دخول الزائر ويوصله إلى بوابة الدورة العادية.

ربط رسائل دورة الحياة

يمكن للدورة أو الندوة ربط أيٍّ من أحداث دورة حياتها بمشروع في الاستوديو بدلًا من نص التأكيد البسيط الخاص بالمنصة:

المورد	الأحداث
الدورة	`enrolled`، و`completed` (يُقبل `reminder` للتماثل، دون مشغّل تلقائي — فالدورات لا تملك موعد استحقاق طبيعيًا يُطلق عنده)
الندوة (`LiveSession`)	`registered`، و`reminder`

يُعيَّن الربط من لوحة رسائل دورة الحياة الخاصة بالدورة/الندوة في لوحة التحكم، لا عبر هذه الواجهة. ويسري مع الحدث التالي بغض النظر عمّا إذا كان قد أُطلق عبر Embed API أو عبر الإجراء المكافئ في لوحة التحكم/النموذج العام. والحدث غير المربوط (أو المربوط بمشروع محذوف/لا يخصّك) يعود مباشرة إلى الرسالة البسيطة الحالية — فهذا لا يُفشل أي إرسال أبدًا.

يُعرض الحدث المربوط عبر renderSingleRecipientEmail تمامًا كوضع القالب في Send API: محرك البدائل الكامل، والعناصر التفاعلية، ورابط عرض مباشر شخصي موقّع. ويلتقطه تتبّع Webhook/الردود الخاص بالمشروع أيضًا، منسوبًا إلى حدث دورة الحياة ذاك تحديدًا بدلًا من صف جهة اتصال مخزّن.

حدود المعدّل

ينطبق حدّان مستقلان، لكل مسار:

لكل مفتاح API: 60 طلبًا/دقيقة. وتجاوزه يعيد 429 \{ "error": "Rate limit exceeded" \} لذلك المفتاح تحديدًا.
لكل حساب، حصة Embed API: تتضمن باقتك عددًا من استدعاءات Embed API في كل شهر تقويمي، مشتركًا بين المسارات الأربعة أعلاه كلها. وقيمة 0 في الباقتين Free/Starter تعيد 403 \{ "error": "The Embed API isn't included in your plan" \}؛ وتجاوز حصة باقة مدفوعة يعيد 429 \{ "error": "Monthly Embed API quota for your plan exceeded" \} حتى تُعاد تعيينها في اليوم 1 من الشهر.

ويعيد إنشاء الندوة إضافةً فحص حصة البث المباشر لديك (checkLiveSessionQuota) — وهو قيد دقائق البث/الدورات نفسه الذي يفرضه مسار الإنشاء في لوحة التحكم — ويعيد 403 مع رسالة ذلك الفحص نفسه إن فشل.

رموز الأخطاء

الحالة	المعنى
`400`	JSON مشوّه أو حقل مطلوب مفقود/غير صالح — راجع جدول كل مسار أعلاه.
`401`	ترويسة `Authorization` مفقودة أو غير صالحة، أو أن المفتاح أُلغي.
`403`	Embed API غير مشمولة في باقتك، أو فشل فحص الحصة، أو تجاوز حصة جلسات البث المباشر، أو (في رمز التضمين) أن البريد غير مستحق حاليًا.
`404`	الندوة/الدورة غير موجودة أو لا يملكها حسابك — وهي عمدًا الاستجابة نفسها لحالة «غير موجود»، للسبب نفسه وراء 404 في وضع القالب في Send API.
`409`	(الندوة) انتهت الجلسة بالفعل. (رمز التضمين) لم يطالب الحساب برابط عضوية بعد.
`429`	تجاوز حدّ المعدّل لكل مفتاح أو الحصة الشهرية.

انظر أيضًا

مرجع Send API — نقطة النهاية المعاملاتية للإرسال الحر/القالب التي تتشارك معها هذه الواجهة نموذج المصادقة.
نظرة عامة على العضوية التعليمية — الدورات والمشتركون والاستحقاق، وهي المفاهيم التي يغلّفها مسارا التسجيل ورمز التضمين.
جلسات البث المباشر والندوات عبر الإنترنت — التسجيل في الندوات، والسعة/قائمة الانتظار، وروابط الانضمام، وهي المفاهيم التي تغلّفها مسارات الندوات.