Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

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.

EstadoSignificado
pending_uploadA linha de importação existe; a URL de upload com prazo de validade está ativa; a plataforma ainda não viu o arquivo.
queuedO commit foi bem-sucedido; o worker ainda não pegou o arquivo.
processingO worker está lendo o arquivo linha a linha.
succeededTodas as linhas foram armazenadas.
partialO arquivo foi totalmente processado, mas pelo menos uma linha falhou.
failedUm erro fatal interrompeu o processamento antes da conclusão (por exemplo, gzip malformado, arquivo enviado ausente, erro interno do worker).
cancelledO 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étodoCaminhoFinalidade
POST/api/v1/monitoring/loan/importsIniciar uma nova importação; receber uma URL de upload com prazo de validade.
POST/api/v1/monitoring/loan/imports/{id}/commitFinalizar 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=truePaginar os erros por linha.
GET/api/v1/monitoring/loan/importsListar 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

CampoTipoObrigatórioRestrição
kindenumsimUm dos seis tipos.
filenamestringsim1 a 255 caracteres; apenas para exibição.
sizeBytesintegersimInteiro positivo; corresponde ao tamanho do arquivo que você pretende enviar.
portfolioIdstring UUID | nullnãoSubstituição opcional; as linhas do corpo continuam trazendo o seu próprio.
idempotencyKeystring | nullnãoO cabeçalho é preferível; o campo do corpo é uma alternativa.
dryRunbooleannãotrue executa a validação sem colocar na fila.
metadataobject | nullnãoRepasse literal.
rowCountDeclaredinteger | nullnãoInformativo — 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"
}
CampoObservações
importIdO identificador da plataforma que você usa em todas as chamadas seguintes.
uploadUrlURL com prazo de validade para o upload via PUT.
headersUm mapa de cabeçalhos HTTP que o seu PUT deve incluir.
s3KeyA chave de armazenamento sob a qual o arquivo ficará.
reusedtrue se a resposta for o resultado da deduplicação de um Idempotency-Key anterior.
statusUrl / commitUrlURLs de conveniência para o ciclo de vida que se segue.

Códigos de status

StatusEnvelopeGatilho
202 Acceptedcomo acimaLinha de importação criada.
400 Bad Requesterrors[] (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.ndjson

O 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" }
StatusEnvelopeGatilho
200 OK{ importId, status }O commit foi bem-sucedido, ou a linha já tinha passado de pending_upload (idempotente).
404 Not FoundpadrãoA 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âmetroPosiçãoObrigatórioObservações
idcaminhosimO UUID da plataforma da importação.
errorsquerynãotrue 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
}
CampoObservações
rowNumberÍndice da linha no NDJSON enviado, começando em 1.
errorCodeValores 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.
errorMessageResumo legível da falha.
rawRowA 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

StatusGatilho
200 OKA linha existe na sua organização.
400 Bad Requestlimit ou offset malformado quando ?errors=true.
404 Not FoundLinha 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âmetroPosiçãoObrigatórioRestrição
statusquerynãoUm dos sete estados do ciclo de vida.
kindquerynãoUm dos seis tipos de empréstimo.
limitquerynão1 a 100; padrão 20.
offsetquerynãoNã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" }
StatusGatilho
200 OKCancelamento aplicado, ou a linha já estava em estado terminal.
404 Not FoundLinha 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:

TipoEntidadeSchema
borrowerborrowersIgual a POST /borrowers.
loanloansIgual a POST /loans.
scheduled_repaymentscheduled_repaymentsSchema de parcela programada.
actual_paymentactual_paymentsIgual a POST /payments.
collateralcollateralSchema de garantia.
collateral_valuationcollateral_valuationsSchema 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.