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

الاستيرادات غير المتزامنة

واجهة الاستيرادات غير المتزامنة هي المسار المخصّص للتحميلات التاريخية ولأي دفعة تتجاوز حد 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.

متن الطلب

الحقلالنوعمطلوبالقيد
kindenumنعمواحد من الأنواع الستة.
filenamestringنعممن 1 إلى 255 حرفًا؛ للعرض فقط.
sizeBytesintegerنعمعدد صحيح موجب؛ يطابق حجم الملف الذي تنوي رفعه.
portfolioIdسلسلة UUID | nullلاتجاوز اختياري؛ وتظل الصفوف في المتن تحمل قيمتها الخاصة.
idempotencyKeystring | nullلاالترويسة هي المفضّلة؛ وحقل المتن بديل احتياطي.
dryRunbooleanلاtrue يُجري التحقق دون الوضع في قائمة الانتظار.
metadataobject | nullلاتمرير حرفي.
rowCountDeclaredinteger | 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مفتاح التخزين الذي سيوضع الملف تحته.
reusedtrue إذا كانت الاستجابة نتيجة إزالة التكرار لمفتاح Idempotency-Key سابق.
statusUrl / commitUrlعناوين URL مساعدة لدورة الحياة التالية.

رموز الحالة

الحالةالغلافالمُسبِّب
202 Acceptedكما أعلاهأُنشئ صف الاستيراد.
400 Bad Requesterrors[] (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}

يقرأ الحالة الحالية والأعداد وملخص الأخطاء لاستيراد ما. هذه هي نقطة نهاية الاستعلام الدوري التي يستدعيها عميلك لمراقبة التقدّم.

الطلب

المعاملالموضعمطلوبملاحظات
idpathنعمUUID المنصة الخاص بالاستيراد.
errorsqueryلا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 Requestlimit أو offset بصيغة غير سليمة عند ?errors=true.
404 Not Foundالصف غير موجود أو تابع لمؤسسة أخرى.

GET /api/v1/monitoring/loan/imports

يسرد استيرادات القروض الخاصة بالمستدعي، الأحدث أولًا.

الطلب

المعاملالموضعمطلوبالقيد
statusqueryلاواحدة من حالات دورة الحياة السبع.
kindqueryلاواحد من أنواع القروض الستة.
limitqueryلامن 1 إلى 100؛ القيمة الافتراضية 20.
offsetqueryلاغير سالب؛ القيمة الافتراضية 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 في طلب البدء المخطط الذي يُتحقق من كل صف وفقه والكيان الذي يتلقى الصفوف. وتقابل الأنواع الستة الكيانات واحدًا لواحد:

النوعالكيانالمخطط
borrowerborrowersمطابق لـ POST /borrowers.
loanloansمطابق لـ POST /loans.
scheduled_repaymentscheduled_repaymentsمخطط السداد المجدول.
actual_paymentactual_paymentsمطابق لـ POST /payments.
collateralcollateralمخطط الضمان.
collateral_valuationcollateral_valuationsمخطط تقييم الضمان.

القيمة kind غير الموجودة في هذه القائمة تُرجع 400 UNKNOWN_KIND مع سرد القيم المسموح بها في الاستجابة، بحيث يمكن تدارك الخطأ الطباعي دون تجربة وخطأ.

متى تستخدم هذه الواجهة

استخدم الاستيرادات غير المتزامنة عندما:

  • تحمّل أرشيفًا تاريخيًا — إذ تبلغ التحميلات التاريخية المعتادة ملايين الصفوف.
  • تتجاوز دفعتك أيًّا من حدّي NDJSON المجمّع (10 000 صف أو 10 MB).
  • تريد خيار الإلغاء في منتصف التحميل — فلا توجد واجهة إلغاء في NDJSON المجمّع لأن الطلب نفسه هو التحميل.
  • يتحمّل عميلك الاستعلام الدوري — إذ لا يوجد إشعار فوري عند اكتمال الاستيراد.

للدفعات التشغيلية الصغيرة التي تتسع في طلب متزامن واحد، فإن NDJSON المجمّع هو المسار الأبسط.