المرشحون

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

جميع النقاط تحت /api/v1 وتتطلب مفتاح واجهة برمجية (Authorization: Bearer jdr_live_…) ينشئه مسؤول مساحة العمل من الإعدادات ← التكاملات.

النقاط

صلاحية recruitment.act تشمل recruitment.view. والمعرّف الذي يخص موظفاً أو مساحة عمل أخرى يُعيد 404 not_found.

بيانات التواصل مخفية دون صلاحية التواصل

المفتاح الذي لا يملك recruitment.candidate.contact يتلقى email وphone وnationalId الخاصة بالمرشح مخفية، في كل استجابة وفي حمولات خطافات الويب:

{ "email": "s•••@example.com", "phone": "05•• ••• •12", "nationalId": "••••••12" }

امنح التكامل صلاحية recruitment.candidate.contact ليتلقى القيم الحقيقية. ودونها يُرفض POST الذي يرسل email أو phone أو nationalId بقيمة غير فارغة بـ403 forbidden (details.reason بقيمة candidate_contact_required)، ويتجاهل PATCH الحقول email وphone وnationalId (لا تتغيّر القيم المخزنة)، ولا تُخزَّن قيمة مخفية أبداً أياً كان مرسلها. ويحتاج تنزيل السيرة الذاتية صلاحية التواصل أيضاً، لأن الملف نفسه يعرض بيانات تواصل المرشح (انظر أدناه).

كائن المرشح

الإنشاء والتعديل

يتطلب POST الحقلين firstName وlastName، وبقية حقول الملف (email وphone وnationality وnationalId وgender وbirthDate وyearsExperience وspecialization وeducation وlinkedinUrl وportfolioUrl) اختيارية. ويقبل PATCH الحقول نفسها ويترك غير المرسلة كما هي. والحقول غير المعروفة، ومنها status، تُرفض بـ422 validation_failed: لا يصبح المرشح موظفاً إلا بتعيينه.

عند الإنشاء، يحتاج إرسال email أو phone أو nationalId بقيمة غير فارغة إلى recruitment.candidate.contact: ودونها يُرفض الطلب بـ403 forbidden مع details.reason بقيمة candidate_contact_required وdetails.required بقيمة ["recruitment.candidate.contact"]، قبل أي فحص للتكرار (أرسل null أو احذف هذه الحقول لإنشاء المرشح دون بيانات تواصل). ومع الصلاحية، تعني 409 conflict مع details.reason بقيمة duplicate_person وجود شخص نشط آخر في مساحة العمل بالبريد نفسه أو رقم الهوية / الإقامة نفسه. ويجب أن تكون روابط الملف بعناوين http أو https.

تنزيل السيرة الذاتية

يبث GET /api/v1/candidates/{id}/cv الملف نفسه مع Content-Disposition: attachment; filename="cv-<id>.pdf" (يتبع الامتداد الملف المخزن). ولا يُعاد موقع التخزين أبداً. وتكون الاستجابة 404 not_found إذا لم تكن للمرشح سيرة ذاتية.

تعرض السيرة الذاتية بريد المرشح وهاتفه، لذا يحتاج التنزيل recruitment.candidate.contact إلى جانب recruitment.view. والمفتاح الذي لا يملكها يتلقى 403 forbidden مع details.reason بقيمة candidate_contact_required وdetails.required بقيمة ["recruitment.candidate.contact"]، سواء كانت للمرشح سيرة ذاتية أم لا. ويظهر hasCv في كائن المرشح لكل مفتاح يقرأ المرشحين. وتستطيع المفاتيح على مستوى النشر تنزيل السير الذاتية.

curl -o cv.pdf https://jadiroon.com/api/v1/candidates/cmvk3c9e20001kn7d4f8g2hij/cv \
  -H "Authorization: Bearer $JADIROON_KEY"

أحداث خطافات الويب

التعيين من الطلبات يرسل application.hired وemployee.created بالمعرّف نفسه، وليس candidate.deleted: احذف الشخص من قائمة المرشحين لديك عند استلامهما. وتنتقل externalRefs الخاصة بالمرشح إلى الموظف. وإذا كان موظف آخر يملك { system, externalId } نفسه فلا ينتقل هذا الرابط، ويبقى الموظف الجديد دون رابط لذلك النظام؛ اربطه من جديد بنقطة الموظفين بالمعرّف الخارجي.

تتبع الحمولات قاعدة الإخفاء نفسها: نقطة الاستقبال التي لا يملك تكاملها recruitment.candidate.contact تتلقى بيانات التواصل مخفية. وتظهر عمليات الحذف أيضاً في GET /api/v1/deleted?resource=candidate لمدة 180 يوماً.

الأخطاء

مثال

curl -X POST https://jadiroon.com/api/v1/candidates \
  -H "Authorization: Bearer $JADIROON_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: jobboard-C-881" \
  -d '{
    "firstName": "فيصل",
    "lastName": "القحطاني",
    "email": "faisal@example.com",
    "phone": "0551234512",
    "nationality": "SA",
    "specialization": "تمريض",
    "yearsExperience": 4
  }'

يحتاج المفتاح إلى recruitment.candidate.contact لأن الطلب يرسل email وphone (ودونها تكون الاستجابة 403 forbidden). وتكون الاستجابة 201 Created:

{
  "id": "cmvk3c9e20001kn7d4f8g2hij",
  "firstName": "فيصل",
  "lastName": "القحطاني",
  "email": "faisal@example.com",
  "phone": "0551234512",
  "nationality": "SA",
  "nationalId": null,
  "gender": null,
  "birthDate": null,
  "yearsExperience": 4,
  "specialization": "تمريض",
  "education": null,
  "archivedAt": null,
  "externalRefs": [],
  "createdAt": "2026-10-22T15:02:11.204Z",
  "updatedAt": "2026-10-22T15:02:11.204Z",
  "linkedinUrl": null,
  "portfolioUrl": null,
  "hasCv": false
}