NDJSON em lote
A interface de NDJSON em lote aceita até dez mil linhas em uma única requisição HTTP síncrona, valida cada linha com os mesmos schemas usados pelas rotas de registro único e retorna um relatório de erros por linha. Use-a para lotes de fim de dia que cabem com folga em uma requisição HTTP; para cargas históricas ou lotes maiores, use importações assíncronas.
O formato de transmissão é JSON delimitado por quebra de linha (newline-delimited JSON): um objeto JSON válido por linha, sem vírgula no final, sem array em volta, sem envelope de abertura ou fechamento. Linhas em branco entre objetos são aceitas e ignoradas.
Rotas
Há uma rota por entidade. O schema aplicado a cada linha corresponde à entidade na URL.
| Método | Caminho | Entidade |
|---|---|---|
POST | /api/v1/monitoring/loan/bulk/borrowers | borrower |
POST | /api/v1/monitoring/loan/bulk/loans | loan |
POST | /api/v1/monitoring/loan/bulk/scheduled-repayments | scheduled_repayment |
POST | /api/v1/monitoring/loan/bulk/actual-payments | actual_payment |
POST | /api/v1/monitoring/loan/bulk/collateral | collateral |
POST | /api/v1/monitoring/loan/bulk/collateral-valuations | collateral_valuation |
Cada linha do corpo da requisição deve ser um objeto JSON válido que atenda ao schema da entidade, conforme documentado na página de registro único. Os schemas são idênticos; só o envelope de transmissão difere.
Requisição
POST /api/v1/monitoring/loan/bulk/loans HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/x-ndjson
Idempotency-Key: <opaque-key>Cabeçalhos e parâmetros de query:
| Nome | Posição | Obrigatório | Observações |
|---|---|---|---|
Authorization | cabeçalho | sim | PAT como Bearer. |
Content-Type | cabeçalho | não | application/x-ndjson recomendado; application/json é aceito. |
Idempotency-Key | cabeçalho | não | Altamente recomendado para lotes de produção. |
?dryRun=true | query | não | Executa a validação, pula as gravações. |
?portfolioId=<UUID> | query | sim | A âncora de tenant do lote; se ausente ou malformado, retorna 400 portfolio_id_required. |
A interface em lote lê portfolioId somente da query string; o campo de mesmo nome no corpo de cada linha é ignorado na camada que envolve o lote. Todas as linhas do corpo devem referenciar o mesmo portfólio.
O corpo é o próprio payload NDJSON — codificado em UTF-8 e terminado por uma única quebra de linha. Linhas além de dez mil ou corpos acima de dez megabytes são rejeitados — veja limites de tamanho.
Contrato por linha
Cada linha é validada de forma independente com o schema da entidade. As mesmas regras de uma gravação de registro único se aplicam por linha:
- Cada linha deve ter seu próprio UUID
ideportfolioId. IDs fornecidos pelo chamador são a chave de deduplicação por linha. - O lote inteiro compartilha o
Idempotency-Keyda requisição. Veja idempotência abaixo. metadataé por linha. Uma linha pode trazer seus próprios metadados de repasse; a plataforma os persiste literalmente.- As regras de moeda, datas, enums e valores monetários são idênticas às do registro único. Uma linha que falha na validação aparece como uma entrada no relatório de erros por linha com
code: "validation_failed".
Uma linha que falha na validação não interrompe o lote — a falha aparece como uma entrada em errors[] e as demais linhas continuam sendo processadas.
Resposta
200 OK é retornado para todo lote cuja requisição em si pôde ser interpretada, independentemente de quantas linhas individuais tiveram sucesso ou falharam. O corpo da resposta traz o relatório completo por linha:
{
"totalRows": 4,
"succeeded": 3,
"failed": 1,
"bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"reused": false,
"errors": [
{
"rowNumber": 2,
"code": "fk_violation",
"message": "borrowerId references a borrower that does not exist in this portfolio"
}
]
}| Campo | Tipo | Descrição |
|---|---|---|
totalRows | integer | O número de linhas não vazias no corpo. |
succeeded | integer | O número de linhas armazenadas. |
failed | integer | totalRows - succeeded. |
bronzeSubmissionId | UUID | O id do registro de envio único para todo o corpo NDJSON. Ausente em uma resposta de ?dryRun=true. |
reused | boolean | Presente e true apenas quando um Idempotency-Key correspondeu a um lote anterior e a resposta foi reconstruída; ausente caso contrário. |
dryRun | boolean | Presente e true apenas em uma resposta de ?dryRun=true; ausente caso contrário. |
errors[].rowNumber | integer | Índice da linha no corpo da requisição, começando em 1. |
errors[].code | enum | validation_failed | unique_violation | fk_violation | check_violation | db_error. |
errors[].message | string | Resumo legível; para validation_failed, os erros de validação são reunidos em uma única frase. |
O formato de erro por linha traz apenas rowNumber, code e message. Não há array fieldErrors por linha nem rawRow por linha — o NDJSON original é preservado literalmente no registro de envio, em vez de ser devolvido na resposta.
Um succeeded igual a 0 não é uma resposta de erro — o lote foi interpretado e a plataforma processou todas as linhas; o relatório informa que nada foi gravado. Um lote que de fato falhou (NDJSON malformado no corpo inteiro, corpo grande demais, portfólio desconhecido) retorna 4xx conforme a tabela abaixo.
Códigos de status
Os envelopes de erro de nível superior desta interface usam valores de code em minúsculas, diferentes dos códigos em maiúsculas usados pelas rotas de registro único. Os dois espaços de códigos são separados intencionalmente.
| Status | Envelope | Gatilho |
|---|---|---|
200 OK | relatório por linha | Lote processado; resultados por linha em errors[]. |
400 Bad Request | { error, code: "invalid_body", errors: [...] } | O corpo da requisição não pôde ser lido como texto. |
400 Bad Request | { error, code: "portfolio_id_required", fieldErrors: [...] } | ?portfolioId=<UUID> está ausente ou não é um UUID válido. |
400 Bad Request | { error, code: "invalid_json" } | Aparece dentro do relatório por linha, linha a linha — uma linha que não é JSON válido recebe uma entrada code: "invalid_json" em errors[]. O lote como um todo ainda retorna 200. |
404 Not Found | { error, code: "portfolio_not_found", fieldErrors: [...] } | O ?portfolioId= não existe como portfólio ativo na sua organização. |
413 Payload Too Large | { error, code: "batch_too_large", fieldErrors: [...] } | Veja limites de tamanho. |
Limites de tamanho
A interface em lote limita os payloads ao menor dos seguintes valores:
- Dez mil linhas não vazias. Linhas além disso são rejeitadas antes do início do processamento.
- Dez megabytes de corpo da requisição.
Uma requisição que excede qualquer um dos limites recebe 413 Payload Too Large:
{
"error": "batch payload exceeds 10485760 bytes; use the async import endpoint at /api/v1/monitoring/loan/imports",
"code": "batch_too_large",
"fieldErrors": [{ "path": "(body)", "message": "max 10485760 bytes" }]
}O envelope do limite de bytes e o do limite de linhas usam ambos code: "batch_too_large"; error e fieldErrors[].message distinguem o gatilho. O caminho canônico de recuperação é enviar o mesmo payload pelo fluxo de importações assíncronas, que faz o upload direto do arquivo e o processa de forma assíncrona, sem limite de linhas.
Idempotência
A interface em lote faz a deduplicação com base no Idempotency-Key no nível do envelope do lote. O funcionamento:
- Primeira chamada com a chave
K. O corpo é registrado como um único envio, todas as linhas são processadas e o relatório por linha é guardado junto com o envio. - Segunda chamada com a chave
K, mesmo corpo. Nenhum segundo registro, nenhuma reinserção. A plataforma retorna o relatório original comreused: true. - Segunda chamada com a chave
K, corpo diferente. A plataforma ainda retorna o relatório original — o envio original é a fonte de verdade. Um novo POST com corpo corrigido deve usar uma chave diferente.
Isso significa que um cliente que tenta novamente após uma falha de rede está seguro mesmo que o corpo da segunda requisição tenha sido truncado ou alterado no caminho — a plataforma retorna os resultados por linha do primeiro processamento bem-sucedido.
Registro de envio
Cada requisição em lote é registrada como um envio contendo todo o corpo NDJSON, e não um por linha. Uma linha reenviada nunca é armazenada duas vezes, porque um externalId é único dentro de um portfólio entre as linhas ativas.
O bronzeSubmissionId na resposta é o id do registro de envio; guarde-o junto com o seu registro local de envio para auditoria e conciliação.
Exemplo com cURL
cat <<'EOF' > batch.ndjson
{"id":"a1...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b1...","externalId":"L-001","principalAmount":"5000","currencyCode":"USD","interestRateApr":"0.18","disbursementDate":"2026-01-15","termMonths":12,"repaymentFrequency":"monthly","status":"active"}
{"id":"a2...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b2...","externalId":"L-002","principalAmount":"3000","currencyCode":"USD","interestRateApr":"0.20","disbursementDate":"2026-01-15","termMonths":24,"repaymentFrequency":"monthly","status":"active"}
{"id":"a3...","portfolioId":"ddf63d12-1234-5678-9abc-def012345678","borrowerId":"b3...","externalId":"L-003","principalAmount":"7500","currencyCode":"USD","interestRateApr":"0.22","disbursementDate":"2026-01-15","termMonths":18,"repaymentFrequency":"monthly","status":"active"}
EOF
curl -X POST "https://app.waafir.io/api/v1/monitoring/loan/bulk/loans?portfolioId=ddf63d12-1234-5678-9abc-def012345678" \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/x-ndjson" \
-H "Idempotency-Key: nightly-2026-01-15-loans" \
--data-binary @batch.ndjsonQuando escolher NDJSON em lote ou importações assíncronas
Escolha NDJSON em lote quando:
- O seu lote cabe em dez mil linhas e dez megabytes.
- Você quer um relatório imediato por linha na resposta HTTP.
- Você tolera uma requisição HTTP de longa duração — lotes normalmente terminam em poucos segundos, mas um lote grande com muitas consultas de chave estrangeira no banco de dados pode demorar mais.
Escolha importações assíncronas quando:
- O seu lote excede qualquer um dos limites de tamanho.
- Você está carregando um arquivo histórico de pagamentos, parcelas programadas ou tomadores — cargas históricas típicas chegam a milhões de linhas.
- Você quer manter a opção de cancelar uma carga em andamento.