NDJSON المجمّع
تقبل واجهة NDJSON المجمّع ما يصل إلى عشرة آلاف صف في طلب HTTP متزامن واحد، وتطبّق التحقق على كل صف وفق المخططات نفسها التي تستخدمها مسارات السجل الواحد، وتُرجع تقريرًا بالأخطاء على مستوى الصف. استخدمها لدفعات نهاية اليوم التي تتسع بسهولة في طلب HTTP واحد؛ وللتحميلات التاريخية أو الدفعات الأكبر استخدم الاستيرادات غير المتزامنة.
صيغة النقل هي JSON المفصول بأسطر جديدة: كائن JSON صالح واحد في كل سطر، بلا فاصلة لاحقة، وبلا مصفوفة محيطة، وبلا غلاف افتتاحي أو ختامي. تُقبل الأسطر الفارغة بين الكائنات ويجري تخطّيها.
المسارات
هناك مسار واحد لكل كيان. ويطابق المخطط المطبّق على كل سطر الكيانَ الوارد في عنوان URL.
| الطريقة | المسار | الكيان |
|---|---|---|
POST | /api/v1/monitoring/loan/bulk/borrowers | borrower |
POST | /api/v1/monitoring/loan/bulk/loans | loan |
POST | /api/v1/monitoring/loan/bulk/scheduled-repayments | scheduled_repayment |
POST | /api/v1/monitoring/loan/bulk/actual-payments | actual_payment |
POST | /api/v1/monitoring/loan/bulk/collateral | collateral |
POST | /api/v1/monitoring/loan/bulk/collateral-valuations | collateral_valuation |
يجب أن يكون كل سطر في متن الطلب كائن JSON صالحًا يستوفي مخطط الكيان كما هو موثّق في صفحة السجل الواحد. المخططات متطابقة؛ ولا يختلف إلا غلاف النقل.
الطلب
POST /api/v1/monitoring/loan/bulk/loans HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/x-ndjson
Idempotency-Key: <opaque-key>الترويسات ومعاملات الاستعلام:
| الاسم | الموضع | مطلوب | ملاحظات |
|---|---|---|---|
Authorization | header | نعم | رمز PAT من نوع Bearer. |
Content-Type | header | لا | يُوصى بـ application/x-ndjson؛ ويُقبل application/json. |
Idempotency-Key | header | لا | يُوصى به بشدة لدفعات الإنتاج. |
?dryRun=true | query | لا | يُجري التحقق ويتخطى عمليات الكتابة. |
?portfolioId=<UUID> | query | نعم | مرتكز الاستئجار للدفعة؛ غيابه أو صيغته غير السليمة يُرجع 400 portfolio_id_required. |
تقرأ الواجهة المجمّعة portfolioId من سلسلة الاستعلام فقط؛ ويُتجاهل حقل المتن الذي يحمل الاسم نفسه في كل صف على مستوى غلاف الدفعة. ويجب أن يشير كل صف في المتن إلى المحفظة نفسها.
المتن هو حمولة NDJSON نفسها — بترميز UTF-8، وتنتهي بسطر جديد واحد. تُرفض الأسطر التي تتجاوز عشرة آلاف والمتون التي تتجاوز عشرة ميغابايت — راجع حدود الحجم.
العقد لكل صف
يُتحقق من كل صف بشكل مستقل وفق مخطط الكيان. وتنطبق على كل صف القواعد نفسها المطبّقة على الكتابة في السجل الواحد:
- يجب أن يحمل كل صف
idUUID و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"
}
]
}| الحقل | النوع | الوصف |
|---|---|---|
totalRows | integer | عدد الأسطر غير الفارغة في المتن. |
succeeded | integer | عدد الصفوف التي خُزّنت. |
failed | integer | totalRows - succeeded. |
bronzeSubmissionId | UUID | معرّف سجل الإرسال الوحيد لمتن NDJSON بأكمله. يغيب في استجابة ?dryRun=true. |
reused | boolean | يظهر بالقيمة true فقط عندما تطابق Idempotency-Key دفعة سابقة وأُعيد بناء الاستجابة؛ ويغيب في غير ذلك. |
dryRun | boolean | يظهر بالقيمة true فقط في استجابة ?dryRun=true؛ ويغيب في غير ذلك. |
errors[].rowNumber | integer | رقم السطر داخل متن الطلب بدءًا من 1. |
errors[].code | enum | validation_failed | unique_violation | fk_violation | check_violation | db_error. |
errors[].message | string | ملخص مقروء للبشر؛ وفي حالة 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 طويل التنفيذ — تكتمل الدفعات المجمّعة عادةً في ثوانٍ قليلة، لكن الدفعة الكبيرة التي تتضمن الكثير من عمليات البحث عن المفاتيح الأجنبية في قاعدة البيانات قد تستغرق وقتًا أطول.
اختر الاستيرادات غير المتزامنة عندما:
- تتجاوز دفعتك أيًّا من حدّي الحجم.
- تحمّل أرشيفًا تاريخيًا من الدفعات أو أقساط السداد المجدولة أو المقترضين — إذ تبلغ التحميلات التاريخية المعتادة ملايين الصفوف.
- تريد الاحتفاظ بخيار إلغاء تحميل قيد التنفيذ.