الإدراج المجمّع

يحمّل الإدراج المجمّع حتى 1,000 موظف أو مرشح أو وحدة تنظيمية أو وظيفة في طلب واحد، ويُطابَق كل صف بمعرّف نظامك. يعالج جديرون الصفوف في الخلفية، وتستعلم أنت عن المهمة لمعرفة نتيجة كل صف. استخدمه للتحميل الأول من نظام تخطيط الموارد (ERP) ولعمليات المزامنة الدورية الكبيرة؛ أما للسجل الواحد فاستخدم نقطة PUT .../by-external/{system}/{externalId} الخاصة بالمورد.

النقاط

إرسال مهمة

أرسل { "rows": [ … ] } بعدد صفوف من 1 إلى 1,000 مع ترويسة Idempotency-Key (إلزامية). كل صف هو جسم طلب PUT بالمعرّف الخارجي للمورد، مع المفتاح داخله في system وexternalId:

{
  "rows": [
    { "system": "oracle-hcm", "externalId": "EMP-1001", "firstName": "Sara", "lastName": "Alharbi" },
    { "system": "oracle-hcm", "externalId": "EMP-1002", "firstName": "Omar", "lastName": "Alqahtani",
      "manager": { "externalSystem": "oracle-hcm", "externalId": "EMP-1001" } }
  ]
}

الاستجابة 202 { "jobId": "…", "statusUrl": "/api/v1/bulk-jobs/…" }. وإعادة إرسال الطلب نفسه بـIdempotency-Key نفسه (خلال 24 ساعة) تعيد jobId نفسه ولا تبدأ شيئاً جديداً.

• أكثر من 1,000 صف أو لا صفوف: 422 validation_failed.
• يمكن أن يكون للتكامل مهمتان في الانتظار أو قيد التشغيل في الوقت نفسه؛ والثالثة تتلقى 429 too_many_jobs. انتظر انتهاء إحداهما ثم أعد الإرسال (يمكن إعادة استخدام المفتاح نفسه بعد 429).
• يُحسب الطلب المجمّع طلباً واحداً في حدود المعدّل.

تُعالَج الصفوف بالترتيب، فيمكن لصف أن يشير إلى سجل أنشأه صف سابق في المهمة نفسها (مثل وحدة فرعية تذكر وحدتها الأم بمعرّفها الخارجي).

المرشحون: يمكن أن يحمل الصف cvUrl، وهو رابط https لسيرة المرشح الذاتية. تنزّله المهمة (من مضيفات عامة فقط، ودون اتباع إعادة التوجيه) وتخزّنه بشكل خاص؛ ويجب أن يكون ملف PDF لا يتجاوز 5 ميغابايت، كما في التطبيق، وأن يكتمل تنزيله خلال 20 ثانية. السيرة التي يتعذّر جلبها تُفشل ذلك الصف وحده، مع details.path بقيمة cvUrl وdetails.reason مثل cv_not_pdf أو cv_too_large أو cv_unreachable أو cv_forbidden_host. والصف الذي يرسل email أو phone أو nationalId بقيمة غير فارغة يحتاج أن يملك المفتاح recruitment.candidate.contact، سواء أنشأ المرشح أم عدّله؛ ودونها يفشل ذلك الصف وحده بـ403 forbidden (details.reason بقيمة candidate_contact_required).

القواعد نفسها للكتابة المفردة

يمر كل صف بالخدمة نفسها التي يمر بها طلب PUT المفرد بالمعرّف الخارجي: التحقق والصلاحيات والفحوص نفسها. الصف الذي كان سيُرفض وحده يفشل وحده، وتُكتب بقية الصفوف. ولكل سجل يُكتب سطر تدقيق خاص به (المنفّذ: تكاملك) وحدث خطاف ويب خاص به (employee.created وorg_unit.updated وغيرهما)، تماماً كما لو أرسلته منفرداً. توقّع حدثاً لكل سجل في التحميلات الكبيرة.

قراءة المهمة

يعيد GET /api/v1/bulk-jobs/{id}:

النتائج مرقّمة (limit حتى 100، وcursor)، و?status=failed يعرض الصفوف الفاشلة فقط. ومهمة تكامل آخر تعيد 404 not_found.

أخطاء الصفوف الشائعة: validation_failed (مع details.issues[].path لصف غير صالح، أو details.reason مثل first_name_required عندما ينقص سجلاً جديداً حقل إلزامي)، وunresolved_reference (السجل المشار إليه غير موجود)، وconflict (مثل duplicate_person أو position_full)، وforbidden.

تبدأ المهمة فور الرد 202 وتعمل حتى دقيقة تقريبًا، وتنتهي معظم المهام حينها. وفي الخدمة المستضافة، يُكمل ما تبقى من المهمة الأطول مُرسِلٌ يعمل في الخلفية، وتشغّله الخدمة حاليًا مرة واحدة يوميًا (03:00 بالتوقيت العالمي UTC). تبقى النتائج متاحة للقراءة بعد انتهاء المهمة، أما الصفوف المرسلة نفسها فتُحذف عند وصول المهمة إلى DONE (وبعد نحو أسبوع على الأكثر).