دليل الوصفات
دليل الوصفات هذا موجّه لمهندسي شركات التقنية المالية الذين يربطون محفظة قروضهم بواجهة برمجة المراقبة (monitoring API) في Waafir. تشرح كل وصفة مهمة واحدة من البداية إلى النهاية باستخدام عملاء المرجع الثلاثة كلهم — cURL وTypeScript وPython — حتى لا يضطر القارئ إلى الترجمة ذهنيًا بين اللغات. وتميل الوصفات إلى مسارات الإخفاق والحالات الحدّية التي يواجهها أي تكامل حقيقي، لا إلى المسار السعيد وحده.
لمن هذا الدليل
لقد أصدر لك مسؤول مؤسستك في Waafir رمز وصول شخصيًا (PAT)، وأنت تكتب الشيفرة التي ترسل بيانات شريط القروض اليومية — المقترضين، والقروض، والأقساط المجدولة، والمدفوعات الفعلية، والضمانات، وتقييمات الضمانات — إلى Waafir. تُسجَّل كل عملية إرسال كما أُرسلت، ثم تُخزَّن صفوفًا؛ ومن هناك تغذّي تبويب مراقبة المستثمرين في أي غرفة بيانات مرتبطة بالمحفظة.
كيفية استخدام هذه الوصفات
لكل وصفة البنية نفسها: مقدمة نثرية قصيرة، وثلاث كتل شيفرة مسوّرة بترتيب ثابت، وفقرة تحقق موجزة. وكتل الشيفرة هي:
- cURL — انسخها والصقها في الطرفية. وهي الأقل تقييدًا؛ ومفيدة للاستكشافات العابرة وفحوصات CI.
- TypeScript — قائمة على
fetchوفق عقود JSON العامة. لا يلزم تثبيت أي SDK. - Python — قائمة على
requestsوفق عقود JSON نفسها. تكفي المكتبة القياسية؛ ولا يلزم أي حزمة خاصة بـ Waafir.
المصادقة
تتطلب جميع نقاط النهاية رمز PAT في ترويسة Authorization:
Authorization: Bearer <YOUR_PAT>يقتصر نطاق رمز PAT على مؤسسة واحدة في Waafir ويحمل هوية تلك المؤسسة في كل طلب. تعامل معه كسرّ؛ ودوّره من لوحة التحكم إذا تسرّب. عنوان URL الأساسي للواجهة في هذه الوصفات كلها هو https://app.waafir.io — استبدله بعنوان بيئة staging إذا كنت تُجري التكامل مع مستأجر الاختبار (sandbox) أولًا.
الاصطلاحات المستخدمة في الوصفات
- تُكتب جميع متغيرات الصدفة في أمثلة cURL بالشكل
${UPPER_CASE_NAME}لتتمكن من تنفيذexportلها مرة واحدة وإعادة استخدامها عبر الوصفات. - تفترض أمثلة TypeScript وPython أن
BASE_URLوPATيُقرآن من البيئة. كيّف ذلك مع أداة تحميل الإعدادات لديك. - ترويسة
Idempotency-Keyهي الاصطلاح المعتمد على مستوى المنصة لإعادة المحاولة الآمنة؛ راجع وصفة إعادة المحاولة للدلالات الدقيقة. - تقبل جميع نقاط نهاية الكتابة قيم
external_idالخاصة بك — فالمعرّفات التي يقدّمها المستدعي تبقى المرجع المعتمد طوال الاستيعاب والمطابقة وتنزيل الشريط. ولا تحتاج أبدًا إلى معرفة معرّفات UUID الداخلية في Waafir.
ما لا يغطيه دليل الوصفات
دليل الوصفات موجّه نحو المهام. للاطلاع على التعريفات الشاملة لنقاط النهاية، ومخططات الطلبات والاستجابات، ومراجع رموز الأخطاء، راجع قسم مرجع API عند صدوره إلى جانب دليل الوصفات. ولمفاهيم المنتج، مثل ماهية المحفظة وعلاقتها بغرفة البيانات، راجع غرف البيانات وقسم المفاهيم الأساسية.
الوصفات
- الاستيراد المجمّع لشريط القروض عبر NDJSON غير المتزامن — تدفق الاستيعاب الأساسي: رفع مباشر، ثم اعتماد، ثم استطلاع حتى الاكتمال.
- التحقق من التحميل بالتشغيل التجريبي قبل اعتماد البيانات — التدفق نفسه مع
?dryRun=true؛ اعرف ما يحتويه ملفك قبل كتابة أي صفوف. - إعادة المحاولة بأمان باستخدام مفتاح عدم التكرار — تجاوز أعطال الشبكة العابرة دون إنشاء عمليات استيراد مكرّرة.
- فحص أخطاء الإخفاق الجزئي بعد الاستيراد — تصفّح الأخطاء لكل صف عندما ينتهي الاستيراد بالحالة
partial. - إلغاء استيراد قيد التنفيذ — أوقف استيرادًا طويل التشغيل عند حدّ الدفعة التالية دون صفوف مكتوبة جزئيًا.
- مطابقة بياناتك بالمعرّف الخارجي — تأكّد من وصول صف ما باستخدام معرّفك الخاص، وتحقّق من الأعداد اليومية.