الموردون

للمسؤولين

الموردون هم وكالات الاستقطاب والجامعات الخارجية التي تتعامل معها مساحة العمل. استخدم هذه النقاط لقراءة الموردين وعقودهم وفواتيرهم وسندات الصرف إلى نظام الـ ERP لديك، ولإبلاغ جديرون بأن فاتورة دُفعت. وللاطلاع على عمل الميزة في التطبيق انظر الموردون.

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

النقاط

الطريقة والمسارما تفعلهالصلاحية
GET /api/v1/suppliersسرد الموردين. المرشّحات type وstatus وupdatedSince وexternalSystem + externalId؛ وlimit وcursorsuppliers.view
GET /api/v1/suppliers/{id}جلب مورد واحدsuppliers.view
GET /api/v1/supplier-contractsسرد العقود. المرشّحات supplierId وstatus وupdatedSincesuppliers.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) وupdatedSincesuppliers.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 وincludeCancelledsuppliers.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نص أو nullSA•• •••• •••• •••• •• يليه آخر رقمين. لا يظهر الآيبان الكامل في هذا المورد أبداً.
bankName وcontactName وemail وphone وcityنص أو null
statusنصPENDING وVERIFIED وSUSPENDED وREJECTED.
verifiedAtISO 8601 أو null
externalRefsمصفوفة[{ system, externalId }]
createdAt وupdatedAtISO 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نص أو nullINV-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 وcancelledAtISO 8601 أو null
paymentReferenceنص أو null
supplierInvoiceNumber وhasSupplierInvoiceFileنص أو null، منطقيالفاتورة الضريبية الخاصة بالمورد.
createdAt وupdatedAtISO 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 تعني أن السند لاغٍ.
createdAtISO 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.