NDJSON en masse
La surface NDJSON en masse accepte jusqu'à dix mille lignes dans une seule requête HTTP synchrone, applique à chaque ligne une validation fondée sur les mêmes schémas que les routes unitaires et renvoie un rapport d'erreurs au niveau de la ligne. Utilisez-la pour les lots de fin de journée qui tiennent aisément dans une seule requête HTTP ; pour les chargements historiques ou les lots plus volumineux, utilisez les imports asynchrones.
Le format de transmission est le JSON délimité par des sauts de ligne : un objet JSON valide par ligne, sans virgule finale, sans tableau englobant, sans enveloppe d'ouverture ni de fermeture. Les lignes vides entre les objets sont acceptées et ignorées.
Routes
Il existe une route par entité. Le schéma appliqué à chaque ligne correspond à l'entité indiquée dans l'URL.
| Méthode | Chemin | Entité |
|---|---|---|
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 |
Chaque ligne du corps de la requête doit être un objet JSON valide conforme au schéma de l'entité tel que documenté sur la page CRUD unitaire. Les schémas sont identiques ; seule l'enveloppe de transmission diffère.
Requête
POST /api/v1/monitoring/loan/bulk/loans HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/x-ndjson
Idempotency-Key: <opaque-key>En-têtes et paramètres de requête :
| Nom | Position | Obligatoire | Remarques |
|---|---|---|---|
Authorization | en-tête | oui | PAT Bearer. |
Content-Type | en-tête | non | application/x-ndjson recommandé ; application/json est accepté. |
Idempotency-Key | en-tête | non | Vivement recommandé pour les lots de production. |
?dryRun=true | requête | non | Exécute la validation, ignore les écritures. |
?portfolioId=<UUID> | requête | oui | L'ancre de locataire du lot ; absent ou mal formé, il renvoie 400 portfolio_id_required. |
La surface en masse lit portfolioId uniquement dans la chaîne de requête ; le champ du même nom dans le corps de chaque ligne est ignoré au niveau de l'enveloppe du lot. Chaque ligne du corps doit référencer le même portefeuille.
Le corps est la charge utile NDJSON elle-même — encodée en UTF-8 et terminée par un unique saut de ligne. Les lignes au-delà de dix mille ou les corps de plus de dix mégaoctets sont refusés — voir limites de taille.
Contrat par ligne
Chaque ligne est validée indépendamment au regard du schéma de l'entité. Les mêmes règles s'appliquent à chaque ligne que pour une écriture unitaire :
- Chaque ligne doit porter son propre UUID
idet sonportfolioId. Les identifiants fournis par l'appelant servent de clé de déduplication par ligne. - L'ensemble du lot partage l'
Idempotency-Keyde la requête. Voir idempotence ci-dessous. metadataest propre à chaque ligne. Une ligne peut porter ses propres métadonnées transmises telles quelles ; la plateforme les persiste sans modification.- Les règles de devise, de dates, d'énumérations et de montants sont identiques à celles du mode unitaire. Une ligne qui échoue à la validation apparaît comme une entrée du rapport d'erreurs par ligne avec
code: "validation_failed".
Une ligne qui échoue à la validation n'interrompt pas le lot — l'échec apparaît comme une entrée de errors[] et le traitement des lignes restantes se poursuit.
Réponse
200 OK est renvoyé pour chaque lot dont la requête elle-même a été analysée, quel que soit le nombre de lignes ayant réussi ou échoué. Le corps de la réponse contient le rapport complet par ligne :
{
"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"
}
]
}| Champ | Type | Description |
|---|---|---|
totalRows | entier | Le nombre de lignes non vides du corps. |
succeeded | entier | Le nombre de lignes stockées. |
failed | entier | totalRows - succeeded. |
bronzeSubmissionId | UUID | L'identifiant de l'enregistrement de soumission unique pour l'ensemble du corps NDJSON. Absent d'une réponse ?dryRun=true. |
reused | booléen | Présent et à true uniquement lorsqu'une Idempotency-Key correspond à un lot antérieur et que la réponse a été reconstituée ; absent sinon. |
dryRun | booléen | Présent et à true uniquement dans une réponse ?dryRun=true ; absent sinon. |
errors[].rowNumber | entier | Index de ligne, à partir de 1, dans le corps de la requête. |
errors[].code | énumération | validation_failed | unique_violation | fk_violation | check_violation | db_error. |
errors[].message | chaîne | Résumé lisible ; pour validation_failed, les erreurs de validation sont regroupées en une seule phrase. |
La forme de l'erreur par ligne ne contient que rowNumber, code et message. Il n'y a pas de tableau fieldErrors par ligne, ni de rawRow par ligne — le NDJSON d'origine est conservé tel quel dans l'enregistrement de soumission au lieu d'être renvoyé sur le réseau.
Une valeur succeeded égale à 0 n'est pas une réponse d'erreur — le lot a été analysé et la plateforme a traité chaque ligne ; le rapport vous indique simplement que rien n'a été stocké. Un lot réellement en échec (NDJSON mal formé sur l'ensemble du corps, corps trop volumineux, portefeuille inconnu) renvoie un 4xx conformément au tableau ci-dessous.
Codes de statut
Les enveloppes d'erreur de premier niveau de cette surface utilisent des valeurs code en minuscules, distinctes des codes en majuscules utilisés par les routes unitaires. Les deux espaces de codes sont volontairement séparés.
| Statut | Enveloppe | Déclencheur |
|---|---|---|
200 OK | rapport par ligne | Lot traité ; résultats par ligne dans errors[]. |
400 Bad Request | { error, code: "invalid_body", errors: [...] } | Le corps de la requête n'a pas pu être lu comme du texte. |
400 Bad Request | { error, code: "portfolio_id_required", fieldErrors: [...] } | ?portfolioId=<UUID> est absent ou n'est pas un UUID valide. |
400 Bad Request | { error, code: "invalid_json" } | Intégré au rapport par ligne, ligne par ligne — une ligne qui n'est pas du JSON valide reçoit une entrée code: "invalid_json" dans errors[]. Le lot dans son ensemble renvoie tout de même 200. |
404 Not Found | { error, code: "portfolio_not_found", fieldErrors: [...] } | Le ?portfolioId= n'existe pas à l'état actif dans votre organisation. |
413 Payload Too Large | { error, code: "batch_too_large", fieldErrors: [...] } | Voir limites de taille. |
Limites de taille
La surface en masse plafonne les charges utiles à la plus petite des deux limites suivantes :
- Dix mille lignes non vides. Les lignes au-delà sont refusées avant le début du traitement.
- Dix mégaoctets de corps de requête.
Une requête qui dépasse l'une ou l'autre limite reçoit 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" }]
}L'enveloppe de la limite en octets et celle de la limite en lignes utilisent toutes deux code: "batch_too_large" ; error et fieldErrors[].message distinguent le déclencheur. La voie de reprise canonique consiste à basculer la même charge utile vers le flux des imports asynchrones, qui téléverse directement le fichier et le traite de manière asynchrone, sans limite de lignes.
Idempotence
La surface en masse déduplique sur la base de l'Idempotency-Key au niveau de l'enveloppe du lot. Le mécanisme :
- Premier appel avec la clé
K. Le corps est enregistré comme une soumission unique, chaque ligne est traitée et le rapport par ligne est conservé avec la soumission. - Second appel avec la clé
K, même corps. Aucun second enregistrement, aucune réinsertion. La plateforme renvoie le rapport d'origine avecreused: true. - Second appel avec la clé
K, corps différent. La plateforme renvoie tout de même le rapport d'origine — la soumission d'origine fait foi. Un nouvel envoi avec un corps corrigé doit utiliser une clé différente.
Ainsi, un client qui réessaie après une coupure réseau est protégé même si le corps de la seconde requête a été tronqué ou modifié en transit — la plateforme renvoie les résultats par ligne du premier traitement réussi.
Enregistrement de soumission
Chaque requête en masse est enregistrée comme une seule soumission contenant l'ensemble du corps NDJSON, et non une par ligne. Une ligne renvoyée n'est jamais stockée deux fois, car un externalId est unique au sein d'un portefeuille parmi les lignes actives.
Le bronzeSubmissionId de la réponse est l'identifiant de l'enregistrement de soumission ; conservez-le avec votre enregistrement local de soumission à des fins d'audit et de rapprochement.
Exemple 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.ndjsonChoisir entre NDJSON en masse et imports asynchrones
Choisissez le NDJSON en masse lorsque :
- Votre lot tient dans dix mille lignes et dix mégaoctets.
- Vous souhaitez un rapport immédiat par ligne dans la réponse HTTP.
- Vous pouvez tolérer une requête HTTP de longue durée — les lots en masse se terminent généralement en quelques secondes, mais un lot volumineux comportant de nombreuses vérifications de clés étrangères en base de données peut prendre plus de temps.
Choisissez les imports asynchrones lorsque :
- Votre lot dépasse l'une des deux limites de taille.
- Vous chargez une archive historique de paiements, d'échéances de remboursement ou d'emprunteurs — les chargements historiques typiques atteignent des millions de lignes.
- Vous souhaitez garder la possibilité d'annuler un chargement en cours.