Importações assíncronas
A interface de importações assíncronas é o caminho para cargas históricas e para qualquer lote acima do limite de dez mil linhas ou dez megabytes do NDJSON em lote. O fluxo tem duas fases: você descreve o que pretende enviar, recebe uma URL de upload com prazo de validade, faz o PUT do arquivo diretamente para ela e depois pede à plataforma que faça o commit. A partir daí, um worker lê o arquivo linha a linha, captura os erros por linha e informa o progresso por meio de um endpoint de status.
As rotas apresentadas aqui são os pontos de entrada do domínio de empréstimos no fluxo de importação.
Ciclo de vida
O ciclo de vida tem sete estados. A maioria das cargas de produção passa por pending_upload → queued → processing → succeeded; os demais representam modos de falha.
| Estado | Significado |
|---|---|
pending_upload | A linha de importação existe; a URL de upload com prazo de validade está ativa; a plataforma ainda não viu o arquivo. |
queued | O commit foi bem-sucedido; o worker ainda não pegou o arquivo. |
processing | O worker está lendo o arquivo linha a linha. |
succeeded | Todas as linhas foram armazenadas. |
partial | O arquivo foi totalmente processado, mas pelo menos uma linha falhou. |
failed | Um erro fatal interrompeu o processamento antes da conclusão (por exemplo, gzip malformado, arquivo enviado ausente, erro interno do worker). |
cancelled | O chamador cancelou a importação; o worker parou no limite do próximo bloco (chunk). |
Uma linha que nunca sai de pending_upload representa uma URL de upload que foi emitida, mas nunca recebeu commit; essas linhas são removidas rotineiramente depois que o TTL da URL expira.
Rotas em resumo
| Método | Caminho | Finalidade |
|---|---|---|
POST | /api/v1/monitoring/loan/imports | Iniciar uma nova importação; receber uma URL de upload com prazo de validade. |
POST | /api/v1/monitoring/loan/imports/{id}/commit | Finalizar o upload, colocar o worker na fila. |
GET | /api/v1/monitoring/loan/imports/{id} | Ler status, contagens e o resumo de erros. |
GET | /api/v1/monitoring/loan/imports/{id}?errors=true | Paginar os erros por linha. |
GET | /api/v1/monitoring/loan/imports | Listar as importações de empréstimos do chamador. |
DELETE | /api/v1/monitoring/loan/imports/{id} | Cancelar uma importação em andamento. |
POST /api/v1/monitoring/loan/imports
Inicia uma nova importação. Retorna o id da importação, uma URL de upload com prazo de validade e os cabeçalhos de upload que o seu cliente deve repetir ao fazer o PUT do arquivo.
Corpo da requisição
| Campo | Tipo | Obrigatório | Restrição |
|---|---|---|---|
kind | enum | sim | Um dos seis tipos. |
filename | string | sim | 1 a 255 caracteres; apenas para exibição. |
sizeBytes | integer | sim | Inteiro positivo; corresponde ao tamanho do arquivo que você pretende enviar. |
portfolioId | string UUID | null | não | Substituição opcional; as linhas do corpo continuam trazendo o seu próprio. |
idempotencyKey | string | null | não | O cabeçalho é preferível; o campo do corpo é uma alternativa. |
dryRun | boolean | não | true executa a validação sem colocar na fila. |
metadata | object | null | não | Repasse literal. |
rowCountDeclared | integer | null | não | Informativo — melhora o relatório de progresso. |
O cabeçalho HTTP Idempotency-Key tem precedência sobre o campo do corpo quando ambos são informados.
Resposta — 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 | Observações |
|---|---|
importId | O identificador da plataforma que você usa em todas as chamadas seguintes. |
uploadUrl | URL com prazo de validade para o upload via PUT. |
headers | Um mapa de cabeçalhos HTTP que o seu PUT deve incluir. |
s3Key | A chave de armazenamento sob a qual o arquivo ficará. |
reused | true se a resposta for o resultado da deduplicação de um Idempotency-Key anterior. |
statusUrl / commitUrl | URLs de conveniência para o ciclo de vida que se segue. |
Códigos de status
| Status | Envelope | Gatilho |
|---|---|---|
202 Accepted | como acima | Linha de importação criada. |
400 Bad Request | errors[] (path/message) | Falha de validação do corpo. |
400 Bad Request | { error, code: "UNKNOWN_KIND", allowed: [...] } | kind não é um dos seis tipos de empréstimo. |
409 Conflict | { error, code: "IDEMPOTENCY_KEY_REUSED", importId, mismatchedFields } | A Idempotency-Key já foi usada em uma importação com parâmetros diferentes. |
Enviando o arquivo
Assim que tiver uma uploadUrl, faça o PUT do arquivo diretamente para ela. Repita todos os cabeçalhos do mapa headers da resposta; a assinatura da URL os cobre e, caso contrário, o upload é rejeitado.
curl -X PUT "$UPLOAD_URL" \
-H "<header-name>: <header-value>" \
--data-binary @your-file.ndjsonO upload vai direto para o armazenamento; ele não passa pela API. O formato do arquivo é o mesmo formato de transmissão NDJSON documentado na página de NDJSON em lote, sem limite de linhas.
POST /api/v1/monitoring/loan/imports/{id}/commit
Depois que o PUT terminar, chame o commit para informar à plataforma que o upload está completo. A plataforma confirma que o arquivo existe, muda a linha de importação de pending_upload para queued e coloca o worker na fila.
Requisição
Sem corpo. O Idempotency-Key é implícito — um segundo commit em uma linha que não está em pending_upload não tem efeito e retorna o estado atual.
Respostas
200 OK:
{ "importId": "1234abcd-...", "status": "queued" }| Status | Envelope | Gatilho |
|---|---|---|
200 OK | { importId, status } | O commit foi bem-sucedido, ou a linha já tinha passado de pending_upload (idempotente). |
404 Not Found | padrão | A importação não existe ou pertence a outra organização. |
409 Conflict | { error, code: "COMMIT_FAILED" } | A plataforma não encontrou o arquivo enviado — normalmente o upload nunca aconteceu ou ainda não terminou. Repita o commit depois que o upload for concluído. |
GET /api/v1/monitoring/loan/imports/{id}
Lê o status atual, as contagens e o resumo de erros de uma importação. Este é o endpoint de consulta que o seu cliente chama para acompanhar o progresso.
Requisição
| Parâmetro | Posição | Obrigatório | Observações |
|---|---|---|---|
id | caminho | sim | O UUID da plataforma da importação. |
errors | query | não | true muda para o modo de erros paginados (veja abaixo). |
Resposta — modo padrão
{
"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 é um pequeno resumo embutido — totais por código de erro e até dez linhas de exemplo. Para a lista completa por linha, mude para o modo de erros paginados.
Resposta — ?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 | Observações |
|---|---|
rowNumber | Índice da linha no NDJSON enviado, começando em 1. |
errorCode | Valores comuns incluem parse_error (a linha não era JSON válido), validation_error (o schema rejeitou a linha), portfolio_mismatch (o portfolioId da linha não corresponde à âncora da importação) e processor_error (uma falha inesperada do handler). Veja erros e códigos de status para a lista consolidada. |
errorMessage | Resumo legível da falha. |
rawRow | A linha NDJSON original, preservada literalmente para depuração. |
limit tem padrão 20, máximo 100. offset tem padrão 0. A paginação percorre a lista persistida de erros na ordem de rowNumber, então um cursor estável é offset += limit.
Códigos de status
| Status | Gatilho |
|---|---|
200 OK | A linha existe na sua organização. |
400 Bad Request | limit ou offset malformado quando ?errors=true. |
404 Not Found | Linha não encontrada ou de outra organização. |
GET /api/v1/monitoring/loan/imports
Lista as importações de empréstimos do chamador, das mais recentes para as mais antigas.
Requisição
| Parâmetro | Posição | Obrigatório | Restrição |
|---|---|---|---|
status | query | não | Um dos sete estados do ciclo de vida. |
kind | query | não | Um dos seis tipos de empréstimo. |
limit | query | não | 1 a 100; padrão 20. |
offset | query | não | Não negativo; padrão 0. |
Resposta
{
"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 uma importação em andamento. O worker para no limite do próximo bloco; as linhas já armazenadas permanecem. Cancelar uma linha que já está em estado terminal (succeeded, partial, failed ou cancelled) não tem efeito e retorna o estado existente.
Respostas
200 OK:
{ "importId": "1234abcd-...", "status": "cancelled" }| Status | Gatilho |
|---|---|
200 OK | Cancelamento aplicado, ou a linha já estava em estado terminal. |
404 Not Found | Linha não encontrada ou de outra organização. |
Tipos
O campo kind na requisição de início determina o schema com o qual cada linha é validada e qual entidade recebe as linhas. Os seis tipos correspondem um a um às entidades:
| Tipo | Entidade | Schema |
|---|---|---|
borrower | borrowers | Igual a POST /borrowers. |
loan | loans | Igual a POST /loans. |
scheduled_repayment | scheduled_repayments | Schema de parcela programada. |
actual_payment | actual_payments | Igual a POST /payments. |
collateral | collateral | Schema de garantia. |
collateral_valuation | collateral_valuations | Schema de avaliação de garantia. |
Um kind que não esteja nesta lista retorna 400 UNKNOWN_KIND com os valores permitidos listados na resposta, de modo que um erro de digitação pode ser corrigido sem tentativa e erro.
Quando usar esta interface
Use importações assíncronas quando:
- Você está carregando um arquivo histórico — cargas históricas típicas têm milhões de linhas.
- O seu lote excede qualquer um dos limites do NDJSON em lote (10 000 linhas ou 10 MB).
- Você quer a opção de cancelar no meio da carga — o NDJSON em lote não tem interface de cancelamento porque a própria requisição é a carga.
- O seu cliente tolera fazer consultas periódicas (polling) — não há notificação push quando uma importação termina.
Para pequenos lotes operacionais que cabem em uma única requisição síncrona, o NDJSON em lote é o caminho mais simples.