الشواغر

للمسؤولين

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

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

النقاط

الطريقة والمسار	ما تفعله	الصلاحية
`GET /api/v1/openings`	عرض الشواغر (ترقيم بالمؤشر، و`updatedSince`، و`?positionId=`، و`?status=`)	`recruitment.view`
`POST /api/v1/openings`	فتح وظيفة للتوظيف	`recruitment.hiring.open`
`GET /api/v1/openings/{id}`	عرض شاغر واحد	`recruitment.view`
`POST /api/v1/openings/{id}/close`	إغلاق شاغر	`recruitment.hiring.open`

يستخدم الفتح والإغلاق الصلاحية نفسها المستخدمة في التطبيق. ومعرّف الشاغر معرّف خاص به، وليس معرّف الوظيفة. للوظيفة شاغر واحد على الأكثر بحالة OPEN في الوقت نفسه، وتبقى الجولات السابقة في القائمة بحالة CLOSED أو FILLED. والمعرّف من مساحة عمل أخرى يُعيد 404 not_found.

كائن الشاغر

الحقل	النوع	ملاحظات
`id`	نص	معرّف الشاغر.
`positionId`	نص	الوظيفة التي يجري التوظيف لها. راجع الوظائف.
`title`	`{ ar, en }`	مسمى الوظيفة؛ وإذا غابت لغة يُستخدم اسم وصفها الوظيفي.
`status`	نص	`OPEN`، أو `CLOSED` (أُغلق يدوياً أو بأرشفة الوظيفة)، أو `FILLED` (أُغلق بالتعيين).
`hiringPathway`	نص أو null	أثناء `OPEN`: `INTERNAL_ONLY`، أو `INTERNAL_FIRST` (الموظفون أولاً ثم الخارج)، أو `EXTERNAL`. وnull في غير ذلك.
`externalAt`	ISO 8601 أو null	أثناء `OPEN`: موعد فتح الشاغر للخارج (فوراً مع `EXTERNAL`، وبعد فترة الأولوية الداخلية مع `INTERNAL_FIRST`، ولا يُفتح أبداً مع `INTERNAL_ONLY`).
`openedAt`، `closedAt`	ISO 8601	`closedAt` فارغ ما دام الشاغر مفتوحاً.
`externalRefs`	مصفوفة	`[{ system, externalId }]` روابط إلى أنظمتك.
`createdAt`، `updatedAt`	ISO 8601

فتح وظيفة للتوظيف

يأخذ POST /api/v1/openings الوظيفة، بمعرّفها أو بمعرّفك الخارجي، ومسار توظيف اختيارياً ونص إعلان اختيارياً:

{ "position": { "externalSystem": "oracle-hcm", "externalId": "POS-2207" }, "hiringPathway": "INTERNAL_FIRST" }

دون hiringPathway يُستخدم المسار السابق للوظيفة (INTERNAL_FIRST في المرة الأولى). وتنطبق قواعد التطبيق نفسها:

يجب أن يكون للوظيفة وصف وظيفي وموضع في الهيكل التنظيمي (422 validation_failed مع details.reason بقيمة not_hire_ready وdetails.missing)؛
ويجب أن يكون لها نص إعلان (422 validation_failed مع details.reason بقيمة no_job_description). الوظيفة المُنشأة عبر الواجهة البرمجية ليس لها نص إعلان: أرسل posting مع الطلب حين لا يكون للوظيفة نص، { "posting": { "ar": "…", "en": "…" } } (لغة واحدة على الأقل). يُحفظ نصاً لإعلان الوظيفة (الحقل posting في الوظيفة)، واللغة التي لا ترسلها أو ترسلها فارغة يبقى نصها الحالي؛
ويجب ألا يكون وصفها الوظيفي مؤرشفاً (422 validation_failed مع details.reason بقيمة archived)، وإلا فشلت كل الطلبات عليها؛
ولا يمكن فتح وظيفة مؤرشفة (409 conflict، position_archived)؛ أعدها من الأرشيف في التطبيق أولاً؛
والوظيفة التي لها شاغر OPEN تُعيد 409 conflict مع details.reason بقيمة already_open وdetails.openingId.

الاستجابة 201 Created مع الشاغر. تُنشأ الوظائف الجديدة من الوظائف، والواجهة البرمجية تفتح الوظائف الموجودة.

الإغلاق

يُغلق POST /api/v1/openings/{id}/close التوظيف على الوظيفة (تصبح حالة توظيفها CLOSED) والشاغر معها. وإغلاق شاغر ليس بحالة OPEN لا يغيّر شيئاً ويُعيده كما هو. ويحتفظ المرشحون عليه بطلباتهم.

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

الحدث	متى	`data.object`
`opening.created`	إنشاء وظيفة وفتحها في خطوة واحدة من التطبيق	الشاغر
`opening.opened`	فتح التوظيف على وظيفة (من التطبيق أو الواجهة البرمجية)	الشاغر
`opening.closed`	إغلاق التوظيف على وظيفة (من التطبيق أو الواجهة البرمجية)، أو أرشفة وصفها الوظيفي أو حذفه	الشاغر
`opening.archived`	أرشفة الوظيفة (يُغلق شاغرها المفتوح)	الشاغر
`opening.updated`	تغيّر مسمى الشاغر، أو فتحه للخارج فوراً، أو إعادة وظيفته من الأرشيف؛ يسرد `data.changedFields` الحقول عند معرفتها	الشاغر

الفتح والإغلاق يغيّران حقول التوظيف في الوظيفة أيضاً، لذا يرسلان position.updated كذلك، والوظيفة التي تُنشأ من مسار الشواغر ترسل position.created. ويحمل كل حدث الشاغر الذي يخصه، وأرشفة وظيفة ليس لها شاغر مفتوح لا ترسل opening.archived.

الأخطاء

الحالة والرمز	المعنى
`403 forbidden`	المفتاح لا يملك الصلاحية المذكورة في الجدول أعلاه.
`404 not_found`	لا يوجد شاغر بهذا المعرّف في مساحة عملك.
`409 conflict`	`already_open` أو `position_archived`.
`422 unresolved_reference`	مرجع الوظيفة لا يطابق وظيفة في مساحة عملك.
`422 validation_failed`	الطلب غير صالح، أو الوظيفة غير جاهزة للتوظيف (`not_hire_ready`، `no_job_description`).

مثال

curl -X POST https://jadiroon.com/api/v1/openings \
  -H "Authorization: Bearer $JADIROON_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: open-POS-2207-2026-10" \
  -d '{ "position": { "id": "cmvikf8270086knoq85hjhu3u" }, "hiringPathway": "INTERNAL_ONLY" }'

{
  "id": "cmvm6inad0002kncr1pytpf2x",
  "positionId": "cmvikf8270086knoq85hjhu3u",
  "title": { "ar": "طبيب أخصائي", "en": "Specialist Physician" },
  "status": "OPEN",
  "hiringPathway": "INTERNAL_ONLY",
  "externalAt": null,
  "openedAt": "2026-10-24T09:11:06.085Z",
  "closedAt": null,
  "externalRefs": [],
  "createdAt": "2026-10-24T09:11:06.085Z",
  "updatedAt": "2026-10-24T09:11:06.085Z"
}

← السابق

المرحلة: فتح الشواغر

المرحلة: الاعتماد