Waafir
Cette page est une traduction automatique en attente de relecture humaine. Elle peut contenir des erreurs.

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.

ÉtatSignification
pending_uploadLa 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.
queuedLa validation a réussi ; le worker n'a pas encore pris en charge le fichier.
processingLe worker lit le fichier en flux, ligne par ligne.
succeededChaque ligne a été stockée.
partialLe fichier a été entièrement traité, mais au moins une ligne a échoué.
failedUne erreur fatale a interrompu le traitement avant son terme (par ex. gzip mal formé, fichier téléversé introuvable, erreur interne du worker).
cancelledL'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éthodeCheminObjet
POST/api/v1/monitoring/loan/importsDémarrer un nouvel import ; recevoir une URL de téléversement à durée limitée.
POST/api/v1/monitoring/loan/imports/{id}/commitFinaliser 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=trueParcourir page par page les erreurs par ligne.
GET/api/v1/monitoring/loan/importsLister 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

ChampTypeObligatoireContrainte
kindénumérationouiL'un des six types.
filenamechaîneoui1 à 255 caractères ; uniquement pour l'affichage.
sizeBytesentierouiEntier positif ; correspond à la taille du fichier que vous comptez téléverser.
portfolioIdchaîne UUID | nullnonRemplacement facultatif ; les lignes du corps portent toujours le leur.
idempotencyKeychaîne | nullnonL'en-tête est préférable ; le champ du corps sert de solution de repli.
dryRunbooléennontrue exécute la validation sans mise en file d'attente.
metadataobjet | nullnonTransmis tel quel.
rowCountDeclaredentier | nullnonIndicatif — 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"
}
ChampRemarques
importIdL'identifiant de plateforme que vous indiquez dans chaque appel ultérieur.
uploadUrlURL à durée limitée pour le téléversement par PUT.
headersUn dictionnaire d'en-têtes HTTP que votre PUT doit inclure.
s3KeyLa clé de stockage sous laquelle le fichier sera conservé.
reusedtrue si la réponse résulte de la déduplication d'une Idempotency-Key antérieure.
statusUrl / commitUrlURL pratiques pour la suite du cycle de vie.

Codes de statut

StatutEnveloppeDéclencheur
202 Acceptedcomme ci-dessusLigne d'import créée.
400 Bad Requesterrors[] (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.ndjson

Le 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" }
StatutEnveloppeDéclencheur
200 OK{ importId, status }Commit réussi, ou la ligne avait déjà dépassé l'état pending_upload (idempotent).
404 Not FoundstandardL'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ètrePositionObligatoireRemarques
idcheminouiL'UUID de plateforme de l'import.
errorsrequêtenontrue 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
}
ChampRemarques
rowNumberIndex de ligne, à partir de 1, dans le NDJSON téléversé.
errorCodeLes 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.
errorMessageRésumé lisible de l'échec.
rawRowLa 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

StatutDéclencheur
200 OKLa ligne existe dans votre organisation.
400 Bad Requestlimit ou offset mal formé lorsque ?errors=true.
404 Not FoundLigne 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ètrePositionObligatoireContrainte
statusrequêtenonL'un des sept états du cycle de vie.
kindrequêtenonL'un des six types de prêts.
limitrequêtenon1 à 100 ; 20 par défaut.
offsetrequêtenonPositif 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" }
StatutDéclencheur
200 OKAnnulation appliquée, ou la ligne était déjà dans un état terminal.
404 Not FoundLigne 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 :

TypeEntitéSchéma
borrowerborrowersIdentique à POST /borrowers.
loanloansIdentique à POST /loans.
scheduled_repaymentscheduled_repaymentsSchéma des échéances de remboursement.
actual_paymentactual_paymentsIdentique à POST /payments.
collateralcollateralSchéma des garanties.
collateral_valuationcollateral_valuationsSché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.