المطابقة
تتيح لك واجهة المطابقة التحقق مما وصل إلى Waafir باستخدام معرّفات المستدعي الخاصة بك بدلًا من معرّفات UUID التي تعيّنها المنصة. وهي مقتضبة عن قصد — مساران فقط — لكنها العمود الفقري التشغيلي لأي تكامل متين: فكل استيعاب يومي سليم ينتهي باستدعاء للمطابقة.
لماذا المطابقة بواسطة معرّف المستدعي
عندما ترسل قرضًا مع externalId: "L-001"، يكون نظامك قد عرف الصف بهذا الاسم مسبقًا. وسؤال المنصة "هل لديك L-001؟" هو الخطوة الطبيعية التالية — وعدم الحاجة إلى التحويل إلى UUID المنصة أولًا يعني أن منطق المطابقة لديك يمكن أن يعمل على المعرّفات نفسها التي تستخدمها دفاترك المحاسبية.
تضمن المنصة أن يكون externalId فريدًا داخل المحفظة بالنسبة إلى الصفوف الحية، وهذا ما يجعل البحث بواسطة externalId قراءة لصف واحد.
المسارات
| الطريقة | المسار | الغرض |
|---|---|---|
GET | /api/v1/monitoring/loan/loans/{externalId}?portfolioId=<UUID> | قراءة قرض واحد بواسطة معرّف المستدعي. |
GET | /api/v1/monitoring/loan/counts | قراءة إجماليات الصفوف لكل كيان، مع إمكانية التضييق حسب المحفظة أو التاريخ أو الكيان. |
GET /api/v1/monitoring/loan/loans/{externalId}
يقرأ قرضًا واحدًا بواسطة externalId الذي أرسلته. ويستبعد الصفوف الملغاة (المحذوفة منطقيًا).
الطلب
| المعامل | الموضع | مطلوب | القيد |
|---|---|---|---|
externalId | path | نعم | من 1 إلى 255 حرفًا؛ رمّز بالنسبة المئوية أي أحرف غير آمنة في عناوين URL. |
portfolioId | query | نعم | UUID المحفظة التي تملك القرض. |
portfolioId مطلوب لأن externalId ليس فريدًا عبر المحافظ — فهو فريد داخل المحفظة فقط.
الاستجابة — 200 OK
{
"loan": {
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "L-001",
"predecessorLoanId": null,
"principalAmount": "10000.0000",
"currencyCode": "USD",
"interestRateApr": "0.180000",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"productType": "Term loan",
"status": "active",
"metadata": {},
"createdAt": "2026-01-15T08:00:00Z",
"updatedAt": "2026-01-15T08:00:00Z"
},
"borrower": {
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "B-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null
}
}تتضمن الاستجابة مقترض القرض مع إخفاء المعلومات الشخصية. هذا هو العرض بنطاق المستثمر — الإخفاء نفسه المطبّق على نقطة نهاية قراءة المقترض. يتيح لك الإخفاء التأكد من أن "هذا القرض مرتبط بالمقترض الصحيح" دون كشف المعلومات الشخصية للنظام المستدعي. أما المسؤولون الذين يحتاجون إلى المعلومات الشخصية الخام فيمرّون عبر واجهة المقترض بواسطة UUID مع ?unmask=true وتسجيل في سجل التدقيق.
تظهر الحقول المالية بكامل الدقة المخزّنة (أربعة أرقام بعد الفاصلة للمبالغ المالية؛ وستة لـ interestRateApr)؛ وينبغي أن يعاملها عميلك كسلاسل عشرية معتمة بدلًا من تحليلها إلى أعداد عشرية عائمة.
رموز الحالة
| الحالة | المُسبِّب |
|---|---|
200 OK | عُثر على القرض في مؤسستك. |
400 Bad Request | portfolioId مفقود أو بصيغة غير سليمة، أو يحتوي externalId على ترميز بالنسبة المئوية غير سليم. |
404 Not Found | القرض غير موجود كصف حي في المحفظة المقدَّمة، أو المحفظة تنتمي إلى مؤسسة أخرى. |
cURL
curl https://app.waafir.io/api/v1/monitoring/loan/loans/L-001?portfolioId=ddf63d12-1234-5678-9abc-def012345678 \
-H "Authorization: Bearer $WAAFIR_PAT"GET /api/v1/monitoring/loan/counts
يقرأ أعداد الصفوف لكل كيان، مع إمكانية التضييق حسب المحفظة أو التاريخ أو إلى كيان واحد. وتُستبعد الصفوف المحذوفة منطقيًا.
الطلب
| المعامل | الموضع | مطلوب | القيد |
|---|---|---|---|
portfolioId | query | لا | UUID؛ يضيّق النطاق إلى محفظة واحدة. احذفه للحصول على تجميع على مستوى المؤسسة. |
date | query | لا | YYYY-MM-DD؛ عند تقديمه، تتضمن الاستجابة عدد onDate لكل كيان. |
entity | query | لا | واحد من borrowers، loans، scheduled_repayments، actual_payments، collateral، collateral_valuations (غير حساس لحالة الأحرف). عند تقديمه، لا يُرجَع إلا ذلك الكيان. |
الاستجابة — 200 OK
التجميع الافتراضي، لكل الكيانات الستة:
{
"counts": {
"borrowers": { "total": 1200 },
"loans": { "total": 3450 },
"scheduled_repayments": { "total": 41400 },
"actual_payments": { "total": 32118 },
"collateral": { "total": 600 },
"collateral_valuations": { "total": 1840 }
},
"date": null,
"portfolioId": null
}مع ?date=2026-05-22، يكتسب كل كيان عدد onDate للصفوف التي أُنشئت في التاريخ المقدَّم:
{
"counts": {
"borrowers": { "total": 1200, "onDate": 0 },
"loans": { "total": 3450, "onDate": 12 },
"scheduled_repayments": { "total": 41400, "onDate": 144 },
"actual_payments": { "total": 32118, "onDate": 1207 },
"collateral": { "total": 600, "onDate": 0 },
"collateral_valuations": { "total": 1840, "onDate": 0 }
},
"date": "2026-05-22",
"portfolioId": null
}مع ?entity=loans، لا يظهر إلا مدخل loans.
رموز الحالة
| الحالة | المُسبِّب |
|---|---|
200 OK | حُلّل الاستعلام؛ وأُرجعت الأعداد. |
400 Bad Request | portfolioId أو date أو entity بصيغة غير سليمة. |
لا يُرجع portfolioId غير الموجود أو التابع لمؤسسة أخرى 404؛ بل يُرجع 200 بأصفار في كل الخانات. وهذا مقصود — فواجهة الأعداد قراءة لبياناتك أنت، والمحفظة المجهولة لا تختلف وظيفيًا عن محفظة خالية من الصفوف.
cURL
# Full daily reconciliation for one portfolio:
curl "https://app.waafir.io/api/v1/monitoring/loan/counts?portfolioId=ddf63d12-1234-5678-9abc-def012345678&date=2026-05-22" \
-H "Authorization: Bearer $WAAFIR_PAT"مطابقة يومية نموذجية
بمجرد إكمال إرسالات اليوم، يكون تدفق المطابقة القياسي كما يلي:
- استدعِ
GET /counts?date=<today>مع محفظتك. قارن عددonDateلكل كيان بما أرسلته اليوم. إذا طابقت الأعداد ما أرسلته، فقد وصلت دفعتك سليمة. - عند أي عدم تطابق، ابحث عن الصفوف المحددة بواسطة
GET /loans/{externalId}. عمليات البحث هذه زهيدة التكلفة — فحص فهرس واحد لكل منها — وتُرجع الحالة القياسية للصف بما في ذلك UUID الذي عيّنته المنصة، والذي يمكنك استخدامه بعد ذلك لمزيد من التحقيق. - للتحقيق على مستوى الصف، فإن نقاط نهاية GET للسجل الواحد ونقطة نهاية الأخطاء المقسّمة إلى صفحات في الاستيرادات غير المتزامنة هي الواجهات التي تُظهر تفاصيل الفشل لكل صف.
واجهة المطابقة للقراءة فقط عن قصد وزهيدة التكلفة — فهي نبض التكامل، لا واجهة للتحميل. استدعِها مرة أو مرتين يوميًا لكل محفظة؛ لا يوجد حد معدّل خاص بها، لكن يُرجى عدم الاستعلام عنها دوريًا ضمن حلقة متلاحقة.