Waafir
Esta página es una traducción automática pendiente de revisión humana. Puede contener errores.

Importaciones asíncronas

La superficie de importaciones asíncronas es la vía para las cargas históricas y para cualquier lote que supere el límite de diez mil filas o diez megabytes de NDJSON masivo. El flujo tiene dos fases: usted describe lo que pretende cargar, recibe una URL de carga de duración limitada, envía el archivo directamente a ella mediante PUT y, a continuación, pide a la plataforma que lo confirme. A partir de ahí, un worker recorre el archivo fila por fila, capturando los errores por fila y mostrando el progreso a través de un endpoint de estado.

Las rutas que se describen aquí son los puntos de entrada del dominio de préstamos al flujo de importación.

Ciclo de vida

El ciclo de vida tiene siete estados. La mayoría de las cargas de producción pasan por pending_upload → queued → processing → succeeded; los demás reflejan modos de fallo.

EstadoSignificado
pending_uploadLa fila de importación existe; la URL de carga de duración limitada está activa; la plataforma aún no ha visto el archivo.
queuedLa confirmación se completó; el worker aún no ha recogido el archivo.
processingEl worker está recorriendo el archivo fila por fila.
succeededSe almacenaron todas las filas.
partialEl archivo se procesó por completo, pero al menos una fila falló.
failedUn error fatal detuvo el procesamiento antes de completarse (p. ej., gzip mal formado, archivo cargado inexistente, error interno del worker).
cancelledEl llamante canceló la importación; el worker se detuvo en el siguiente límite de bloque.

Una fila que nunca sale de pending_upload representa una URL de carga que se emitió pero nunca se confirmó; estas filas se eliminan de forma rutinaria una vez que expira el TTL de la URL.

Rutas de un vistazo

MétodoRutaPropósito
POST/api/v1/monitoring/loan/importsIniciar una importación nueva; recibir una URL de carga de duración limitada.
POST/api/v1/monitoring/loan/imports/{id}/commitFinalizar la carga y poner en cola el worker.
GET/api/v1/monitoring/loan/imports/{id}Leer el estado, los recuentos y el resumen de errores.
GET/api/v1/monitoring/loan/imports/{id}?errors=truePaginar los errores por fila.
GET/api/v1/monitoring/loan/importsListar las importaciones de préstamos del llamante.
DELETE/api/v1/monitoring/loan/imports/{id}Cancelar una importación en curso.

POST /api/v1/monitoring/loan/imports

Inicia una importación nueva. Devuelve el id de la importación, una URL de carga de duración limitada y los encabezados de carga que su cliente debe reenviar al enviar el archivo mediante PUT.

Cuerpo de la solicitud

CampoTipoObligatorioRestricción
kindenumsíUno de los seis tipos.
filenamecadenasí1-255 caracteres; solo para visualización.
sizeBytesenterosíEntero positivo; coincide con el tamaño del archivo que pretende cargar.
portfolioIdcadena UUID | nullnoSustitución opcional; las filas del cuerpo siguen llevando la suya propia.
idempotencyKeycadena | nullnoSe prefiere el encabezado; el campo del cuerpo es una alternativa.
dryRunbooleanonotrue ejecuta la validación sin poner en cola.
metadataobjeto | nullnoTransferencia directa tal cual.
rowCountDeclaredentero | nullnoOrientativo — mejora el informe de progreso.

El encabezado HTTP Idempotency-Key tiene prioridad sobre el campo del cuerpo cuando se indican ambos.

Respuesta — 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"
}
CampoNotas
importIdEl identificador de plataforma al que hace referencia en cada llamada posterior.
uploadUrlURL de duración limitada para la carga mediante PUT.
headersUn mapa de encabezados HTTP que su PUT debe incluir.
s3KeyLa clave de almacenamiento bajo la que se guardará el archivo.
reusedtrue si la respuesta es el resultado de deduplicación de una Idempotency-Key anterior.
statusUrl / commitUrlURL de conveniencia para el ciclo de vida que sigue.

Códigos de estado

EstadoSobreDesencadenante
202 Acceptedcomo arribaFila de importación creada.
400 Bad Requesterrors[] (path/message)Fallo de validación del cuerpo.
400 Bad Request{ error, code: "UNKNOWN_KIND", allowed: [...] }kind no es uno de los seis tipos de préstamo.
409 Conflict{ error, code: "IDEMPOTENCY_KEY_REUSED", importId, mismatchedFields }La Idempotency-Key ya se usó para una importación con parámetros distintos.

Carga del archivo

Una vez que dispone de una uploadUrl, envíe el archivo directamente a ella mediante PUT. Reenvíe todos los encabezados del mapa headers de la respuesta; la firma de la URL los cubre y, de lo contrario, la carga se rechaza.

curl -X PUT "$UPLOAD_URL" \
  -H "<header-name>: <header-value>" \
  --data-binary @your-file.ndjson

La carga va directamente al almacenamiento; no pasa por la API. El formato del archivo es el mismo formato de transmisión NDJSON documentado en la página de NDJSON masivo, sin límite de filas.

POST /api/v1/monitoring/loan/imports/{id}/commit

Cuando el PUT haya terminado, llame a commit para indicar a la plataforma que la carga se ha completado. La plataforma confirma que el archivo existe, cambia la fila de importación de pending_upload a queued y pone en cola el worker.

Solicitud

Sin cuerpo. Idempotency-Key es implícita — una segunda confirmación sobre una fila que ya no está en pending_upload no tiene efecto y devuelve el estado actual.

Respuestas

200 OK:

{ "importId": "1234abcd-...", "status": "queued" }
EstadoSobreDesencadenante
200 OK{ importId, status }La confirmación se completó, o la fila ya había superado pending_upload (idempotente).
404 Not FoundestándarLa importación no existe o pertenece a otra organización.
409 Conflict{ error, code: "COMMIT_FAILED" }La plataforma no encontró el archivo cargado — normalmente porque la carga nunca se produjo o aún no ha terminado. Reintente la confirmación cuando la carga se complete.

GET /api/v1/monitoring/loan/imports/{id}

Lee el estado actual, los recuentos y el resumen de errores de una importación. Es el endpoint que su cliente consulta periódicamente para supervisar el progreso.

Solicitud

ParámetroPosiciónObligatorioNotas
idrutasíEl UUID de plataforma de la importación.
errorsconsultanotrue cambia al modo de errores paginados (véase más abajo).

Respuesta — modo predeterminado

{
  "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 es un pequeño resumen incrustado — totales por código de error y hasta diez filas de muestra. Para obtener la lista completa por fila, cambie al modo de errores paginados.

Respuesta — ?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
}
CampoNotas
rowNumberÍndice de línea, empezando en 1, en el NDJSON cargado.
errorCodeLos valores habituales incluyen parse_error (la línea no era JSON válido), validation_error (el esquema rechazó la fila), portfolio_mismatch (el portfolioId de la fila no coincide con el ancla de la importación) y processor_error (un fallo inesperado del manejador). Consulte errores y códigos de estado para ver la lista consolidada.
errorMessageResumen del fallo legible por humanos.
rawRowLa línea NDJSON original, conservada tal cual para la depuración.

limit tiene un valor predeterminado de 20, con un máximo de 100. offset tiene un valor predeterminado de 0. La paginación recorre la lista de errores persistida en orden de rowNumber, por lo que un cursor estable es offset += limit.

Códigos de estado

EstadoDesencadenante
200 OKLa fila existe en su organización.
400 Bad Requestlimit u offset mal formados cuando se usa ?errors=true.
404 Not FoundFila no encontrada o de otra organización.

GET /api/v1/monitoring/loan/imports

Lista las importaciones de préstamos del llamante, de la más reciente a la más antigua.

Solicitud

ParámetroPosiciónObligatorioRestricción
statusconsultanoUno de los siete estados del ciclo de vida.
kindconsultanoUno de los seis tipos de préstamo.
limitconsultano1-100; valor predeterminado 20.
offsetconsultanoNo negativo; valor predeterminado 0.

Respuesta

{
  "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}

Cancela una importación en curso. El worker se detiene en el siguiente límite de bloque; las filas ya almacenadas se conservan. Cancelar una fila que ya está en un estado terminal (succeeded, partial, failed o cancelled) no tiene efecto y devuelve el estado existente.

Respuestas

200 OK:

{ "importId": "1234abcd-...", "status": "cancelled" }
EstadoDesencadenante
200 OKCancelación aplicada o la fila ya estaba en un estado terminal.
404 Not FoundFila no encontrada o de otra organización.

Tipos

El campo kind de la solicitud de inicio determina el esquema con el que se valida cada fila y qué entidad recibe las filas. Los seis tipos se corresponden uno a uno con las entidades:

TipoEntidadEsquema
borrowerborrowersIgual que POST /borrowers.
loanloansIgual que POST /loans.
scheduled_repaymentscheduled_repaymentsEsquema de reembolso programado.
actual_paymentactual_paymentsIgual que POST /payments.
collateralcollateralEsquema de garantía.
collateral_valuationcollateral_valuationsEsquema de valoración de garantía.

Un kind que no figura en esta lista devuelve 400 UNKNOWN_KIND con los valores permitidos indicados en la respuesta, de modo que un error tipográfico se puede corregir sin recurrir al ensayo y error.

Cuándo usar esta superficie

Use importaciones asíncronas cuando:

  • Está cargando un archivo histórico — las cargas históricas típicas alcanzan millones de filas.
  • Su lote supera cualquiera de los límites de NDJSON masivo (10 000 filas o 10 MB).
  • Desea la opción de cancelar a mitad de la carga — NDJSON masivo no tiene superficie de cancelación porque la propia solicitud es la carga.
  • Su cliente tolera la consulta periódica — no hay notificación push cuando una importación se completa.

Para lotes operativos pequeños que caben en una sola solicitud síncrona, NDJSON masivo es la vía más sencilla.