نظرة عامة
تشترك كل نقاط نهاية نطاق القروض في العقد الموضّح في هذه الصفحة. اقرأها أولًا؛ فصفحات كل واجهة تُحيل إليها بدلًا من تكرار مضمونها.
عنوان URL الأساسي والإصدارات
تُركَّب كل مسارات نطاق القروض تحت /api/v1/monitoring/loan/. الرقم الصحيح الذي يلي v هو الإصدار الرئيسي: رفع الإصدار الرئيسي تغيير كاسر لا يحدث إلا بإشعار إيقاف صريح. أما التطور الثانوي ضمن الإصدار الرئيسي نفسه فهو إضافي فقط — حقول اختيارية جديدة، ونقاط نهاية جديدة، وقيم تعداد جديدة — ولا يكسر أبدًا تكاملًا يتجاهل الحقول التي لا يفهمها.
مضيف الإنتاج هو https://app.waafir.io. للحصول على عنوان URL كامل، أضف المضيف قبل أي مسار في موقع المرجع هذا، مثل https://app.waafir.io/api/v1/monitoring/loan/borrowers.
المصادقة
يحمل كل طلب ترويسة Authorization برمز Bearer:
Authorization: Bearer <PAT><PAT> رمز وصول شخصي يُصدَر من مستوى التحكم في Waafir لمؤسسة واحدة. تحدد مؤسسة الرمز نطاق الاستئجار لكل قراءة وكل كتابة — فلا يوجد معامل للمؤسسة في أي عنوان URL أو متن، لأن الرمز يحددها مسبقًا.
تُرجع الطلبات عبر المؤسسات 404 Not Found، لا 403 Forbidden. فإرجاع 403 سيكشف وجود مورد مستأجر آخر بمعرّفه؛ أما نهج 404 فيعامل المعرّفات المجهولة ومعرّفات المستأجرين الآخرين معاملة واحدة.
الطلب الذي يخلو من ترويسة Authorization، أو يحمل رمزًا مجهولًا، أو رمزًا مُلغى، يُرجع 401 Unauthorized.
ضمانات التكامل
يلتزم كل مسار تعديل بالضمانات أدناه. كل ضمان منها شيء يمكن لشيفرة العميل الاعتماد عليه؛ وقراءتها مرة واحدة هنا تتيح لك تنفيذ تكامل متين في مرور واحد.
المعرّفات التي يقدّمها المستدعي
لكل كيان حقل id في متن طلبه تقدّمه أنت بصيغة UUID. لا تخترع المنصة المعرّفات نيابةً عنك أبدًا. وهذا أساس كل عقد آخر في هذه القائمة: فعدم التكرار والمطابقة وإعادة التشغيل تعتمد كلها على قدرتك على الإشارة إلى صف بمعرّف اخترته أنت.
إذا أعدت إرسال صف عبر POST بالقيمة نفسها لـ id، فستتلقى 409 ID_CONFLICT ومدخلًا في fieldErrors يشير إلى id. اختر معرّفاتك بعناية — يُوصى بمعرّفات UUIDv4 مولّدة، لكن أي UUID سليم الصيغة يعمل.
إضافةً إلى id، يحمل كل كيان أيضًا externalId — سلسلة نصية حرة يصل طولها إلى 255 حرفًا تستخدمها للإشارة إلى الصف من نظامك الخاص. يكون externalId فريدًا داخل المحفظة بالنسبة إلى الصفوف الحية، وهذا ما يجعل المطابقة بواسطة معرّف المستدعي ممكنة.
ترويسة Idempotency-Key
يقرأ كل مسار تعديل ترويسة HTTP اختيارية هي Idempotency-Key. عند وجودها، تُزيل المنصة التكرار بالمقارنة مع أرشيف داخلي: الطلب الثاني بالمفتاح نفسه يُرجع الاستجابة نفسها التي أرجعها الأول، حتى لو اختلف المتن قليلًا. وهكذا ينجو العملاء من انقطاعات الشبكة العابرة التي تتركهم غير متأكدين مما إذا كان الطلب قد وصل.
الترويسة غير حساسة لحالة الأحرف أثناء النقل (Idempotency-Key وidempotency-key وIDEMPOTENCY-KEY كلها تعمل). تُعامل القيمة على أنها معتمة — اختر أي قيمة ثابتة لكل عملية منطقية، وعادةً ما تكون UUIDv4 مع مميّز للمسار.
?dryRun=true
يقبل كل مسار تعديل معامل الاستعلام ?dryRun=true. يُجري طلب التشغيل التجريبي فحوص التحقق والاستئجار ويُرجع المُدخل المُتحقَّق منه، لكنه لا يسجّل شيئًا ولا يخزّن أي صف. استخدمه للتأكد من أن المتن يُحلَّل بنجاح قبل أن تُنفّذ كتابة حقيقية.
شكل الاستجابة عند نجاح التشغيل التجريبي هو { "dryRun": true, "validatedInput": <body> } مع 200 OK. أما حالات فشل التحقق أثناء التشغيل التجريبي فتُرجع شكل 400 نفسه الذي تُرجعه الكتابة الحقيقية؛ ولا يختلف إلا الأثر الجانبي.
غلاف التحقق fieldErrors
تُرجع حالات فشل التحقق 400 Bad Request مع غلاف منظَّم:
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}path هو المسار المنقّط إلى الحقل المخالف؛ وmessage شرح مقروء للبشر. الغلاف موحّد في كل المسارات، لذا يستطيع معالج واحد في جانب العميل عرض كل حالات فشل التحقق بطريقة متسقة.
تعدادات غير حساسة لحالة الأحرف مع تلميحات "هل تقصد"
تقبل تعدادات النطاق (حالة القرض، وطريقة الدفع، وتكرار السداد، ورمز العملة، وغيرها) أي حالة أحرف أثناء النقل. وتُوحّد المنصة القيمة إلى الصيغة القياسية بالأحرف الصغيرة قبل حفظها.
القيمة غير المطابقة تُرجع 400 مع مدخل في fieldErrors يسمّي القيمة المخالفة ويقترح أقرب قيمة مقبولة:
{
"error": "Validation failed",
"fieldErrors": [
{
"path": "status",
"message": "got 'restruktured', did you mean 'restructured'?"
}
]
}يُحسب الاقتراح بمقياس صغير لمسافة التحرير، لذا تُكتشف الأحرف المتبادلة المواضع والأخطاء الطباعية المنفردة بشكل موثوق.
تمرير metadata من نوع JSONB
يقبل كل كيان حقلًا اختياريًا metadata من نوع object. تحفظ المنصة الكائن حرفيًا — فلا تُحذف أي مفاتيح ولا تُحوَّل أي قيم. استخدمه لإرفاق سياق من جانب العميل لا تحتاج المنصة نفسها إلى فهمه: معرّفك الداخلي، أو النظام المصدر، أو الطابع الزمني للاستخراج، أو رمز حملة.
هناك واجهتان لا تقبلان metadata: مسار انتقال حالة القرض ومسارات إلغاء الدفعات. والمبرر موثّق ضمن تلك المسارات.
المطابقة بواسطة معرّف المستدعي
يمكن الإشارة إلى كل كيان بواسطة externalId الذي أرسلته، ضمن نطاق محفظة. تستخدم واجهة المطابقة — GET /loans/{externalId} وGET /counts — ذلك لتتيح لك التحقق من عمليات الكتابة دون الحاجة إلى UUID الذي تعيّنه المنصة. راجع صفحة المطابقة لمعرفة الأشكال بدقة.
تمثيل المبالغ المالية
القيم المالية بصيغة النقل هي سلاسل نصية من أرقام عشرية، بما يصل إلى أربعة أرقام عشرية بعد الفاصلة. يُرفض النوع number في JavaScript لأن الأعداد العشرية الثنائية وفق IEEE-754 لا تستطيع تمثيل السنتات العشرية بدقة:
{ "amount": "100.50", "currencyCode": "USD" }القيمة العشرية التي تحتوي على أكثر من أربعة أرقام بعد الفاصلة، أو القيمة التي تحتوي على أحرف غير الأرقام وعلامة سالب في البداية ونقطة واحدة، تُرجع 400 مع مدخل في fieldErrors. وتُرفض السلاسل الفارغة.
رموز العملات هي رموز ISO-4217 المكوّنة من ثلاثة أحرف. تتعرّف المنصة صراحةً على المجموعة الشائعة؛ أما الرموز المجهولة المطابقة لشكل ثلاثة أحرف كبيرة فتُقبل وتُحفظ حرفيًا كي لا تُحجب رموز الأسواق غير المألوفة.
صيغة التاريخ
التواريخ بصيغة النقل هي سلاسل تقويمية وفق ISO-8601 بالشكل YYYY-MM-DD:
{ "disbursementDate": "2026-01-15" }لا يوجد مكوّن للمنطقة الزمنية. التواريخ تواريخ تقويمية وفق تفسير المحفظة؛ ولا تُجري المنصة أي تحويل.
دلالات الإلغاء
لا تمحو استدعاءات API أي صف أبدًا. بل يُعلَّم الصف بأنه ملغى عند الإلغاء أو أي عكس آخر. والنتائج المترتبة على ذلك:
- لا يُحرَّر
externalIdبالإلغاء. يكونexternalIdفريدًا داخل المحفظة بين الصفوف الحية فقط. والصف الملغى لم يعد حيًا، لذا يمكنك إعادة استخدامexternalIdالخاص به لإعادة إرسال مصحَّحة. - لا تُرجع قراءات المطابقة الصفوف الملغاة افتراضيًا. تستبعد واجهتا
GET /loans/{externalId}وGET /countsالصفوف المحذوفة منطقيًا من استجابتهما الافتراضية. - تُحفظ سجلات الإرسال في كل الأحوال. حتى عند إلغاء صف، يبقى سجل الإرسال الذي أنشأه سليمًا لأغراض التدقيق.
كل إرسال يُسجَّل
تسجّل كل عملية تعديل ناجحة متن الطلب الخام قبل كتابة الصف. والنتائج المترتبة على تكاملك:
- يعني
200/201أن إرسالك قد سُجّل بشكل دائم حتى لو أشّرت عليه المعالجة اللاحقة لاحقًا. يبدأ سجل التدقيق الخاص بك لحظة إقرار المنصة بالطلب. - حتى
409 ID_CONFLICTيُؤرشَف. يحتفظ سجل الإرسال بكلٍّ من التعارض والإرسال الذي جرت محاولته، لتتمكن من التحقيق لاحقًا دون أي التباس بشأن ما أُرسل. - تُسجَّل الاستيرادات غير المتزامنة عند الالتزام. ملف NDJSON المرفوع والاستيراد نفسه هما السجل؛ ولا يوجد سجل منفصل لكل صف في الاستيراد غير المتزامن.
لا يمكن تغيير سجل الإرسال. ولا تقرؤه مباشرةً عبر واجهة API العامة أبدًا، لكنه سبب كون واجهة المطابقة موثوقة — فلكل صف يظهر هناك مدخل أرشيف مقابل خلفه.
كيف نُظّم بقية هذا المرجع
توثّق كل صفحة لاحقة في موقع المرجع هذا شكلًا واحدًا من أشكال الاستيعاب أو واجهة المطابقة. وتتبع كل صفحة مسار البنية نفسها: غاية في جملة واحدة، وشكل الطلب (الترويسات والاستعلام والمتن)، وشكل الاستجابة لكل رمز حالة، واستدعاء cURL مختصر. تُعرض قيود كل حقل في جداول يسهل تصفّحها؛ أما الأمثلة المعمّقة وعيّنات الشيفرة بثلاث لغات فموجودة في قسم «دليل الوصفات».
صفحة الأخطاء ورموز الحالة هي المرجع الموحّد لأغلفة الاستجابة التي يستخدمها كل مسار في هذا الموقع. اقرأها مرة قبل التكامل؛ وعُد إليها كلما فاجأتك حالة غير 200.