عمليات 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 | نعم | المحفظة المالكة؛ يجب أن تكون موجودة في مؤسستك. |
externalId | string | نعم | من 1 إلى 255 حرفًا؛ فريد لكل (portfolio, externalId) بالنسبة إلى الصفوف الحية. |
name | string | null | لا | الاسم الكامل للمقترض. يُحفظ خامًا؛ وتُخفيه القراءات الموجّهة للمستثمرين. |
email | string | null | لا | بريد إلكتروني وفق RFC 5322؛ يُحفظ خامًا؛ وتُخفيه القراءات الموجّهة للمستثمرين. |
phone | string | null | لا | رقم هاتف بصيغة حرة؛ يُحفظ خامًا؛ وتُخفيه القراءات الموجّهة للمستثمرين. |
nationalIdLast4 | string | null | لا | أربعة أرقام بالضبط؛ ولا تُرجَع الأرقام الأولى أبدًا. |
countryCode | string | null | لا | رمز ISO-3166 من حرفين (بأحرف كبيرة). |
dob | سلسلة تاريخ | null | لا | YYYY-MM-DD. |
gender | enum | null | لا | male | female | non_binary | other | undisclosed (غير حساس لحالة الأحرف). |
incomeBand | string | null | لا | صيغة حرة. |
employmentStatus | string | null | لا | صيغة حرة. |
metadata | object | 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 Request | fieldErrors | فشل التحقق في أي حقل من حقول المتن. |
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، وهو ما يكتب مدخلًا في سجل التدقيق.
الطلب
| المعامل | الموضع | مطلوب | القيد |
|---|---|---|---|
id | path | نعم | UUID المنصة الخاص بالمقترض. |
unmask | query | لا | 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 Request | id ليس 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 | نعم | مقترض حي في المحفظة نفسها. |
externalId | string | نعم | من 1 إلى 255 حرفًا؛ فريد لكل محفظة بالنسبة إلى الصفوف الحية. |
predecessorLoanId | سلسلة UUID | null | لا | يُضبط عند إعادة الهيكلة؛ ويشير إلى القرض الذي يجري استبداله. |
principalAmount | سلسلة عشرية | نعم | حتى أربعة أرقام بعد الفاصلة. |
currencyCode | string | نعم | رمز ISO-4217 من ثلاثة أحرف؛ غير حساس لحالة الأحرف. |
interestRateApr | سلسلة عشرية | نعم | حتى ستة أرقام بعد الفاصلة؛ يجب أن يكون >= 0. |
disbursementDate | سلسلة تاريخ | نعم | YYYY-MM-DD. |
termMonths | integer | نعم | يجب أن يكون > 0. |
repaymentFrequency | enum | نعم | monthly | weekly | biweekly | quarterly | bullet (غير حساس لحالة الأحرف). |
productType | string | null | لا | صيغة حرة، مثل "Term loan" أو "Overdraft". |
status | enum | نعم | pending | active | paid_off | restructured | written_off | defaulted (غير حساس لحالة الأحرف). |
metadata | object | null | لا | تمرير حرفي. |
الاستجابات
201 Created (أو 200 OK عند إعادة التشغيل المتكررة دون أثر) مع { id, externalId, bronzeSubmissionId, reused }.
| الحالة | الغلاف | المُسبِّب |
|---|---|---|
200 OK | { ..., reused: true } | إعادة تشغيل متكررة دون أثر. |
201 Created | { ..., reused: false } | أُدرج قرض جديد. |
400 Bad Request | fieldErrors | فشل التحقق (مثل قيمة سالبة لـ 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 | نعم | قرض حي في المحفظة نفسها. |
externalId | string | نعم | من 1 إلى 255 حرفًا؛ فريد لكل محفظة بالنسبة إلى الصفوف الحية. |
paymentDate | سلسلة تاريخ | نعم | YYYY-MM-DD. |
amount | سلسلة عشرية | نعم | إجمالي الدفعة المستلمة. |
currencyCode | string | نعم | ISO-4217. |
principalPaid | سلسلة عشرية | لا | القيمة الافتراضية "0". |
interestPaid | سلسلة عشرية | لا | القيمة الافتراضية "0". |
feesPaid | سلسلة عشرية | لا | القيمة الافتراضية "0". |
writeOffAmount | سلسلة عشرية | لا | القيمة الافتراضية "0". راجع قاعدة الإعفاء أدناه. |
paymentNotes | string | null | لا | يجب أن يساوي "Forgiven" (غير حساس لحالة الأحرف) عندما يكون writeOffAmount > 0. |
paymentMethod | enum | null | لا | cash | bank_transfer | card | mobile_money | check | other. |
metadata | object | null | لا | تمرير حرفي. |
قاعدة الإعفاء. إذا كان writeOffAmount > 0، فيجب أن يساوي paymentNotes القيمة "Forgiven" دون مراعاة حالة الأحرف. تُفشل المنصة الطلب عند حدود API بحيث تُرفض الدفعة الخاطئة قبل تسجيل أي شيء.
الاستجابات
201 Created (أو 200 OK عند إعادة التشغيل المتكررة دون أثر) مع { id, externalId, bronzeSubmissionId, reused }.
| الحالة | الغلاف | المُسبِّب |
|---|---|---|
200 OK | { ..., reused: true } | إعادة تشغيل متكررة دون أثر. |
201 Created | { ..., reused: false } | أُدرجت دفعة جديدة. |
400 Bad Request | fieldErrors | فشل التحقق (مبالغ بصيغة غير سليمة، أو قيمة تعداد غير مطابقة، أو حقل مطلوب مفقود). |
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 المنصة، بما في ذلك الصفوف الملغاة (المحذوفة منطقيًا). استخدمه للتحقق من عملية كتابة أو لفحص سجل ملغى.
الطلب
| المعامل | الموضع | مطلوب | القيد |
|---|---|---|---|
id | path | نعم | 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>المتن:
| الحقل | النوع | مطلوب | القيد |
|---|---|---|---|
status | enum | نعم | واحدة من active | paid_off | defaulted | written_off | restructured (غير حساس لحالة الأحرف). |
effectiveDate | سلسلة تاريخ | نعم | YYYY-MM-DD. |
reason | string | null | لا | من 1 إلى 500 حرف؛ يُسجَّل في سجل التدقيق. |
مصفوفة انتقالات الحالة
تفرض المنصة مصفوفة انتقالات؛ ويُرجع الانتقال غير الصالح 422 INVALID_STATUS_TRANSITION مع fieldErrors تسمّي حالتَي المصدر والوجهة.
| من | الوجهات المسموح بها |
|---|---|
pending | active |
active | paid_off، defaulted، written_off، restructured |
paid_off | (نهائية) |
defaulted | written_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 Request | fieldErrors | فشل التحقق من المتن، أو غياب 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المتن (اختياري):
| الحقل | النوع | مطلوب | القيد |
|---|---|---|---|
reason | string | 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 Request | fieldErrors | id ليس UUID سليم الصيغة، أو reason يتجاوز 500 حرف. |
404 Not Found | { error, code: "NOT_FOUND" } | الدفعة غير موجودة أو تنتمي إلى مؤسسة أخرى. |
يُكتب سجل إرسال عند كل إلغاء — بما في ذلك الإلغاء الثاني — لاكتمال التدقيق. ولا يُعدَّل الصف إلا عند الاستدعاء الأول.
الحذف المنطقي وإعادة استخدام externalId
تترك الدفعة الملغاة externalId الخاص بها متاحًا لإعادة الاستخدام في عملية كتابة لاحقة، لأن قيد التفرّد ينطبق على الصفوف الحية فقط. لتصحيح إرسال خاطئ، المسار القياسي هو:
POST /api/v1/monitoring/loan/payments/{id}/cancelعلى الصف الأصلي.POST /api/v1/monitoring/loan/paymentsلصف جديد بالحقول المصحَّحة. يمكنك إعادة استخدامexternalIdنفسه؛ ويجب أن تقدّمidمختلفًا.
هذا مقصود: فالإلغاءات غير مدمّرة (إذ يُحفظ الصف الأصلي لأغراض التدقيق)، وإعادة استخدام externalId تُبقي فضاء معرّفات المستدعي التشغيلية متراصًّا لأغراض المطابقة.