# ربط تطبيقك بواجهة API للبوابة

قدّم الاختبار من واجهتك، واحتفظ بالعملاء وتقاريرهم والرصيد في حساب البوابة نفسه. يجري الاتصال بين خادمك وخادم البوابة؛ لذلك لا تضع المفتاح في كود المتصفح أو تطبيق الجوال. استخدم عنوان الخادم المخصّص لبيئتك، متبوعًا بـ `/partner/v1`. الإصدار الثاني للبوابة هو إصدار المنتج، أما `/partner/v1` فهو إصدار الواجهة البرمجية.

## تجهيز المفتاح

من الإعدادات ← المطوّر، سمِّ المفتاح وأنشئه لربط خادمك بالبوابة. يتيح المفتاح الجديد إجراء الاختبارات والوصول إلى التقارير واختبار الاتصال أيضًا. أما المفاتيح القديمة المخصّصة لاختبار الاتصال فقط، فتبقى بصلاحياتها الحالية؛ أنشئ مفتاحًا جديدًا إذا احتجت إلى الاختبارات والتقارير.

يتيح مفتاح الربط تعديل بيانات العملاء، وإدارة الاختبارات المنشأة عبر API، وقراءة جميع التقارير الكاملة المتاحة للحساب، واستخدام رصيده. الحد الأقصى خمسة مفاتيح نشطة، وصلاحية كل مفتاح 90 يومًا. ألغِ المفتاح لإيقاف وصوله. يتوقف أيضًا إذا فقد الحساب أو المالك الذي أنشأه صلاحية الوصول.

أرسل الترويسة `Authorization: Bearer YOUR_KEY` مع كل طلب. لا تحتاج إلى معرّف مزوّد. الحد هو 60 طلبًا لكل مفتاح في الدقيقة؛ إذا ورد الرمز 429، انتظر المدة المحددة في `Retry-After`.

## من بيانات العميل إلى التقرير

1. تحقّق من الاتصال والصلاحيات بطلب `GET /status`.
2. أرسل `PUT /participants` مع `fullName` و`email` و`locale`، ويمكنك إضافة `externalId` لربط العميل بسجلاتك. احفظ `participant.id`. البريد المسجّل مسبقًا يحدّث العميل نفسه داخل حسابك. العميل المؤرشف لا يقبل التحديث، وتغيير البريد ينشئ سجل عميل مختلفًا.
3. أرسل `POST /assessments` مع `participantId` و`locale` و`expiresAt`، وترويسة `Idempotency-Key` بقيمة فريدة. اختر موعد انتهاء لاحقًا، خلال 180 يومًا كحد أقصى، واحفظ `assessment.id`.
4. اطلب `GET /assessments/{assessmentId}/questions`، واعرض الأسئلة وخيارات الإجابة كما وردت وبالترتيب نفسه. يتكوّن الاختبار من 120 سؤالًا، ويتاح بالعربية والإنجليزية والإسبانية.
5. احفظ الإجابات الفعلية عبر `PUT /assessments/{assessmentId}/answers`. يتضمن الطلب مصفوفة `answers`؛ كل عنصر فيها يحتوي `questionId` و`value` بعدد صحيح من 1 إلى 5. يمكن إرسال إجابة واحدة إلى 120 إجابة، دون تكرار معرّف السؤال في الطلب نفسه. تُحدَّث الإجابة السابقة للسؤال عند إعادة إرسالها.
6. بعد حفظ جميع الإجابات، أرسل `POST /assessments/{assessmentId}/complete` مع كائن JSON فارغ. احفظ `result.id`. يمكنك استعادته بعد الإكمال أيضًا من `GET /assessments/{assessmentId}`.
7. تحقّق من الرصيد عبر `GET /credits`، ثم أرسل `POST /reports` مع `assessmentResultId` وترويسة `Idempotency-Key` مستقلة. احفظ `report.id`. إصدار تقرير دائم جديد يستهلك **رصيدًا واحدًا**؛ إنشاء الاختبار وإكماله لا يستهلكان رصيدًا.
8. اقرأ التقرير عبر `GET /reports/{reportId}`. أضف `?locale=ar` أو `?locale=en` أو `?locale=es` لعرضه باللغة المطلوبة. القراءة مجانية ولا تغيّر لغة التقرير المحفوظ. المحتوى وطريقة العرض هما المعتمدان في تقرير المالك، دون افتراض عدد ثابت للمؤشرات.

تدير مسارات الاختبار الجلسات المنشأة عبر هذه الواجهة فقط. أما قراءة التقارير فتشمل جميع التقارير الكاملة المتاحة للحساب، بما فيها الصادرة من البوابة مباشرة.

## إعادة المحاولة والرصيد

اختر قيمة `Idempotency-Key` من 8 إلى 128 حرفًا لاتينيًا أو رقمًا، ويمكن استخدام النقطتين والشرطة والشرطة السفلية. احتفظ بالقيمة نفسها والبيانات نفسها لإعادة الطلب بعد تعذّره، واستخدم قيمة مستقلة للعملية التالية. تغيير البيانات مع المعرّف نفسه يعيد خطأ تعارض 409. احفظ هذه القيم مع معرّفات العميل والاختبار والنتيجة والتقرير في نظامك.

إعادة الإكمال تعيد النتيجة المحفوظة. وطلب تقرير صادر مسبقًا يعيد التقرير نفسه دون خصم آخر، حتى عند استخدام معرّف طلب جديد. إذا تعذّر إنشاء التقرير، يُعاد الرصيد المحجوز. عالج السبب ثم أعد الطلب بالمعرّف الأصلي؛ فقد يصل ردّ فاشل رغم نجاح الحفظ.

الرمز 409 قد يعني أن الإجابات لم تكتمل، و402 يعني أن الرصيد لا يكفي، و410 يعني انتهاء الاختبار. السجل غير الموجود أو التابع لحساب آخر يعيد 404. المفتاح غير الصالح يعيد 401، والصلاحية غير الكافية تعيد 403. الحد الأقصى لجسم الطلب 32 KiB بصيغة JSON، وتُرفض الحقول غير المتوقعة. جميع الردود تحمل `Cache-Control: no-store`.

## ظهور البيانات والمشاركة

تظهر بيانات العميل وتقاريره في أقسام البوابة المعتادة، ويظهر الخصم في صفحة الرصيد. يبقى `externalId` مرجعًا داخل حسابك لربط أنظمتك؛ إغفاله يحافظ على القيمة السابقة، وإرساله قد يحدّثها. لا يظهر في تقارير المستلمين أو رسائل البريد أو ملفات PDF. تحدّد لغة الاختبار لغة الأسئلة والتقرير الأصلي؛ أما لغة طلب القراءة فتخص الردّ فقط.

لا ترسل هذه الخطوات دعوات أو تقارير بالبريد، ولا تنشئ رابط مشاركة عامًا. مشاركة التقرير إجراء مستقل ينفّذه المالك. لا تستخدم هذه المسارات لتجاوز إجراءات الدعوة أو التسليم التلقائي في البوابة.

## الأمثلة والمراجع

تعرض صفحة المطوّر أمثلة **Bash/cURL** قابلة للنسخ. اضبط `PORTAL_API_BASE` و`PORTAL_API_KEY`، ثم احفظ المعرّفات الواردة في متغيّرات البيئة المطلوبة. حدّد تاريخ الانتهاء ومعرّفي طلب إنشاء الاختبار وإصدار التقرير، وجهّز ملف `answers.json` بالإجابات الفعلية.

استورد [مجموعة Postman](/developer/portal-partner-v1.postman.json)، وأدخل `baseUrl` متبوعًا بـ `/partner/v1` والمفتاح `apiKey` محليًا. أضف `expiresAt` و`answersJson`. تحفظ المجموعة المعرّفات الواردة وتُنشئ معرّفات الطلبات عند غيابها؛ احتفظ بها للمحاولة مجددًا وامسحها عند بدء اختبار أو تقرير جديد. تنفيذ طلب إصدار التقرير يستهلك رصيدًا. لا تشارك ملف تصدير يتضمن المفتاح أو بيانات العملاء.

تجد الحقول بالتفصيل في [مرجع API بالإنجليزية](/developer/portal-partner-v1.reference.html) و[مواصفات OpenAPI](/developer/portal-partner-v1.openapi.json). المراجع القديمة التي تستخدم معرّفات المزوّد ومساراته تخص واجهة سابقة، ولا تنطبق على الحسابات الحالية.