Imports asynchrones
La surface des imports asynchrones est la voie dédiée aux chargements historiques et à tout lot dépassant la limite de dix mille lignes ou de dix mégaoctets du NDJSON en masse. Le flux se déroule en deux phases : vous décrivez ce que vous comptez téléverser, recevez une URL de téléversement à durée limitée, y envoyez directement le fichier par PUT, puis demandez à la plateforme de le valider (commit). Un worker lit ensuite le fichier en flux, ligne par ligne, en consignant les erreurs par ligne et en exposant la progression via un endpoint de statut.
Les routes présentées ici sont les points d'entrée du domaine des prêts vers le flux d'import.
Cycle de vie
Le cycle de vie comporte sept états. La plupart des chargements de production passent par pending_upload → queued → processing → succeeded ; les autres états correspondent aux cas d'échec.
| État | Signification |
|---|---|
pending_upload | La ligne d'import existe ; l'URL de téléversement à durée limitée est active ; la plateforme n'a pas encore vu le fichier. |
queued | La validation a réussi ; le worker n'a pas encore pris en charge le fichier. |
processing | Le worker lit le fichier en flux, ligne par ligne. |
succeeded | Chaque ligne a été stockée. |
partial | Le fichier a été entièrement traité, mais au moins une ligne a échoué. |
failed | Une erreur fatale a interrompu le traitement avant son terme (par ex. gzip mal formé, fichier téléversé introuvable, erreur interne du worker). |
cancelled | L'appelant a annulé l'import ; le worker s'est arrêté à la limite de bloc suivante. |
Une ligne qui ne quitte jamais l'état pending_upload correspond à une URL de téléversement émise mais jamais validée ; ces lignes sont régulièrement purgées après l'expiration du TTL de l'URL.
Aperçu des routes
| Méthode | Chemin | Objet |
|---|---|---|
POST | /api/v1/monitoring/loan/imports | Démarrer un nouvel import ; recevoir une URL de téléversement à durée limitée. |
POST | /api/v1/monitoring/loan/imports/{id}/commit | Finaliser le téléversement, mettre le worker en file d'attente. |
GET | /api/v1/monitoring/loan/imports/{id} | Lire le statut, les compteurs et le résumé des erreurs. |
GET | /api/v1/monitoring/loan/imports/{id}?errors=true | Parcourir page par page les erreurs par ligne. |
GET | /api/v1/monitoring/loan/imports | Lister les imports de prêts de l'appelant. |
DELETE | /api/v1/monitoring/loan/imports/{id} | Annuler un import en cours. |
POST /api/v1/monitoring/loan/imports
Démarre un nouvel import. Renvoie l'identifiant de l'import, une URL de téléversement à durée limitée et les en-têtes de téléversement que votre client doit reprendre lors du PUT du fichier.
Corps de la requête
| Champ | Type | Obligatoire | Contrainte |
|---|---|---|---|
kind | énumération | oui | L'un des six types. |
filename | chaîne | oui | 1 à 255 caractères ; uniquement pour l'affichage. |
sizeBytes | entier | oui | Entier positif ; correspond à la taille du fichier que vous comptez téléverser. |
portfolioId | chaîne UUID | null | non | Remplacement facultatif ; les lignes du corps portent toujours le leur. |
idempotencyKey | chaîne | null | non | L'en-tête est préférable ; le champ du corps sert de solution de repli. |
dryRun | booléen | non | true exécute la validation sans mise en file d'attente. |
metadata | objet | null | non | Transmis tel quel. |
rowCountDeclared | entier | null | non | Indicatif — améliore le suivi de la progression. |
L'en-tête HTTP Idempotency-Key l'emporte sur le champ du corps lorsque les deux sont fournis.
Réponse — 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"
}| Champ | Remarques |
|---|---|
importId | L'identifiant de plateforme que vous indiquez dans chaque appel ultérieur. |
uploadUrl | URL à durée limitée pour le téléversement par PUT. |
headers | Un dictionnaire d'en-têtes HTTP que votre PUT doit inclure. |
s3Key | La clé de stockage sous laquelle le fichier sera conservé. |
reused | true si la réponse résulte de la déduplication d'une Idempotency-Key antérieure. |
statusUrl / commitUrl | URL pratiques pour la suite du cycle de vie. |
Codes de statut
| Statut | Enveloppe | Déclencheur |
|---|---|---|
202 Accepted | comme ci-dessus | Ligne d'import créée. |
400 Bad Request | errors[] (path/message) | Échec de validation du corps. |
400 Bad Request | { error, code: "UNKNOWN_KIND", allowed: [...] } | kind ne fait pas partie des six types de prêts. |
409 Conflict | { error, code: "IDEMPOTENCY_KEY_REUSED", importId, mismatchedFields } | La clé Idempotency-Key a déjà été utilisée pour une importation avec des paramètres différents. |
Téléversement du fichier
Une fois en possession d'une uploadUrl, envoyez-y directement le fichier par PUT. Reprenez chaque en-tête du dictionnaire headers de la réponse ; la signature de l'URL les couvre, et le téléversement est refusé dans le cas contraire.
curl -X PUT "$UPLOAD_URL" \
-H "<header-name>: <header-value>" \
--data-binary @your-file.ndjsonLe téléversement va directement vers le stockage ; il ne transite pas par l'API. Le format de fichier est le même format de transmission NDJSON que celui documenté sur la page NDJSON en masse, sans limite de lignes.
POST /api/v1/monitoring/loan/imports/{id}/commit
Une fois le PUT terminé, appelez commit pour indiquer à la plateforme que le téléversement est terminé. La plateforme vérifie que le fichier existe, fait passer la ligne d'import de pending_upload à queued et met le worker en file d'attente.
Requête
Aucun corps. L'Idempotency-Key est implicite — un second commit sur une ligne qui n'est pas à l'état pending_upload est sans effet et renvoie l'état courant.
Réponses
200 OK :
{ "importId": "1234abcd-...", "status": "queued" }| Statut | Enveloppe | Déclencheur |
|---|---|---|
200 OK | { importId, status } | Commit réussi, ou la ligne avait déjà dépassé l'état pending_upload (idempotent). |
404 Not Found | standard | L'import n'existe pas ou appartient à une autre organisation. |
409 Conflict | { error, code: "COMMIT_FAILED" } | La plateforme n'a pas trouvé le fichier téléversé — en général, le téléversement n'a jamais eu lieu ou n'est pas terminé. Relancez le commit une fois le téléversement terminé. |
GET /api/v1/monitoring/loan/imports/{id}
Lit le statut courant, les compteurs et le résumé des erreurs d'un import. C'est l'endpoint que votre client interroge pour suivre la progression.
Requête
| Paramètre | Position | Obligatoire | Remarques |
|---|---|---|---|
id | chemin | oui | L'UUID de plateforme de l'import. |
errors | requête | non | true bascule en mode erreurs paginées (voir ci-dessous). |
Réponse — mode par défaut
{
"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 est un petit résumé intégré — totaux par code d'erreur et jusqu'à dix lignes d'exemple. Pour la liste complète par ligne, passez en mode erreurs paginées.
Réponse — ?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
}| Champ | Remarques |
|---|---|
rowNumber | Index de ligne, à partir de 1, dans le NDJSON téléversé. |
errorCode | Les valeurs courantes incluent parse_error (la ligne n'était pas du JSON valide), validation_error (le schéma a rejeté la ligne), portfolio_mismatch (le portfolioId de la ligne ne correspond pas à l'ancre de l'import) et processor_error (un échec inattendu du gestionnaire). Consultez Erreurs et codes de statut pour la liste consolidée. |
errorMessage | Résumé lisible de l'échec. |
rawRow | La ligne NDJSON d'origine, conservée telle quelle pour le débogage. |
limit vaut 20 par défaut, 100 au maximum. offset vaut 0 par défaut. La pagination parcourt la liste d'erreurs persistée dans l'ordre de rowNumber ; un curseur stable est donc offset += limit.
Codes de statut
| Statut | Déclencheur |
|---|---|
200 OK | La ligne existe dans votre organisation. |
400 Bad Request | limit ou offset mal formé lorsque ?errors=true. |
404 Not Found | Ligne introuvable ou d'une autre organisation. |
GET /api/v1/monitoring/loan/imports
Liste les imports de prêts de l'appelant, du plus récent au plus ancien.
Requête
| Paramètre | Position | Obligatoire | Contrainte |
|---|---|---|---|
status | requête | non | L'un des sept états du cycle de vie. |
kind | requête | non | L'un des six types de prêts. |
limit | requête | non | 1 à 100 ; 20 par défaut. |
offset | requête | non | Positif ou nul ; 0 par défaut. |
Réponse
{
"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}
Annule un import en cours. Le worker s'arrête à la limite de bloc suivante ; les lignes déjà stockées sont conservées. L'annulation d'une ligne déjà dans un état terminal (succeeded, partial, failed ou cancelled) est sans effet et renvoie l'état existant.
Réponses
200 OK :
{ "importId": "1234abcd-...", "status": "cancelled" }| Statut | Déclencheur |
|---|---|
200 OK | Annulation appliquée, ou la ligne était déjà dans un état terminal. |
404 Not Found | Ligne introuvable ou d'une autre organisation. |
Types
Le champ kind de la requête de démarrage détermine le schéma au regard duquel chaque ligne est validée et l'entité qui reçoit les lignes. Les six types correspondent un à un aux entités :
| Type | Entité | Schéma |
|---|---|---|
borrower | borrowers | Identique à POST /borrowers. |
loan | loans | Identique à POST /loans. |
scheduled_repayment | scheduled_repayments | Schéma des échéances de remboursement. |
actual_payment | actual_payments | Identique à POST /payments. |
collateral | collateral | Schéma des garanties. |
collateral_valuation | collateral_valuations | Schéma des évaluations de garanties. |
Un kind absent de cette liste renvoie 400 UNKNOWN_KIND avec les valeurs autorisées listées dans la réponse, de sorte qu'une faute de frappe se corrige sans tâtonnement.
Quand utiliser cette surface
Utilisez les imports asynchrones lorsque :
- Vous chargez une archive historique — les chargements historiques typiques atteignent des millions de lignes.
- Votre lot dépasse l'une des limites du NDJSON en masse (10 000 lignes ou 10 Mo).
- Vous souhaitez pouvoir annuler en cours de chargement — le NDJSON en masse n'a pas de surface d'annulation, car la requête elle-même constitue le chargement.
- Votre client tolère l'interrogation périodique — aucune notification push n'est envoyée à la fin d'un import.
Pour les petits lots opérationnels qui tiennent dans une seule requête synchrone, le NDJSON en masse est la voie la plus simple.