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.
| Estado | Significado |
|---|---|
pending_upload | La fila de importación existe; la URL de carga de duración limitada está activa; la plataforma aún no ha visto el archivo. |
queued | La confirmación se completó; el worker aún no ha recogido el archivo. |
processing | El worker está recorriendo el archivo fila por fila. |
succeeded | Se almacenaron todas las filas. |
partial | El archivo se procesó por completo, pero al menos una fila falló. |
failed | Un error fatal detuvo el procesamiento antes de completarse (p. ej., gzip mal formado, archivo cargado inexistente, error interno del worker). |
cancelled | El 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étodo | Ruta | Propósito |
|---|---|---|
POST | /api/v1/monitoring/loan/imports | Iniciar una importación nueva; recibir una URL de carga de duración limitada. |
POST | /api/v1/monitoring/loan/imports/{id}/commit | Finalizar 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=true | Paginar los errores por fila. |
GET | /api/v1/monitoring/loan/imports | Listar 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
| Campo | Tipo | Obligatorio | Restricción |
|---|---|---|---|
kind | enum | sí | Uno de los seis tipos. |
filename | cadena | sí | 1-255 caracteres; solo para visualización. |
sizeBytes | entero | sí | Entero positivo; coincide con el tamaño del archivo que pretende cargar. |
portfolioId | cadena UUID | null | no | Sustitución opcional; las filas del cuerpo siguen llevando la suya propia. |
idempotencyKey | cadena | null | no | Se prefiere el encabezado; el campo del cuerpo es una alternativa. |
dryRun | booleano | no | true ejecuta la validación sin poner en cola. |
metadata | objeto | null | no | Transferencia directa tal cual. |
rowCountDeclared | entero | null | no | Orientativo — 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"
}| Campo | Notas |
|---|---|
importId | El identificador de plataforma al que hace referencia en cada llamada posterior. |
uploadUrl | URL de duración limitada para la carga mediante PUT. |
headers | Un mapa de encabezados HTTP que su PUT debe incluir. |
s3Key | La clave de almacenamiento bajo la que se guardará el archivo. |
reused | true si la respuesta es el resultado de deduplicación de una Idempotency-Key anterior. |
statusUrl / commitUrl | URL de conveniencia para el ciclo de vida que sigue. |
Códigos de estado
| Estado | Sobre | Desencadenante |
|---|---|---|
202 Accepted | como arriba | Fila de importación creada. |
400 Bad Request | errors[] (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.ndjsonLa 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" }| Estado | Sobre | Desencadenante |
|---|---|---|
200 OK | { importId, status } | La confirmación se completó, o la fila ya había superado pending_upload (idempotente). |
404 Not Found | estándar | La 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ámetro | Posición | Obligatorio | Notas |
|---|---|---|---|
id | ruta | sí | El UUID de plataforma de la importación. |
errors | consulta | no | true 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
}| Campo | Notas |
|---|---|
rowNumber | Índice de línea, empezando en 1, en el NDJSON cargado. |
errorCode | Los 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. |
errorMessage | Resumen del fallo legible por humanos. |
rawRow | La 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
| Estado | Desencadenante |
|---|---|
200 OK | La fila existe en su organización. |
400 Bad Request | limit u offset mal formados cuando se usa ?errors=true. |
404 Not Found | Fila 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ámetro | Posición | Obligatorio | Restricción |
|---|---|---|---|
status | consulta | no | Uno de los siete estados del ciclo de vida. |
kind | consulta | no | Uno de los seis tipos de préstamo. |
limit | consulta | no | 1-100; valor predeterminado 20. |
offset | consulta | no | No 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" }| Estado | Desencadenante |
|---|---|
200 OK | Cancelación aplicada o la fila ya estaba en un estado terminal. |
404 Not Found | Fila 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:
| Tipo | Entidad | Esquema |
|---|---|---|
borrower | borrowers | Igual que POST /borrowers. |
loan | loans | Igual que POST /loans. |
scheduled_repayment | scheduled_repayments | Esquema de reembolso programado. |
actual_payment | actual_payments | Igual que POST /payments. |
collateral | collateral | Esquema de garantía. |
collateral_valuation | collateral_valuations | Esquema 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.