الوحدات التنظيمية

للمسؤولين

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

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

النقاط

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

صلاحية structure.org.act تشمل structure.org.view.

كائن الوحدة التنظيمية

الحقل	النوع	ملاحظات
`id`	نص	معرّف جديرون. يختلف المعرّف بين بيئات جديرون؛ اربط سجلاتك عبر `externalRefs`.
`name`	`{ ar, en }`	الحقل `name.ar` مطلوب.
`type`	نص	`ENTITY` أو `SECTOR` أو `AGENCY` أو `BRANCH` أو `GENERAL_ADMIN` أو `ADMIN` أو `SECTION` أو `UNIT`.
`parentId`	نص أو null	null للوحدة الجذرية.
`function`	`{ ar, en }`	تخصص الوحدة أو وظيفتها.
`headName`، `headRole`	نص أو null	رئيس الوحدة ومسمّاه.
`headcount`	عدد صحيح	العدد الحالي (صفر أو أكثر).
`ssoCode`	نص أو null	رمز التصنيف السعودي الموحد، للقراءة فقط.
`status`	نص	`DRAFT` (مسودة) أو `APPROVED` (معتمد).
`sortOrder`	عدد صحيح أو null	ترتيب العرض، للقراءة فقط.
`externalRefs`	مصفوفة	`[{ system, externalId }]` روابط بأنظمتك.
`createdAt`، `updatedAt`	ISO 8601	يتغيّر `updatedAt` أيضاً عند تعديل الوحدة من داخل التطبيق.

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

يقبل POST الحقلين name وtype، واختيارياً parent وfunction وheadName وheadRole وheadcount وstatus (تُنشأ الوحدة مسودةً DRAFT ما لم ترسل status). تُرفض الحقول غير المعروفة.

يحدّد parent الوحدة الرئيسية بمعرّف جديرون أو بمعرّف نظامك:

{ "parent": { "id": "cmv…" } }
{ "parent": { "externalSystem": "oracle-hcm", "externalId": "ORG-100" } }
{ "parent": null }

القيمة null تنقل الوحدة إلى الجذر. إذا لم تُوجد الوحدة الرئيسية في مساحة عملك يُعاد 422 unresolved_reference. ونقل وحدة تحت نفسها أو تحت إحدى الوحدات المتفرعة منها يُعيد 422 validation_failed مع details.reason بقيمة self_parent أو cycle.

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

يبحث الطلب PUT /api/v1/org-units/by-external/oracle-hcm/ORG-200 عن الوحدة المرتبطة بـ oracle-hcm / ORG-200:

إذا وُجدت وحدة مرتبطة: يُطبَّق الطلب مثل PATCH ويكون الرد 200.
إذا لم تُوجد: تُنشأ وحدة من الطلب (أرسل على الأقل name.ar وtype) وتُربط بالمعرّف الخارجي، ويكون الرد 201.

الحد الأقصى لـ system هو 64 حرفاً، ولـ externalId هو 128 حرفاً. للعثور على وحدة بمعرّفك دون تعديلها استخدم GET /api/v1/org-units?externalSystem=oracle-hcm&externalId=ORG-200 (أرسل المعاملين معاً؛ إرسال أحدهما وحده يُعيد 422 validation_failed).

الحذف

لا يحذف DELETE إلا وحدة ليس لها وحدات فرعية، وإلا يُعيد 409 has_children مع details.childCount: انقل الوحدات الفرعية أو احذفها أولاً.

عند حذف وحدة:

تبقى الوظائف المسكّنة فيها، لكنها تصبح بلا وحدة تنظيمية. يتغيّر updatedAt لكل منها ويُرسل حدث position.updated لكل وظيفة حتى 500 وظيفة؛ وما زاد على ذلك يغطيه حدث واحد position.bulk_changed.
تُحذف مهام عبء العمل الخاصة بالوحدة معها.
تُزال روابطها الخارجية، ويظهر الحذف في GET /api/v1/deleted?resource=org_unit لمدة 180 يوماً.

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

الحدث	متى	`data.object`
`org_unit.created`	إنشاء وحدة (من التطبيق أو الواجهة البرمجية)	الوحدة التنظيمية
`org_unit.updated`	تعديل وحدة؛ يسرد `data.changedFields` الحقول المعدّلة	الوحدة التنظيمية
`org_unit.deleted`	حذف وحدة	`{ id, externalRefs }`
`org_unit.bulk_changed`	استيراد الهيكل (ملف أو قالب أو رابط) أو استبداله من التطبيق	`{ resource: "org_unit" }`

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

الأخطاء

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

مثال

curl -X PUT https://jadiroon.com/api/v1/org-units/by-external/oracle-hcm/ORG-200 \
  -H "Authorization: Bearer $JADIROON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": { "ar": "إدارة الموارد البشرية", "en": "Human Resources" },
    "type": "ADMIN",
    "parent": { "externalSystem": "oracle-hcm", "externalId": "ORG-100" },
    "headcount": 12
  }'

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

{
  "id": "cmvjmf15k0008kn4q404rqwgw",
  "name": { "ar": "إدارة الموارد البشرية", "en": "Human Resources" },
  "type": "ADMIN",
  "parentId": "cmvjmeq4p0002kn4qq820gqll",
  "function": { "ar": null, "en": null },
  "headName": null,
  "headRole": null,
  "headcount": 12,
  "ssoCode": null,
  "status": "DRAFT",
  "sortOrder": null,
  "externalRefs": [{ "system": "oracle-hcm", "externalId": "ORG-200" }],
  "createdAt": "2026-10-22T14:12:52.761Z",
  "updatedAt": "2026-10-22T14:12:52.761Z"
}

← السابق

المرحلة: الإعداد والتهيئة

الوظائف