الاستيرادات غير المتزامنة
واجهة الاستيرادات غير المتزامنة هي المسار المخصّص للتحميلات التاريخية ولأي دفعة تتجاوز حد NDJSON المجمّع البالغ عشرة آلاف صف أو عشرة ميغابايت. التدفق على مرحلتين: تصف ما تنوي رفعه، فتتلقى عنوان URL للرفع محدود الصلاحية زمنيًا، ثم ترفع الملف مباشرةً إليه عبر PUT، ثم تطلب من المنصة الالتزام به. ومن هناك يقرأ عامل المعالجة الملف صفًا صفًا، ويلتقط الأخطاء لكل صف، ويُظهر التقدّم عبر نقطة نهاية للحالة.
المسارات التي تراها هنا هي نقاط الدخول الخاصة بنطاق القروض إلى تدفق الاستيراد.
دورة الحياة
لدورة الحياة سبع حالات. تمر معظم تحميلات الإنتاج عبر pending_upload → queued → processing → succeeded؛ أما الحالات الأخرى فتُظهر أنماط الفشل.
| الحالة | المعنى |
|---|---|
pending_upload | صف الاستيراد موجود؛ وعنوان URL للرفع محدود الصلاحية فعّال؛ ولم تَرَ المنصة الملف بعد. |
queued | نجح الالتزام؛ ولم يلتقط عامل المعالجة الملف بعد. |
processing | يقرأ عامل المعالجة الملف صفًا صفًا. |
succeeded | خُزّن كل صف. |
partial | عولج الملف بالكامل لكن صفًا واحدًا على الأقل فشل. |
failed | أوقف خطأ فادح المعالجة قبل اكتمالها (مثل ملف gzip غير سليم، أو ملف مرفوع مفقود، أو خطأ داخلي في عامل المعالجة). |
cancelled | ألغى المستدعي الاستيراد؛ وتوقف عامل المعالجة عند حد الجزء التالي. |
الصف الذي لا يغادر حالة pending_upload أبدًا يمثّل عنوان URL للرفع صدر لكن لم يُلتزم به قط؛ وتُجمع هذه الصفوف كمهملات بشكل روتيني بعد انتهاء مدة صلاحية عنوان URL.
المسارات في لمحة
| الطريقة | المسار | الغرض |
|---|---|---|
POST | /api/v1/monitoring/loan/imports | بدء استيراد جديد؛ وتلقّي عنوان URL للرفع محدود الصلاحية. |
POST | /api/v1/monitoring/loan/imports/{id}/commit | إنهاء الرفع، ووضع عامل المعالجة في قائمة الانتظار. |
GET | /api/v1/monitoring/loan/imports/{id} | قراءة الحالة والأعداد وملخص الأخطاء. |
GET | /api/v1/monitoring/loan/imports/{id}?errors=true | تصفّح الأخطاء لكل صف صفحةً صفحة. |
GET | /api/v1/monitoring/loan/imports | سرد استيرادات القروض الخاصة بالمستدعي. |
DELETE | /api/v1/monitoring/loan/imports/{id} | إلغاء استيراد قيد التنفيذ. |
POST /api/v1/monitoring/loan/imports
يبدأ استيرادًا جديدًا. يُرجع معرّف الاستيراد، وعنوان URL للرفع محدود الصلاحية، وترويسات الرفع التي يجب أن يعيدها عميلك عند رفع الملف عبر PUT.
متن الطلب
| الحقل | النوع | مطلوب | القيد |
|---|---|---|---|
kind | enum | نعم | واحد من الأنواع الستة. |
filename | string | نعم | من 1 إلى 255 حرفًا؛ للعرض فقط. |
sizeBytes | integer | نعم | عدد صحيح موجب؛ يطابق حجم الملف الذي تنوي رفعه. |
portfolioId | سلسلة UUID | null | لا | تجاوز اختياري؛ وتظل الصفوف في المتن تحمل قيمتها الخاصة. |
idempotencyKey | string | null | لا | الترويسة هي المفضّلة؛ وحقل المتن بديل احتياطي. |
dryRun | boolean | لا | true يُجري التحقق دون الوضع في قائمة الانتظار. |
metadata | object | null | لا | تمرير حرفي. |
rowCountDeclared | integer | null | لا | استرشادي — يحسّن الإبلاغ عن التقدّم. |
تتقدّم ترويسة HTTP Idempotency-Key على حقل المتن عند تقديم الاثنين معًا.
الاستجابة — 202 Accepted
{
"importId": "1234abcd-5678-90ef-1234-567890abcdef",
"uploadUrl": "https://<upload-host>/...?<signature>",
"headers": { "<header-name>": "<header-value>" },
"s3Key": "imports/abc.../...",
"reused": false,
"statusUrl": "/api/v1/monitoring/loan/imports/1234abcd-5678-90ef-1234-567890abcdef",
"commitUrl": "/api/v1/monitoring/loan/imports/1234abcd-5678-90ef-1234-567890abcdef/commit"
}| الحقل | ملاحظات |
|---|---|
importId | معرّف المنصة الذي تشير إليه في كل استدعاء لاحق. |
uploadUrl | عنوان URL محدود الصلاحية للرفع عبر PUT. |
headers | خريطة بترويسات HTTP التي يجب أن يتضمنها طلب PUT. |
s3Key | مفتاح التخزين الذي سيوضع الملف تحته. |
reused | true إذا كانت الاستجابة نتيجة إزالة التكرار لمفتاح Idempotency-Key سابق. |
statusUrl / commitUrl | عناوين URL مساعدة لدورة الحياة التالية. |
رموز الحالة
| الحالة | الغلاف | المُسبِّب |
|---|---|---|
202 Accepted | كما أعلاه | أُنشئ صف الاستيراد. |
400 Bad Request | errors[] (path/message) | فشل التحقق من المتن. |
400 Bad Request | { error, code: "UNKNOWN_KIND", allowed: [...] } | kind ليس واحدًا من أنواع القروض الستة. |
409 Conflict | { error, code: "IDEMPOTENCY_KEY_REUSED", importId, mismatchedFields } | سبق استخدام Idempotency-Key لعملية استيراد بمعاملات مختلفة. |
رفع الملف
بمجرد حصولك على uploadUrl، ارفع الملف إليه مباشرةً عبر PUT. أعِد كل ترويسة من خريطة headers في الاستجابة؛ فالتوقيع على عنوان URL يغطيها، ويُرفض الرفع بخلاف ذلك.
curl -X PUT "$UPLOAD_URL" \
-H "<header-name>: <header-value>" \
--data-binary @your-file.ndjsonيذهب الرفع مباشرةً إلى التخزين؛ ولا يمر عبر API. صيغة الملف هي صيغة نقل NDJSON نفسها الموثّقة في صفحة NDJSON المجمّع، دون حد للصفوف.
POST /api/v1/monitoring/loan/imports/{id}/commit
بعد اكتمال PUT، استدعِ الالتزام لتُبلغ المنصة بأن الرفع قد اكتمل. تتأكد المنصة من وجود الملف، وتنقل صف الاستيراد من pending_upload إلى queued، وتضع عامل المعالجة في قائمة الانتظار.
الطلب
لا متن. Idempotency-Key ضمني — فالالتزام الثاني على صف ليس في حالة pending_upload لا يُحدث أثرًا ويُرجع الحالة الحالية.
الاستجابات
200 OK:
{ "importId": "1234abcd-...", "status": "queued" }| الحالة | الغلاف | المُسبِّب |
|---|---|---|
200 OK | { importId, status } | نجح الالتزام، أو كان الصف قد تجاوز بالفعل pending_upload (دون أثر متكرر). |
404 Not Found | قياسي | الاستيراد غير موجود أو ينتمي إلى مؤسسة أخرى. |
409 Conflict | { error, code: "COMMIT_FAILED" } | لم تتمكن المنصة من العثور على الملف المرفوع — عادةً لأن الرفع لم يحدث أو لم ينتهِ بعد. أعِد محاولة الالتزام بعد اكتمال الرفع. |
GET /api/v1/monitoring/loan/imports/{id}
يقرأ الحالة الحالية والأعداد وملخص الأخطاء لاستيراد ما. هذه هي نقطة نهاية الاستعلام الدوري التي يستدعيها عميلك لمراقبة التقدّم.
الطلب
| المعامل | الموضع | مطلوب | ملاحظات |
|---|---|---|---|
id | path | نعم | UUID المنصة الخاص بالاستيراد. |
errors | query | لا | true يحوّل إلى وضع الأخطاء المقسّمة إلى صفحات (انظر أدناه). |
الاستجابة — الوضع الافتراضي
{
"importId": "1234abcd-...",
"kind": "actual_payment",
"domain": "loan",
"status": "succeeded",
"filename": "payments-2025-full-year.ndjson",
"sizeBytes": 524288000,
"portfolioId": "ddf63d12-...",
"rowCountDeclared": 1500000,
"rowCountProcessed": 1500000,
"rowCountSucceeded": 1499987,
"rowCountFailed": 13,
"createdAt": "2026-05-20T10:00:00Z",
"startedAt": "2026-05-20T10:00:15Z",
"completedAt": "2026-05-20T10:18:42Z",
"dryRun": false,
"errorSummary": {
"totals": { "validation_error": 9, "fk_violation": 4 },
"samples": [
{ "rowNumber": 12, "errorCode": "validation_error", "errorMessage": "..." },
{ "rowNumber": 1041, "errorCode": "fk_violation", "errorMessage": "..." }
]
}
}errorSummary ملخص صغير مضمَّن — إجماليات حسب رمز الخطأ وما يصل إلى عشرة صفوف كعيّنات. للحصول على القائمة الكاملة لكل صف، حوّل إلى وضع الأخطاء المقسّمة إلى صفحات.
الاستجابة — ?errors=true&limit=&offset=
{
"items": [
{
"rowNumber": 12,
"errorCode": "validation_error",
"errorMessage": "interestRateApr must be >= 0",
"rawRow": "{\"id\":\"...\",\"interestRateApr\":\"-0.05\",...}",
"createdAt": "2026-05-20T10:01:14Z"
}
],
"limit": 20,
"offset": 0
}| الحقل | ملاحظات |
|---|---|
rowNumber | رقم السطر في ملف NDJSON المرفوع بدءًا من 1. |
errorCode | تشمل القيم الشائعة parse_error (السطر ليس JSON صالحًا)، وvalidation_error (رفض المخطط الصف)، وportfolio_mismatch (لا يطابق portfolioId الخاص بالصف مرتكز الاستيراد)، وprocessor_error (فشل غير متوقع في المعالج). راجع الأخطاء ورموز الحالة للقائمة الموحّدة. |
errorMessage | ملخص للفشل مقروء للبشر. |
rawRow | سطر NDJSON الأصلي، محفوظ حرفيًا لأغراض التصحيح. |
القيمة الافتراضية لـ limit هي 20، والحد الأقصى 100. والقيمة الافتراضية لـ offset هي 0. يتنقّل التقسيم إلى صفحات في قائمة الأخطاء المحفوظة بترتيب rowNumber، لذا فإن المؤشر الثابت هو offset += limit.
رموز الحالة
| الحالة | المُسبِّب |
|---|---|
200 OK | الصف موجود في مؤسستك. |
400 Bad Request | limit أو offset بصيغة غير سليمة عند ?errors=true. |
404 Not Found | الصف غير موجود أو تابع لمؤسسة أخرى. |
GET /api/v1/monitoring/loan/imports
يسرد استيرادات القروض الخاصة بالمستدعي، الأحدث أولًا.
الطلب
| المعامل | الموضع | مطلوب | القيد |
|---|---|---|---|
status | query | لا | واحدة من حالات دورة الحياة السبع. |
kind | query | لا | واحد من أنواع القروض الستة. |
limit | query | لا | من 1 إلى 100؛ القيمة الافتراضية 20. |
offset | query | لا | غير سالب؛ القيمة الافتراضية 0. |
الاستجابة
{
"items": [
{
"importId": "...",
"kind": "actual_payment",
"status": "succeeded",
"filename": "...",
"createdAt": "...",
"completedAt": "...",
"rowCountSucceeded": 1499987,
"rowCountFailed": 13
}
],
"limit": 20,
"offset": 0
}DELETE /api/v1/monitoring/loan/imports/{id}
يلغي استيرادًا قيد التنفيذ. يتوقف عامل المعالجة عند حد الجزء التالي؛ وتبقى الصفوف المخزّنة بالفعل. إلغاء صف في حالة نهائية بالفعل (succeeded أو partial أو failed أو cancelled) لا يُحدث أثرًا ويُرجع الحالة القائمة.
الاستجابات
200 OK:
{ "importId": "1234abcd-...", "status": "cancelled" }| الحالة | المُسبِّب |
|---|---|
200 OK | طُبّق الإلغاء أو كان الصف في حالة نهائية بالفعل. |
404 Not Found | الصف غير موجود أو تابع لمؤسسة أخرى. |
الأنواع
يحدد الحقل kind في طلب البدء المخطط الذي يُتحقق من كل صف وفقه والكيان الذي يتلقى الصفوف. وتقابل الأنواع الستة الكيانات واحدًا لواحد:
| النوع | الكيان | المخطط |
|---|---|---|
borrower | borrowers | مطابق لـ POST /borrowers. |
loan | loans | مطابق لـ POST /loans. |
scheduled_repayment | scheduled_repayments | مخطط السداد المجدول. |
actual_payment | actual_payments | مطابق لـ POST /payments. |
collateral | collateral | مخطط الضمان. |
collateral_valuation | collateral_valuations | مخطط تقييم الضمان. |
القيمة kind غير الموجودة في هذه القائمة تُرجع 400 UNKNOWN_KIND مع سرد القيم المسموح بها في الاستجابة، بحيث يمكن تدارك الخطأ الطباعي دون تجربة وخطأ.
متى تستخدم هذه الواجهة
استخدم الاستيرادات غير المتزامنة عندما:
- تحمّل أرشيفًا تاريخيًا — إذ تبلغ التحميلات التاريخية المعتادة ملايين الصفوف.
- تتجاوز دفعتك أيًّا من حدّي NDJSON المجمّع (10 000 صف أو 10 MB).
- تريد خيار الإلغاء في منتصف التحميل — فلا توجد واجهة إلغاء في NDJSON المجمّع لأن الطلب نفسه هو التحميل.
- يتحمّل عميلك الاستعلام الدوري — إذ لا يوجد إشعار فوري عند اكتمال الاستيراد.
للدفعات التشغيلية الصغيرة التي تتسع في طلب متزامن واحد، فإن NDJSON المجمّع هو المسار الأبسط.