الموردون هم وكالات الاستقطاب والجامعات الخارجية التي تتعامل معها مساحة العمل. استخدم هذه النقاط لقراءة الموردين وعقودهم وفواتيرهم وسندات الصرف إلى نظام الـ ERP لديك، ولإبلاغ جديرون بأن فاتورة دُفعت. وللاطلاع على عمل الميزة في التطبيق انظر الموردون.
جميع النقاط تحت /api/v1 وتتطلب مفتاح واجهة برمجية (Authorization: Bearer jdr_live_…) ينشئه مسؤول مساحة العمل من الإعدادات ← التكاملات.
النقاط
| الطريقة والمسار | ما تفعله | الصلاحية |
|---|---|---|
GET /api/v1/suppliers | سرد الموردين. المرشّحات type وstatus وupdatedSince وexternalSystem + externalId؛ وlimit وcursor | suppliers.view |
GET /api/v1/suppliers/{id} | جلب مورد واحد | suppliers.view |
GET /api/v1/supplier-contracts | سرد العقود. المرشّحات supplierId وstatus وupdatedSince | suppliers.view |
GET /api/v1/supplier-contracts/{id} | جلب عقد واحد | suppliers.view |
GET /api/v1/supplier-contracts/{id}/file | بثّ ملف PDF للعقد (الملف النهائي الموقَّع مقابلاً إن وُجد) | suppliers.view |
GET /api/v1/supplier-invoices | سرد الفواتير. المرشّحات supplierId وstatus (مثل APPROVED) وupdatedSince | suppliers.view |
GET /api/v1/supplier-invoices/{id} | جلب فاتورة واحدة | suppliers.view |
GET /api/v1/supplier-invoices/{id}/file | بثّ الفاتورة الضريبية الخاصة بالمورد إن رُفعت | suppliers.view |
POST /api/v1/supplier-invoices/{id}/mark-paid | تسجيل أن فاتورة معتمدة دُفعت | suppliers.payments.record |
GET /api/v1/supplier-payment-vouchers | سرد السندات. المرشّحات supplierId وinvoiceId وupdatedSince وincludeCancelled | suppliers.payments.record |
GET /api/v1/supplier-payment-vouchers/{id} | جلب سند واحد مع الآيبان الكامل | suppliers.payments.record |
GET /api/v1/supplier-payment-vouchers/{id}/file | بثّ ملف PDF للسند | suppliers.payments.record |
تستخدم القوائم الترقيم بالمؤشر (limit حتى 100). تستطيع المفاتيح على مستوى النشر قراءة الموردين والعقود والفواتير، لكنها تُرفض (403) على سندات الصرف.
كائن المورد
| الحقل | النوع | ملاحظات |
|---|---|---|
id | نص | |
type | نص | HEADHUNTING_AGENCY وUNIVERSITY؛ أما TRAINING_CENTER وOTHER فمحجوزان وغير مستخدمين بعد. |
legalNameAr وlegalNameEn | نص، نص أو null | |
legalForm | نص | INDIVIDUAL وESTABLISHMENT وCOMPANY. |
crNumber وvatNumber | نص أو null | |
ibanMasked | نص أو null | SA•• •••• •••• •••• •• يليه آخر رقمين. لا يظهر الآيبان الكامل في هذا المورد أبداً. |
bankName وcontactName وemail وphone وcity | نص أو null | |
status | نص | PENDING وVERIFIED وSUSPENDED وREJECTED. |
verifiedAt | ISO 8601 أو null | |
externalRefs | مصفوفة | [{ system, externalId }] |
createdAt وupdatedAt | ISO 8601 |
كائن العقد
id وsupplierId وdirection (PAYABLE؛ وRECEIVABLE محجوز وغير مستخدم بعد) وtitle وfeeModel (PERCENT_OF_ANNUAL_SALARY أو FIXED_AMOUNT أو null لاتفاقية بلا أتعاب؛ وPER_SUBMISSION وSUBSCRIPTION محجوزان وغير مستخدمين بعد) وfeePercent وfeeFixedAmount (نصوص عشرية أو null) وcurrency وvatRate وpaymentTermsDays وstartDate وendDate وownershipWindowDays وscope (ALL_OPEN أو SELECTED) وpositionIds وstatus (DRAFT وSENT وSIGNED وEXPIRED وTERMINATED) وsentAt وterminatedAt وhasFile وcreatedAt وupdatedAt، وكائن signature فيه: signerName وsignedAt وcountersignedAt وpdfSha256 وfinalPdfSha256. لا يُكشف عنوان IP للموقِّع ولا وكيل المستخدم.
كائن الفاتورة
| الحقل | النوع | ملاحظات |
|---|---|---|
id وsupplierId وcontractId | نص | |
direction | نص | PAYABLE |
origin | نص | HIRE أو MANUAL أو CLAIM. |
number | نص أو null | INV-2026-0001، يُحدَّد عند الإصدار. |
status | نص | DRAFT وISSUED وAPPROVED وPAID وCANCELLED. |
applicationId | نص أو null | طلب التوظيف (إدخال المسار) الذي نتج عنه التوظيف. |
positionTitleAr وpositionTitleEn وcandidateName | نص | لقطات تؤخذ عند الإنشاء. |
feeModel وfeePercent وfeeFixedAmount | لقطة من أتعاب العقد. | |
baseAnnualSalary وbaseSource | نص عشري، نص | تكونان null بدون structure.functional.salary، في القراءة وفي خطافات الويب. قيم baseSource: PAY_GRADE وPOSITION وJD_MIN وMANUAL وMISSING. |
amount وvatRate وvatAmount وtotal | نصوص عشرية | المبالغ بعملة currency (SAR). |
dueDate وissuedAt وapprovedAt وpaidAt وcancelledAt | ISO 8601 أو null | |
paymentReference | نص أو null | |
supplierInvoiceNumber وhasSupplierInvoiceFile | نص أو null، منطقي | الفاتورة الضريبية الخاصة بالمورد. |
createdAt وupdatedAt | ISO 8601 |
استعلم دورياً عن GET /api/v1/supplier-invoices?status=APPROVED&updatedSince=… لتجد الفواتير الجاهزة للدفع.
كائن السند
| الحقل | النوع | ملاحظات |
|---|---|---|
id وinvoiceId وsupplierId وnumber | نص | number بصيغة PV-2026-0001. |
amount وcurrency | نص عشري، نص | إجمالي الفاتورة. |
iban | نص | الآيبان الكامل كما حُفظ لحظة الاعتماد. هذا هو المكان الوحيد الذي يخرج منه من جديرون، ويتطلب suppliers.payments.record. |
ibanLast4 وbankName وbeneficiaryName | نص | |
hasFile | منطقي | |
invoiceStatus | نص | حالة الفاتورة. القيمة CANCELLED تعني أن السند لاغٍ. |
createdAt | ISO 8601 |
الفواتير الملغاة والسندات اللاغية
يصبح السند لاغياً عند إلغاء فاتورته. تُستثنى سندات الفواتير الملغاة من القائمة افتراضياً؛ أرسل includeCancelled=true لتضمينها واقرأ invoiceStatus. ولإبقاء نظامك متزامناً راقب حالة الفاتورة: يُظهر GET /api/v1/supplier-invoices?updatedSince=… الحالة CANCELLED، ولا تدفع سنداً فاتورته ملغاة.
تسجيل دفع فاتورة
يتطلب POST /api/v1/supplier-invoices/{id}/mark-paid الصلاحية suppliers.payments.record. أرسل ترويسة Idempotency-Key اختيارية وجسماً صارماً:
{ "paymentReference": "BANK-2026-04411", "paidAt": "2026-11-20" }
paymentReference من 1 إلى 200 حرف؛ وpaidAt تاريخ (YYYY-MM-DD) ولا يجوز أن يكون بعد تاريخ اليوم (بتوقيت الرياض). تُرفض الحقول غير المعروفة. والاستجابة هي الفاتورة بعد التحديث.
- يجب أن تكون الفاتورة
APPROVED. - تكرار المرجع
paymentReferenceنفسه على فاتورةPAIDأصلاً لا يغيّر شيئاً ويعيد200مع الفاتورة. 409 conflictمعdetails.reason:supplier_not_verified: المورد غير موثَّق (مثلاً معلَّق أو أُعيد إلى قيد المراجعة بعد تغيير البنك)؛invalid_status: الفاتورة ليستAPPROVED.
الأحداث
أحداث خطافات الويب لهذه المجموعة من الموارد:
| الحدث | متى | الكائن |
|---|---|---|
supplier.verified | وُثّق مورد أو أُعيد تفعيله. | المورد |
supplier_contract.signed | وقّعت مساحة العمل توقيعاً مقابلاً فأصبح العقد ساريًا. | العقد |
application.supplier_submitted | رشّح مورد مرشحاً (غير مكرر). | الطلب |
supplier_invoice.issued | صدرت فاتورة. | الفاتورة |
supplier_invoice.approved | اعتُمدت فاتورة وأُنشئ سندها. | الفاتورة |
supplier_invoice.paid | سُجّل دفع فاتورة. | الفاتورة |
تحمل أحداث الفواتير الفاتورة مع baseAnnualSalary وbaseSource بقيمة null للنقاط التي لا يملك مفتاحها structure.functional.salary. ليس للسندات أحداث. أما بقية تغييرات الموردين (التعليق والرفض والمسودات والإلغاء) ففي سجل التدقيق لكنها لا ترسل حدث مورد. انظر فهرس الأحداث.
الوظائف
يعيد DELETE /api/v1/positions/{id} الاستجابة 409 conflict مع details.reason بقيمة has_supplier_submissions حين يكون مورد قد رشّح مرشحاً لهذه الوظيفة. انظر الوظائف.
الأخطاء
تسري الاتفاقيات المعتادة. المفتاح الذي لا يملك الصلاحية المطلوبة يتلقى 403 forbidden؛ ومعرّف من مساحة عمل أخرى يتلقى 404 not_found.