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

NDJSON المجمّع

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

صيغة النقل هي JSON المفصول بأسطر جديدة: كائن JSON صالح واحد في كل سطر، بلا فاصلة لاحقة، وبلا مصفوفة محيطة، وبلا غلاف افتتاحي أو ختامي. تُقبل الأسطر الفارغة بين الكائنات ويجري تخطّيها.

المسارات

هناك مسار واحد لكل كيان. ويطابق المخطط المطبّق على كل سطر الكيانَ الوارد في عنوان URL.

الطريقةالمسارالكيان
POST/api/v1/monitoring/loan/bulk/borrowersborrower
POST/api/v1/monitoring/loan/bulk/loansloan
POST/api/v1/monitoring/loan/bulk/scheduled-repaymentsscheduled_repayment
POST/api/v1/monitoring/loan/bulk/actual-paymentsactual_payment
POST/api/v1/monitoring/loan/bulk/collateralcollateral
POST/api/v1/monitoring/loan/bulk/collateral-valuationscollateral_valuation

يجب أن يكون كل سطر في متن الطلب كائن JSON صالحًا يستوفي مخطط الكيان كما هو موثّق في صفحة السجل الواحد. المخططات متطابقة؛ ولا يختلف إلا غلاف النقل.

الطلب

POST /api/v1/monitoring/loan/bulk/loans HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/x-ndjson
Idempotency-Key: <opaque-key>

الترويسات ومعاملات الاستعلام:

الاسمالموضعمطلوبملاحظات
Authorizationheaderنعمرمز PAT من نوع Bearer.
Content-Typeheaderلايُوصى بـ application/x-ndjson؛ ويُقبل application/json.
Idempotency-Keyheaderلايُوصى به بشدة لدفعات الإنتاج.
?dryRun=truequeryلايُجري التحقق ويتخطى عمليات الكتابة.
?portfolioId=<UUID>queryنعممرتكز الاستئجار للدفعة؛ غيابه أو صيغته غير السليمة يُرجع 400 portfolio_id_required.

تقرأ الواجهة المجمّعة portfolioId من سلسلة الاستعلام فقط؛ ويُتجاهل حقل المتن الذي يحمل الاسم نفسه في كل صف على مستوى غلاف الدفعة. ويجب أن يشير كل صف في المتن إلى المحفظة نفسها.

المتن هو حمولة NDJSON نفسها — بترميز UTF-8، وتنتهي بسطر جديد واحد. تُرفض الأسطر التي تتجاوز عشرة آلاف والمتون التي تتجاوز عشرة ميغابايت — راجع حدود الحجم.

العقد لكل صف

يُتحقق من كل صف بشكل مستقل وفق مخطط الكيان. وتنطبق على كل صف القواعد نفسها المطبّقة على الكتابة في السجل الواحد:

  • يجب أن يحمل كل صف id UUID وportfolioId خاصين به. المعرّفات التي يقدّمها المستدعي هي مفتاح إزالة التكرار لكل صف.
  • تتشارك الدفعة كلها Idempotency-Key الخاص بالطلب. راجع عدم التكرار أدناه.
  • metadata خاص بكل صف. يمكن لكل صف أن يحمل بياناته الوصفية الممرّرة؛ وتحفظها المنصة حرفيًا.
  • قواعد العملة والتواريخ والتعدادات والمبالغ مطابقة لقواعد السجل الواحد. الصف الذي يفشل في التحقق يظهر كمدخل في تقرير الأخطاء لكل صف مع code: "validation_failed".

الصف الذي يفشل في التحقق لا يُجهض الدفعة — يظهر الفشل كمدخل في errors[] وتستمر معالجة بقية الصفوف.

الاستجابة

يُرجَع 200 OK لكل دفعة جرى تحليل طلبها نفسه، بصرف النظر عن عدد الصفوف التي نجحت أو فشلت. ويحمل متن الاستجابة التقرير الكامل لكل صف:

{
  "totalRows": 4,
  "succeeded": 3,
  "failed": 1,
  "bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
  "reused": false,
  "errors": [
    {
      "rowNumber": 2,
      "code": "fk_violation",
      "message": "borrowerId references a borrower that does not exist in this portfolio"
    }
  ]
}
الحقلالنوعالوصف
totalRowsintegerعدد الأسطر غير الفارغة في المتن.
succeededintegerعدد الصفوف التي خُزّنت.
failedintegertotalRows - succeeded.
bronzeSubmissionIdUUIDمعرّف سجل الإرسال الوحيد لمتن NDJSON بأكمله. يغيب في استجابة ?dryRun=true.
reusedbooleanيظهر بالقيمة true فقط عندما تطابق Idempotency-Key دفعة سابقة وأُعيد بناء الاستجابة؛ ويغيب في غير ذلك.
dryRunbooleanيظهر بالقيمة true فقط في استجابة ?dryRun=true؛ ويغيب في غير ذلك.
errors[].rowNumberintegerرقم السطر داخل متن الطلب بدءًا من 1.
errors[].codeenumvalidation_failed | unique_violation | fk_violation | check_violation | db_error.
errors[].messagestringملخص مقروء للبشر؛ وفي حالة validation_failed تُدمج أخطاء التحقق في جملة واحدة.

لا يحمل شكل الخطأ لكل صف إلا rowNumber وcode وmessage. فلا توجد مصفوفة fieldErrors لكل صف، ولا rawRow لكل صف — إذ يُحفظ NDJSON الأصلي حرفيًا في سجل الإرسال بدلًا من إعادته عبر الشبكة.

القيمة 0 لـ succeeded ليست استجابة خطأ — فقد حُلّلت الدفعة وعالجت المنصة كل صف؛ والتقرير يخبرك بأن شيئًا لم يُخزَّن. أما الدفعة الفاشلة فعلًا (NDJSON غير سليم في المتن كله، أو متن كبير جدًا، أو محفظة مجهولة) فتُرجع 4xx وفق الجدول أدناه.

رموز الحالة

تستخدم أغلفة الأخطاء على المستوى الأعلى في هذه الواجهة قيم code بأحرف صغيرة، تختلف عن الرموز بالأحرف الكبيرة التي تستخدمها مسارات السجل الواحد. فضاءا الرموز منفصلان عن قصد.

الحالةالغلافالمُسبِّب
200 OKتقرير لكل صفعولجت الدفعة؛ ونتائج كل صف في errors[].
400 Bad Request{ error, code: "invalid_body", errors: [...] }تعذّرت قراءة متن الطلب كنص.
400 Bad Request{ error, code: "portfolio_id_required", fieldErrors: [...] }?portfolioId=<UUID> مفقود أو ليس UUID صالحًا.
400 Bad Request{ error, code: "invalid_json" }يُضمَّن داخل التقرير لكل صف على أساس كل صف — فالصف الذي ليس JSON صالحًا يحصل على مدخل code: "invalid_json" في errors[]. وتظل الدفعة ككل تُرجع 200.
404 Not Found{ error, code: "portfolio_not_found", fieldErrors: [...] }?portfolioId= غير موجود كمحفظة حية في مؤسستك.
413 Payload Too Large{ error, code: "batch_too_large", fieldErrors: [...] }راجع حدود الحجم.

حدود الحجم

تحدّ الواجهة المجمّعة الحمولات بالأصغر من:

  • عشرة آلاف سطر غير فارغ. تُرفض الصفوف التي تتجاوز ذلك قبل بدء المعالجة.
  • عشرة ميغابايت من متن الطلب.

الطلب الذي يتجاوز أيًّا من الحدّين يتلقى 413 Payload Too Large:

{
  "error": "batch payload exceeds 10485760 bytes; use the async import endpoint at /api/v1/monitoring/loan/imports",
  "code": "batch_too_large",
  "fieldErrors": [{ "path": "(body)", "message": "max 10485760 bytes" }]
}

يستخدم غلاف حد البايتات وغلاف حد الصفوف كلاهما code: "batch_too_large"؛ ويميّز error وfieldErrors[].message بين المُسبِّبين. ومسار التعافي القياسي هو تحويل الحمولة نفسها إلى تدفق الاستيرادات غير المتزامنة، الذي يرفع الملف مباشرة ويعالجه بشكل غير متزامن دون حد للصفوف.

عدم التكرار

تُزيل الواجهة المجمّعة التكرار بواسطة Idempotency-Key على مستوى غلاف الدفعة. والآلية كما يلي:

  • الاستدعاء الأول بالمفتاح K. يُسجَّل المتن كإرسال واحد، ويُعالج كل صف، ويُحفظ التقرير لكل صف مع الإرسال.
  • استدعاء ثانٍ بالمفتاح K والمتن نفسه. لا سجل ثانٍ ولا إعادة إدراج. تُرجع المنصة التقرير الأصلي مع reused: true.
  • استدعاء ثانٍ بالمفتاح K ومتن مختلف. تظل المنصة تُرجع التقرير الأصلي — فالإرسال الأصلي هو المصدر الموثوق. ويجب أن تستخدم إعادة الإرسال عبر POST بمتن مصحَّح مفتاحًا مختلفًا.

وهذا يعني أن العميل الذي يعيد المحاولة بعد انقطاع عابر في الشبكة آمن حتى لو اقتُطع متن الطلب الثاني أو عُدّل أثناء النقل — إذ تُرجع المنصة نتائج الصفوف من أول معالجة ناجحة.

سجل الإرسال

يُسجَّل كل طلب مجمّع كإرسال واحد يحتوي على متن NDJSON بأكمله، لا إرسال لكل صف. ولا يُخزَّن الصف المُعاد إرساله مرتين أبدًا، لأن externalId فريد داخل المحفظة بين الصفوف الحية.

bronzeSubmissionId في الاستجابة هو معرّف سجل الإرسال؛ احفظه إلى جانب سجل الإرسال المحلي لديك لأغراض التدقيق والمطابقة.

مثال cURL

cat <<'EOF' > batch.ndjson
{"id":"a1...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b1...","externalId":"L-001","principalAmount":"5000","currencyCode":"USD","interestRateApr":"0.18","disbursementDate":"2026-01-15","termMonths":12,"repaymentFrequency":"monthly","status":"active"}
{"id":"a2...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b2...","externalId":"L-002","principalAmount":"3000","currencyCode":"USD","interestRateApr":"0.20","disbursementDate":"2026-01-15","termMonths":24,"repaymentFrequency":"monthly","status":"active"}
{"id":"a3...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b3...","externalId":"L-003","principalAmount":"7500","currencyCode":"USD","interestRateApr":"0.22","disbursementDate":"2026-01-15","termMonths":18,"repaymentFrequency":"monthly","status":"active"}
EOF

curl -X POST "https://app.waafir.io/api/v1/monitoring/loan/bulk/loans?portfolioId=ddf63d12-1234-5678-9abc-def012345678" \
  -H "Authorization: Bearer $WAAFIR_PAT" \
  -H "Content-Type: application/x-ndjson" \
  -H "Idempotency-Key: nightly-2026-01-15-loans" \
  --data-binary @batch.ndjson

متى تختار NDJSON المجمّع ومتى تختار الاستيرادات غير المتزامنة

اختر NDJSON المجمّع عندما:

  • تتسع دفعتك في عشرة آلاف صف وعشرة ميغابايت.
  • تريد تقريرًا فوريًا لكل صف في استجابة HTTP.
  • تستطيع تحمّل طلب HTTP طويل التنفيذ — تكتمل الدفعات المجمّعة عادةً في ثوانٍ قليلة، لكن الدفعة الكبيرة التي تتضمن الكثير من عمليات البحث عن المفاتيح الأجنبية في قاعدة البيانات قد تستغرق وقتًا أطول.

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

  • تتجاوز دفعتك أيًّا من حدّي الحجم.
  • تحمّل أرشيفًا تاريخيًا من الدفعات أو أقساط السداد المجدولة أو المقترضين — إذ تبلغ التحميلات التاريخية المعتادة ملايين الصفوف.
  • تريد الاحتفاظ بخيار إلغاء تحميل قيد التنفيذ.