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

مرجع API

هذا القسم هو الدليل المرجعي لواجهة API الخاصة بنطاق القروض في Waafir — واجهة HTTP التي تستخدمها شركات التقنية المالية لبث بيانات المحافظ إلى Waafir من أجل مراقبة المستثمرين. وهو يوثّق كل مسار تحت /api/v1/monitoring/loan/، ومخططات الطلبات والاستجابات، وكل رمز حالة، وعقد تجربة المطوّر المشترك، وأغلفة الأخطاء التي ينبغي أن تتوقعها.

المرجع شامل لكنه ليس سرديًا. إذا كنت تُجري التكامل لأول مرة وتريد وصفة إرشادية متكاملة من البداية إلى النهاية — مع أمثلة متجاورة بلغات cURL وTypeScript وPython — فاقرأ قسم «دليل الوصفات» إلى جانب هذا المرجع؛ فقد صُمّم الاثنان ليُقرآ معًا.

ما الذي تغطيه الواجهة

تعرض واجهة API الخاصة بنطاق القروض أربعة أشكال للاستيعاب إضافةً إلى واجهة للمطابقة:

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

لكل شكل صفحته الخاصة. ويطابق ترتيب الصفحات الترتيب الذي يسلكه معظم المُكاملين: اقرأ النظرة العامة، ثم وضع الاستيعاب الذي تنوي استخدامه أولًا، ثم المطابقة، ثم مرجع الأخطاء.

كيانات نطاق القروض الستة

يعمل كل مسار على واحد أو أكثر من الكيانات التالية. مخططاتها الكاملة موثّقة لكل مسار — وهذه القائمة هي الفهرس:

  • borrower — الشخص الطبيعي أو الاعتباري الذي يحصل على القرض، مع حقول اختيارية للمعلومات الشخصية (PII) تُخفى عند القراءة.
  • loan — اتفاقية القرض نفسها: أصل القرض، والعملة، ومعدل الفائدة السنوي (APR)، والمدة، وتكرار السداد، والحالة.
  • scheduled_repayment — جدول السداد التعاقدي، بصف واحد لكل تاريخ استحقاق.
  • actual_payment — الدفعات الفعلية المستلمة، بما في ذلك الشطب والدفعات الجزئية.
  • collateral — الضمانات المرهونة مقابل قرض.
  • collateral_valuation — تقييمات صف الضمان في نقطة زمنية محددة، مع دعم طرق متعددة.

ينتمي كل كيان إلى محفظة في مؤسستك. تُقدَّم المحفظة مع كل عملية كتابة؛ أما المؤسسة فتأتي من رمز الوصول الشخصي الخاص بك ولا تظهر أبدًا في متن الطلب.

المصادقة في سطر واحد

يحمل كل طلب Authorization: Bearer <PAT> حيث <PAT> رمز وصول شخصي يُصدره مستوى التحكم في Waafir. الرموز محصورة بالمؤسسة — فالرمز الصادر للمؤسسة A لا يستطيع قراءة بيانات المؤسسة B أو الكتابة فيها، وتُرجع القراءات عبر المؤسسات 404 Not Found بدلًا من 403 Forbidden تجنبًا لكشف وجود موارد مستأجر آخر.

نموذج المصادقة والتفويض الكامل مشروح في النظرة العامة.

كيف تستخدم هذا المرجع

اقرأ الصفحات بالترتيب، أو انتقل مباشرة إلى الواجهة التي تحتاجها:

  • نظرة عامة — العقد المشترك الذي يلتزم به كل مسار في نطاق القروض: المصادقة، وضمانات التكامل (المعرّفات التي يقدّمها المستدعي، وعدم التكرار، والتشغيل التجريبي)، وأغلفة الأخطاء، واصطلاحات المبالغ والتواريخ، ودلالات الإلغاء، وكيفية تسجيل كل إرسال.
  • عمليات CRUD للسجل الواحد — كل مسارات POST وGET وPATCH والإلغاء للصف الواحد.
  • NDJSON المجمّع — استيعاب مجمّع متزامن مع إبلاغ عن الأخطاء لكل صف.
  • الاستيرادات غير المتزامنة — دورة الحياة ذات المرحلتين: الرفع، والاستعلام الدوري عن الحالة، وتصفّح الأخطاء صفحةً صفحة.
  • المطابقة — القراءة بواسطة معرّف المستدعي وأعداد الصفوف لكل كيان.
  • الأخطاء ورموز الحالة — الفهرس الموحّد لكل رمز حالة وغلاف خطأ ورمز خطأ مسمّى تُصدره واجهة نطاق القروض.

للأدلة الموجّهة نحو المهام — تهيئة محفظة من البداية إلى النهاية، أو تشغيل مطابقة يومية، أو التعافي من استيراد فشل جزئيًا — راجع قسم «دليل الوصفات» (الذي يُطرح إلى جانب هذا المرجع). يشرح قسم «دليل الوصفات» كل مهمة بثلاث لغات؛ أما هذا المرجع فهو المصدر الموثوق لما يقبله كل مسار وما يُرجعه.

ما الذي لا يتضمنه هذا المرجع

  • التهيئة والرموز — كيفية تسجيل مؤسسة، وإنشاء محفظة، وإصدار رمز وصول شخصي. هذه العمليات مشروحة في وثائق إدارة المنصة وفي وصفة البدء ضمن قسم «دليل الوصفات».
  • التحليلات الموجّهة للمستثمرين — حِزم الرسوم البيانية، وتصدير سجل القروض (tape)، وواجهة تنزيل سجل القروض. تُطرح هذه خلف مسارات منفصلة ولا يغطيها هذا المرجع.
  • Webhooks والتسليم المجدول لسجل القروض — لا يغطيها هذا المرجع.