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

المطابقة

تتيح لك واجهة المطابقة التحقق مما وصل إلى 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 الذي أرسلته. ويستبعد الصفوف الملغاة (المحذوفة منطقيًا).

الطلب

المعاملالموضعمطلوبالقيد
externalIdpathنعممن 1 إلى 255 حرفًا؛ رمّز بالنسبة المئوية أي أحرف غير آمنة في عناوين URL.
portfolioIdqueryنعم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 RequestportfolioId مفقود أو بصيغة غير سليمة، أو يحتوي 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

يقرأ أعداد الصفوف لكل كيان، مع إمكانية التضييق حسب المحفظة أو التاريخ أو إلى كيان واحد. وتُستبعد الصفوف المحذوفة منطقيًا.

الطلب

المعاملالموضعمطلوبالقيد
portfolioIdqueryلاUUID؛ يضيّق النطاق إلى محفظة واحدة. احذفه للحصول على تجميع على مستوى المؤسسة.
datequeryلاYYYY-MM-DD؛ عند تقديمه، تتضمن الاستجابة عدد onDate لكل كيان.
entityqueryلاواحد من 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 RequestportfolioId أو 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"

مطابقة يومية نموذجية

بمجرد إكمال إرسالات اليوم، يكون تدفق المطابقة القياسي كما يلي:

  1. استدعِ GET /counts?date=<today> مع محفظتك. قارن عدد onDate لكل كيان بما أرسلته اليوم. إذا طابقت الأعداد ما أرسلته، فقد وصلت دفعتك سليمة.
  2. عند أي عدم تطابق، ابحث عن الصفوف المحددة بواسطة GET /loans/{externalId}. عمليات البحث هذه زهيدة التكلفة — فحص فهرس واحد لكل منها — وتُرجع الحالة القياسية للصف بما في ذلك UUID الذي عيّنته المنصة، والذي يمكنك استخدامه بعد ذلك لمزيد من التحقيق.
  3. للتحقيق على مستوى الصف، فإن نقاط نهاية GET للسجل الواحد ونقطة نهاية الأخطاء المقسّمة إلى صفحات في الاستيرادات غير المتزامنة هي الواجهات التي تُظهر تفاصيل الفشل لكل صف.

واجهة المطابقة للقراءة فقط عن قصد وزهيدة التكلفة — فهي نبض التكامل، لا واجهة للتحميل. استدعِها مرة أو مرتين يوميًا لكل محفظة؛ لا يوجد حد معدّل خاص بها، لكن يُرجى عدم الاستعلام عنها دوريًا ضمن حلقة متلاحقة.