Waafir
هذه الصفحة ترجمة آلية في انتظار المراجعة البشرية. قد تحتوي على أخطاء.

عمليات CRUD للسجل الواحد

واجهة CRUD للسجل الواحد هي المسار منخفض الحجم: استدعاء HTTP واحد لكل صف. استخدمها لعمليات الكتابة التشغيلية — قرض جديد واحد، أو دفعة واحدة لم تصل ضمن الدفعة اليومية، أو انتقال في الحالة — وللقراءة بواسطة UUID المنصة. لدفعات نهاية اليوم استخدم NDJSON المجمّع؛ وللتحميلات التاريخية استخدم الاستيرادات غير المتزامنة.

يلتزم كل مسار في هذه الصفحة بالعقد الموثّق في النظرة العامة: المصادقة برمز Bearer، وضمانات التكامل، وغلاف fieldErrors، ودلالات الإلغاء، وكيفية تسجيل كل إرسال. لا يذكر التوثيق التفصيلي لكل مسار أدناه إلا الأشكال الخاصة بذلك المسار؛ ارجع إلى النظرة العامة للسلوك المشترك.

المسارات في لمحة

الطريقةالمسارالغرض
POST/api/v1/monitoring/loan/borrowersإنشاء مقترض
GET/api/v1/monitoring/loan/borrowers/{id}قراءة مقترض بواسطة UUID مع إخفاء المعلومات الشخصية
POST/api/v1/monitoring/loan/loansإنشاء قرض
POST/api/v1/monitoring/loan/paymentsإنشاء دفعة فعلية
GET/api/v1/monitoring/loan/payments/{id}قراءة دفعة فعلية بواسطة UUID
PATCH/api/v1/monitoring/loan/loans/{loanRef}/statusنقل قرض إلى حالة جديدة
POST/api/v1/monitoring/loan/payments/{id}/cancelحذف دفعة حذفًا منطقيًا

تقبل كل مسارات التعديل ترويسة Idempotency-Key ومعامل الاستعلام ?dryRun=true، وتُرجع غلاف fieldErrors المنظَّم عند فشل التحقق.

POST /api/v1/monitoring/loan/borrowers

ينشئ مقترضًا في المحفظة المحددة بواسطة portfolioId.

الطلب

POST /api/v1/monitoring/loan/borrowers HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>

المتن:

الحقلالنوعمطلوبالقيد
idسلسلة UUIDنعممعرّف المنصة الذي يقدّمه المستدعي.
portfolioIdسلسلة UUIDنعمالمحفظة المالكة؛ يجب أن تكون موجودة في مؤسستك.
externalIdstringنعممن 1 إلى 255 حرفًا؛ فريد لكل (portfolio, externalId) بالنسبة إلى الصفوف الحية.
namestring | nullلاالاسم الكامل للمقترض. يُحفظ خامًا؛ وتُخفيه القراءات الموجّهة للمستثمرين.
emailstring | nullلابريد إلكتروني وفق RFC 5322؛ يُحفظ خامًا؛ وتُخفيه القراءات الموجّهة للمستثمرين.
phonestring | nullلارقم هاتف بصيغة حرة؛ يُحفظ خامًا؛ وتُخفيه القراءات الموجّهة للمستثمرين.
nationalIdLast4string | nullلاأربعة أرقام بالضبط؛ ولا تُرجَع الأرقام الأولى أبدًا.
countryCodestring | nullلارمز ISO-3166 من حرفين (بأحرف كبيرة).
dobسلسلة تاريخ | nullلاYYYY-MM-DD.
genderenum | nullلاmale | female | non_binary | other | undisclosed (غير حساس لحالة الأحرف).
incomeBandstring | nullلاصيغة حرة.
employmentStatusstring | nullلاصيغة حرة.
metadataobject | nullلاتمرير حرفي.

الاستجابات

201 Created عند الكتابة الجديدة، و200 OK عند إعادة التشغيل المتكررة دون أثر:

{
  "id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
  "externalId": "BORROWER-001",
  "bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
  "reused": false
}
الحالةالغلافالمُسبِّب
200 OK{ id, externalId, bronzeSubmissionId, reused: true }طابقت Idempotency-Key طلبًا سابقًا؛ لا كتابة جديدة.
201 Created{ id, externalId, bronzeSubmissionId, reused: false }أُدرج صف جديد.
400 Bad RequestfieldErrorsفشل التحقق في أي حقل من حقول المتن.
404 Not Found{ error, code: "PORTFOLIO_NOT_FOUND" }portfolioId غير موجود أو ينتمي إلى مؤسسة أخرى.
409 Conflict{ error, code: "ID_CONFLICT", fieldErrors: [...] }يوجد بالفعل مقترض حي بالقيمة نفسها لـ id.

cURL

curl -X POST https://app.waafir.io/api/v1/monitoring/loan/borrowers \
  -H "Authorization: Bearer $WAAFIR_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" \
  -d '{
    "id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
    "portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
    "externalId": "BORROWER-001",
    "gender": "female",
    "countryCode": "KE"
  }'

GET /api/v1/monitoring/loan/borrowers/{id}

يقرأ مقترضًا بواسطة UUID المنصة. تُخفى حقول المعلومات الشخصية افتراضيًا؛ ويمكن للمسؤولين طلب المعلومات الشخصية الخام بواسطة ?unmask=true، وهو ما يكتب مدخلًا في سجل التدقيق.

الطلب

المعاملالموضعمطلوبالقيد
idpathنعمUUID المنصة الخاص بالمقترض.
unmaskqueryلاtrue يُرجع المعلومات الشخصية الخام؛ للمسؤولين فقط. الإخفاء هو الافتراضي.

الاستجابات

200 OK مع سجل المقترض بعد الإخفاء:

{
  "id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
  "portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
  "externalId": "BORROWER-001",
  "name": "J***",
  "email": "j***@example.com",
  "phone": "***-***-1234",
  "nationalIdLast4": "1234",
  "countryCode": "KE",
  "dob": "1985-03-20",
  "gender": "female",
  "incomeBand": null,
  "employmentStatus": null,
  "metadata": {}
}
الحالةالمُسبِّب
200 OKالصف موجود في مؤسستك. تكون المعلومات الشخصية خامًا إذا كان المستدعي مسؤولًا وأُرسل أيضًا ?unmask=true؛ وإلا فهي مُخفاة.
400 Bad Requestid ليس UUID سليم الصيغة.
404 Not Foundالصف غير موجود، أو ملغى، أو ينتمي إلى مؤسسة أخرى.

ينطبق إخفاء المعلومات الشخصية على name وemail وphone وnationalIdLast4. لا يخزّن الحقل nationalIdLast4 أصلًا إلا آخر أربعة أرقام وقت الكتابة؛ ومع ذلك يُخفيها الإخفاء عند القراءة عن القراءات غير الإدارية.

المستدعي غير المسؤول الذي يمرّر ?unmask=true لا يتلقى 403 — بل تبقى الاستجابة 200 بالشكل المُخفى، ويُكتب في سجل التدقيق مدخل لمحاولة رفع الإخفاء المرفوضة. لا تُظهر المنصة فحص الدور كخطأ لأن الشكل المُخفى هو الافتراض الآمن؛ وسجل التدقيق هو ما يجعل المحاولة مرئية لفريق الأمن.

المستدعي المسؤول الذي يمرّر ?unmask=true يتلقى المعلومات الشخصية الخام، ويكتب الطلب مدخلًا منفصلًا في سجل التدقيق يسجّل رفع الإخفاء. وتحمل الاستجابة Cache-Control: private, no-store لمنع الوسطاء من تخزين حمولة المعلومات الشخصية الخام مؤقتًا.

POST /api/v1/monitoring/loan/loans

ينشئ قرضًا لمقترض موجود في المحفظة نفسها.

الطلب

الحقلالنوعمطلوبالقيد
idسلسلة UUIDنعممعرّف المنصة الذي يقدّمه المستدعي.
portfolioIdسلسلة UUIDنعمالمحفظة المالكة.
borrowerIdسلسلة UUIDنعممقترض حي في المحفظة نفسها.
externalIdstringنعممن 1 إلى 255 حرفًا؛ فريد لكل محفظة بالنسبة إلى الصفوف الحية.
predecessorLoanIdسلسلة UUID | nullلايُضبط عند إعادة الهيكلة؛ ويشير إلى القرض الذي يجري استبداله.
principalAmountسلسلة عشريةنعمحتى أربعة أرقام بعد الفاصلة.
currencyCodestringنعمرمز ISO-4217 من ثلاثة أحرف؛ غير حساس لحالة الأحرف.
interestRateAprسلسلة عشريةنعمحتى ستة أرقام بعد الفاصلة؛ يجب أن يكون >= 0.
disbursementDateسلسلة تاريخنعمYYYY-MM-DD.
termMonthsintegerنعميجب أن يكون > 0.
repaymentFrequencyenumنعمmonthly | weekly | biweekly | quarterly | bullet (غير حساس لحالة الأحرف).
productTypestring | nullلاصيغة حرة، مثل "Term loan" أو "Overdraft".
statusenumنعمpending | active | paid_off | restructured | written_off | defaulted (غير حساس لحالة الأحرف).
metadataobject | nullلاتمرير حرفي.

الاستجابات

201 Created (أو 200 OK عند إعادة التشغيل المتكررة دون أثر) مع { id, externalId, bronzeSubmissionId, reused }.

الحالةالغلافالمُسبِّب
200 OK{ ..., reused: true }إعادة تشغيل متكررة دون أثر.
201 Created{ ..., reused: false }أُدرج قرض جديد.
400 Bad RequestfieldErrorsفشل التحقق (مثل قيمة سالبة لـ interestRateApr، أو currencyCode بصيغة غير سليمة).
404 Not Found{ error, code: "PORTFOLIO_NOT_FOUND" }المحفظة غير موجودة أو تابعة لمؤسسة أخرى.
409 Conflict{ error, code: "ID_CONFLICT" }يوجد بالفعل قرض حي بالقيمة نفسها لـ id.
422 Unprocessable Entity{ error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "borrowerId", ... }] }borrowerId لا يشير إلى مقترض حي في المحفظة نفسها.

cURL

curl -X POST https://app.waafir.io/api/v1/monitoring/loan/loans \
  -H "Authorization: Bearer $WAAFIR_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
    "borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
    "externalId": "LOAN-001",
    "principalAmount": "10000.00",
    "currencyCode": "USD",
    "interestRateApr": "0.18",
    "disbursementDate": "2026-01-15",
    "termMonths": 12,
    "repaymentFrequency": "monthly",
    "status": "active"
  }'

POST /api/v1/monitoring/loan/payments

يسجّل دفعة فعلية لقرض موجود. استخدمه للدفعات المستلمة والدفعات الجزئية والشطب. أما إعادات الهيكلة فتُمثَّل كقرض جديد مع ضبط predecessorLoanId، لا كدفعة.

الطلب

الحقلالنوعمطلوبالقيد
idسلسلة UUIDنعممعرّف المنصة الذي يقدّمه المستدعي.
portfolioIdسلسلة UUIDنعمالمحفظة المالكة.
loanIdسلسلة UUIDنعمقرض حي في المحفظة نفسها.
externalIdstringنعممن 1 إلى 255 حرفًا؛ فريد لكل محفظة بالنسبة إلى الصفوف الحية.
paymentDateسلسلة تاريخنعمYYYY-MM-DD.
amountسلسلة عشريةنعمإجمالي الدفعة المستلمة.
currencyCodestringنعمISO-4217.
principalPaidسلسلة عشريةلاالقيمة الافتراضية "0".
interestPaidسلسلة عشريةلاالقيمة الافتراضية "0".
feesPaidسلسلة عشريةلاالقيمة الافتراضية "0".
writeOffAmountسلسلة عشريةلاالقيمة الافتراضية "0". راجع قاعدة الإعفاء أدناه.
paymentNotesstring | nullلايجب أن يساوي "Forgiven" (غير حساس لحالة الأحرف) عندما يكون writeOffAmount > 0.
paymentMethodenum | nullلاcash | bank_transfer | card | mobile_money | check | other.
metadataobject | nullلاتمرير حرفي.

قاعدة الإعفاء. إذا كان writeOffAmount > 0، فيجب أن يساوي paymentNotes القيمة "Forgiven" دون مراعاة حالة الأحرف. تُفشل المنصة الطلب عند حدود API بحيث تُرفض الدفعة الخاطئة قبل تسجيل أي شيء.

الاستجابات

201 Created (أو 200 OK عند إعادة التشغيل المتكررة دون أثر) مع { id, externalId, bronzeSubmissionId, reused }.

الحالةالغلافالمُسبِّب
200 OK{ ..., reused: true }إعادة تشغيل متكررة دون أثر.
201 Created{ ..., reused: false }أُدرجت دفعة جديدة.
400 Bad RequestfieldErrorsفشل التحقق (مبالغ بصيغة غير سليمة، أو قيمة تعداد غير مطابقة، أو حقل مطلوب مفقود).
404 Not Found{ error, code: "PORTFOLIO_NOT_FOUND" }المحفظة غير موجودة أو تابعة لمؤسسة أخرى.
409 Conflict{ error, code: "ID_CONFLICT" }توجد بالفعل دفعة حية بالقيمة نفسها لـ id.
422 Unprocessable Entity{ error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "loanId", ... }] }loanId لا يشير إلى قرض حي في المحفظة نفسها.
400 Bad Request{ error, code: "CHECK_VIOLATION", fieldErrors: [...] }رُفضت قاعدة الإعفاء عند تخزين الدفعة (نادر؛ إذ يرفض التحقق الشكل نفسه أولًا).

GET /api/v1/monitoring/loan/payments/{id}

يقرأ دفعة فعلية بواسطة UUID المنصة، بما في ذلك الصفوف الملغاة (المحذوفة منطقيًا). استخدمه للتحقق من عملية كتابة أو لفحص سجل ملغى.

الطلب

المعاملالموضعمطلوبالقيد
idpathنعمUUID المنصة الخاص بالدفعة.

الاستجابات

200 OK مع سجل الدفعة الكامل. تظهر الصفوف الملغاة مع تعبئة deletedAt؛ أما الصفوف الحية فتحمل deletedAt: null. و404 Not Found عند المؤسسة الأخرى أو UUID المجهول. و400 Bad Request إذا لم يكن id UUID سليم الصيغة.

PATCH /api/v1/monitoring/loan/loans/{loanRef}/status

ينقل قرضًا إلى حالة جديدة. يقبل مقطع المسار {loanRef} إما UUID المنصة الخاص بالقرض أو externalId الخاص به. عند تمرير externalId، يجب عليك أيضًا تقديم ?portfolioId=<UUID> لأن المعرّفات الخارجية ليست فريدة عبر المحافظ.

الطلب

PATCH /api/v1/monitoring/loan/loans/LOAN-001/status?portfolioId=ddf63d12-1234-5678-9abc-def012345678 HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>

المتن:

الحقلالنوعمطلوبالقيد
statusenumنعمواحدة من active | paid_off | defaulted | written_off | restructured (غير حساس لحالة الأحرف).
effectiveDateسلسلة تاريخنعمYYYY-MM-DD.
reasonstring | nullلامن 1 إلى 500 حرف؛ يُسجَّل في سجل التدقيق.

مصفوفة انتقالات الحالة

تفرض المنصة مصفوفة انتقالات؛ ويُرجع الانتقال غير الصالح 422 INVALID_STATUS_TRANSITION مع fieldErrors تسمّي حالتَي المصدر والوجهة.

منالوجهات المسموح بها
pendingactive
activepaid_off، defaulted، written_off، restructured
paid_off(نهائية)
defaultedwritten_off، restructured
written_off(نهائية)
restructured(نهائية)

عند نقل قرض إلى restructured، فإن الخطوة الطبيعية التالية هي POST /loans للقرض البديل مع ضبط predecessorLoanId. عمليتا الكتابة ليستا ذريتين عن قصد — فإذا فشل طلب POST للقرض البديل، يبقى القرض السابق في restructured وستُظهر واجهة المطابقة الانحراف في المرة التالية التي تستعلم فيها.

الاستجابات

200 OK عند النجاح:

{
  "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "externalId": "LOAN-001",
  "status": "restructured",
  "bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
  "reused": false
}
الحالةالغلافالمُسبِّب
200 OK{ id, externalId, status, bronzeSubmissionId, reused }طُبّق الانتقال (أو إعادة تشغيل متكررة دون أثر مع reused: true).
400 Bad RequestfieldErrorsفشل التحقق من المتن، أو غياب portfolioId عند البحث بواسطة externalId، أو قيمة تعداد بصيغة غير سليمة.
404 Not Found{ error, code: "NOT_FOUND" }لم يُعثر على القرض بواسطة UUID، أو لا يشير (portfolioId, externalId) إلى قرض.
422 Unprocessable Entity{ error, code: "INVALID_STATUS_TRANSITION", fieldErrors: [...] }زوج المصدر/الوجهة غير موجود في مصفوفة الانتقالات؛ ويسرد fieldErrors[].message الوجهات المسموح بها.
409 Conflict{ error, code: "IDEMPOTENCY_CONFLICT" }سبق استخدام Idempotency-Key لانتقال مختلف. تبقى الكتابة السابقة سارية؛ أرسل الانتقال الجديد بمفتاح جديد.

يُسجَّل effectiveDate الذي تقدّمه مع الإرسال وفي سجل التدقيق؛ ولا يظهر في متن الاستجابة. ولا يُقبل metadata في هذا المسار عن قصد — فالانتقال نفسه هو حدث التدقيق، ويحمل الحقل الاختياري reason السياق المقروء للبشر.

POST /api/v1/monitoring/loan/payments/{id}/cancel

يحذف دفعة مسجّلة سابقًا حذفًا منطقيًا. نقطة نهاية الإلغاء هي واجهة العكس الوحيدة في نطاق القروض — فلا يوجد PATCH /loans/{id}/adjust ولن يوجد.

الطلب

POST /api/v1/monitoring/loan/payments/7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/cancel HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json

المتن (اختياري):

الحقلالنوعمطلوبالقيد
reasonstring | nullلامن 1 إلى 500 حرف؛ يُسجَّل في حدث تدقيق الإلغاء.

يُقبل المتن الفارغ؛ ويمكنك حذف ترويسة Content-Type تمامًا.

الاستجابات

200 OK عند النجاح:

{
  "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "deletedAt": "2026-03-15T11:02:33Z",
  "bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
  "reused": false,
  "alreadyCancelled": false
}

عند الاستدعاء الثاني للدفعة نفسها، يكون شكل الاستجابة مطابقًا باستثناء alreadyCancelled: true، ويكون deletedAt هو الطابع الزمني للإلغاء الأصلي. تتتبّع العلامة reused حالة عدم التكرار، بينما تعكس alreadyCancelled ما إذا كان الصف قد عُدّل بهذا الاستدعاء.

الحالةالغلافالمُسبِّب
200 OK{ id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled }إلغاء أول أو لاحق.
400 Bad RequestfieldErrorsid ليس UUID سليم الصيغة، أو reason يتجاوز 500 حرف.
404 Not Found{ error, code: "NOT_FOUND" }الدفعة غير موجودة أو تنتمي إلى مؤسسة أخرى.

يُكتب سجل إرسال عند كل إلغاء — بما في ذلك الإلغاء الثاني — لاكتمال التدقيق. ولا يُعدَّل الصف إلا عند الاستدعاء الأول.

الحذف المنطقي وإعادة استخدام externalId

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

  1. POST /api/v1/monitoring/loan/payments/{id}/cancel على الصف الأصلي.
  2. POST /api/v1/monitoring/loan/payments لصف جديد بالحقول المصحَّحة. يمكنك إعادة استخدام externalId نفسه؛ ويجب أن تقدّم id مختلفًا.

هذا مقصود: فالإلغاءات غير مدمّرة (إذ يُحفظ الصف الأصلي لأغراض التدقيق)، وإعادة استخدام externalId تُبقي فضاء معرّفات المستدعي التشغيلية متراصًّا لأغراض المطابقة.