الموظفون

للمسؤولين

الموظفون هم الأشخاص في قائمة مساحة عملك: الموظفون الحاليون والسابقون. استخدم هذه النقاط لمزامنة سجلات الموظفين في جديرون مع نظام تخطيط الموارد (ERP) أو نظام الموارد البشرية لديك. وللمرشحين نقاط خاصة بهم (انظر المرشحون).

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

النقاط

الطريقة والمسار	ما تفعله	الصلاحية
`GET /api/v1/employees`	عرض الموظفين الحاليين والسابقين (ترقيم بالمؤشر، و`updatedSince`، والبحث بالمعرّف الخارجي)	`people.view`
`POST /api/v1/employees`	إضافة موظف	`people.act`
`GET /api/v1/employees/{id}`	عرض موظف واحد	`people.view`
`PATCH /api/v1/employees/{id}`	تعديل موظف؛ الحقول غير المرسلة تبقى كما هي	`people.act`
`DELETE /api/v1/employees/{id}`	إنهاء خدمة موظف: تصبح حالته `FORMER_EMPLOYEE` ويبقى سجله	`people.act`
`POST /api/v1/employees/{id}/archive`	أرشفة موظف	`people.act`
`PUT /api/v1/employees/by-external/{system}/{externalId}`	إنشاء أو تعديل بمعرّف نظامك	`people.act`
`POST /api/v1/employees/bulk`	إدراج أو تعديل حتى 1,000 موظف بالمعرّف الخارجي في الخلفية (انظر الإدراج المجمّع)	`people.act`

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

كائن الموظف

الحقل	النوع	ملاحظات
`id`	نص	معرّف جديرون. يختلف المعرّف بين بيئات جديرون؛ اربط سجلاتك عبر `externalRefs`.
`status`	نص	`EMPLOYEE` (موظف) أو `FORMER_EMPLOYEE` (موظف سابق).
`firstName`، `lastName`	نص	الاسم الأول واسم العائلة.
`email`، `phone`	نص أو null	بيانات التواصل. لا تُخفى بيانات تواصل الموظفين.
`nationality`	نص أو null	رمز الدولة وفق ISO 3166-1 (حرفان)، مثل `SA`.
`nationalId`	نص أو null	رقم الهوية الوطنية أو الإقامة.
`employeeNumber`	نص أو null	الرقم الوظيفي لديك. حقل عمل؛ اربط السجلات عبر `externalRefs`.
`gender`	نص أو null	`MALE` (ذكر) أو `FEMALE` (أنثى).
`birthDate`، `startDate`	ISO 8601 أو null	تاريخ الميلاد وتاريخ المباشرة.
`managerId`	نص أو null	مدير الموظف (موظف آخر).
`currentPositionId`	نص أو null	الوظيفة التي يشغلها الموظف (انظر الوظائف).
`managementLevel`	نص أو null	`SENIOR_MANAGEMENT` (إدارة عليا) أو `INDIVIDUAL_CONTRIBUTOR` (مساهم فردي).
`specialization`، `education`	نص أو null	التخصص والمؤهل.
`yearsExperience`	عدد صحيح أو null	إجمالي سنوات الخبرة.
`govExperienceYears`، `civilServiceExperienceYears`، `entityExperienceYears`	عدد صحيح أو null	الخبرة الحكومية، وفي الخدمة المدنية، وداخل الجهة.
`archivedAt`	ISO 8601 أو null	يُضبط عند أرشفة الموظف.
`externalRefs`	مصفوفة	`[{ system, externalId }]` روابط بأنظمتك.
`createdAt`، `updatedAt`	ISO 8601

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

يتطلب POST الحقلين firstName وlastName، وبقية الحقول اختيارية. القيمة الافتراضية لـstatus هي EMPLOYEE؛ أرسل FORMER_EMPLOYEE لإدخال موظف سابق. والحقول غير المعروفة تُرفض بـ422 validation_failed.

يُشار إلى manager وcurrentPosition بمعرّف جديرون أو بمعرّفك الخاص، وnull يمسحهما:

{
  "manager": { "externalSystem": "oracle-hcm", "externalId": "EMP-1001" },
  "currentPosition": { "id": "cmv…" }
}

يجب أن يكون المدير موظفاً (حالياً أو سابقاً) في مساحة عملك، وأن تتبع الوظيفة مساحة عملك؛ وإلا فالاستجابة 422 unresolved_reference. وبقية الفحوص تتبع قواعد التطبيق:

409 conflict مع details.reason بقيمة position_full إذا لم يكن في الوظيفة مقعد شاغر.
409 conflict مع details.reason بقيمة duplicate_person إذا وُجد في مساحة العمل شخص نشط آخر بالبريد نفسه أو رقم الهوية / الإقامة نفسه أو الرقم الوظيفي نفسه (عند الإنشاء).
422 validation_failed مع details.reason، مثل self_manager (لا يكون الموظف مديراً لنفسه) أو invalid_nationality.

الإنشاء أو التعديل بالمعرّف الخارجي

يبحث PUT /api/v1/employees/by-external/oracle-hcm/EMP-1001 عن الموظف المرتبط بـoracle-hcm / EMP-1001:

وُجد موظف مرتبط: يُطبَّق الطلب كما في PATCH وتكون الاستجابة 200.
لا يوجد موظف مرتبط: يُنشأ موظف من الطلب (أرسل على الأقل firstName وlastName) ويُربط بالمعرّف الخارجي، وتكون الاستجابة 201.

إذا حُذف الموظف المرتبط من داخل التطبيق، يُسقط الرابط القديم وينشئ الطلب موظفاً جديداً برابط جديد. وللعثور على موظف بمعرّفك دون تغييره استدعِ GET /api/v1/employees?externalSystem=oracle-hcm&externalId=EMP-1001 (أرسل المعاملين معاً).

إنهاء الخدمة والأرشفة والحذف

يُنهي DELETE /api/v1/employees/{id} خدمة الموظف: تصبح status بقيمة FORMER_EMPLOYEE، ويبقى السجل وتاريخه، وتكون الاستجابة الموظف بعد التحديث. وإنهاء خدمة موظف سابق لا يغيّر شيئاً. ولإعادة شخص إلى الخدمة أرسل PATCH بالقيمة { "status": "EMPLOYEE" }.

يضبط POST /api/v1/employees/{id}/archive الحقل archivedAt. وأرشفة موظف مؤرشف لا تغيّر شيئاً وتعيده كما هو.

لا تحذف الواجهة البرمجية أي شخص أبداً. وعند حذف شخص من داخل التطبيق (من صفحة الأشخاص أو عبر محرر البيانات) يظهر الحذف في GET /api/v1/deleted?resource=employee لمدة 180 يوماً، مع الروابط الخارجية التي كانت للشخص.

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

الحدث	متى	`data.object`
`employee.created`	إضافة موظف واحد (من التطبيق أو عبر الواجهة البرمجية)، أو تعيين مرشح (مع `application.hired`؛ وتنتقل `externalRefs` الخاصة بالمرشح إلى الموظف، إلا رابطاً يملكه موظف آخر)، أو تحويل مرشح إلى موظف من محرر الأشخاص	الموظف
`employee.updated`	تغيّر بيانات موظف، ومنها إسناده إلى وظيفة في الهيكل التنظيمي، أو فقدان موظف سابق وظيفته عند حذفها (`changedFields: ["currentPositionId"]`)؛ يسرد `data.changedFields` الحقول عند معرفتها	الموظف
`employee.offboarded`	إنهاء خدمة موظف (عبر `DELETE`، أو من التطبيق، أو بضبط `status` على `FORMER_EMPLOYEE`، وهذا يرسل أيضاً `employee.updated`)	الموظف
`employee.archived`	أرشفة موظف	الموظف
`employee.deleted`	حذف موظف من صفحة الأشخاص، أو تحويله إلى مرشح من محرر الأشخاص	`{ id, externalRefs }`
`employee.bulk_changed`	استيراد موظفين (من ملف أو بالذكاء الاصطناعي)، أو تعديلهم أو حذفهم في محرر البيانات، أو تغيّر عدد كبير منهم دفعة واحدة	`{ resource: "employee" }`

لا يرسل الاستيراد ولا محرر البيانات حدثاً لكل موظف: يرسلان employee.bulk_changed، ولا يظهر الموظفون المحذوفون في محرر البيانات إلا في GET /api/v1/deleted.

بعد employee.bulk_changed أعد قراءة القائمة مع ضبط updatedSince على occurredAt للحدث، واقرأ GET /api/v1/deleted?resource=employee&since=… لمعرفة الموظفين المحذوفين.

الأخطاء

الحالة والرمز	المعنى
`403 forbidden`	المفتاح لا يملك الصلاحية المذكورة في الجدول أعلاه.
`404 not_found`	لا يوجد موظف بهذا المعرّف في مساحة عملك.
`409 conflict`	الوظيفة ممتلئة، أو يوجد شخص مكرر، أو المعرّف الخارجي مرتبط بموظف آخر.
`422 validation_failed`	الطلب غير صالح؛ يوضح `details` السبب.
`422 unresolved_reference`	تعذّر العثور على `manager` أو `currentPosition` في مساحة عملك.

مثال

curl -X PUT https://jadiroon.com/api/v1/employees/by-external/oracle-hcm/EMP-1042 \
  -H "Authorization: Bearer $JADIROON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "سارة",
    "lastName": "الحربي",
    "email": "sara.alharbi@example.sa",
    "employeeNumber": "1042",
    "startDate": "2026-01-15",
    "manager": { "externalSystem": "oracle-hcm", "externalId": "EMP-1001" },
    "currentPosition": { "externalSystem": "oracle-hcm", "externalId": "POS-310" }
  }'

ينشئ الطلب الأول الموظف ويربطه ويجيب 201 Created، وتكراره يعدّل الموظف نفسه ويجيب 200 OK بالشكل نفسه:

{
  "id": "cmvk2a8d10007kn5c3e9h1xyz",
  "status": "EMPLOYEE",
  "firstName": "سارة",
  "lastName": "الحربي",
  "email": "sara.alharbi@example.sa",
  "phone": null,
  "nationality": null,
  "nationalId": null,
  "gender": null,
  "birthDate": null,
  "yearsExperience": null,
  "specialization": null,
  "education": null,
  "archivedAt": null,
  "externalRefs": [{ "system": "oracle-hcm", "externalId": "EMP-1042" }],
  "createdAt": "2026-10-22T15:02:11.204Z",
  "updatedAt": "2026-10-22T15:02:11.204Z",
  "employeeNumber": "1042",
  "startDate": "2026-01-15T00:00:00.000Z",
  "managerId": "cmvjx0h1t0003kn3o1b2c3def",
  "currentPositionId": "cmvk1q2w30004kn8x7d1f0abc",
  "managementLevel": null,
  "govExperienceYears": null,
  "civilServiceExperienceYears": null,
  "entityExperienceYears": null
}

← السابق

المرحلة: ملف الموظف

المرحلة: التوقيع الإلكتروني (قادمة مع الميزة)