Ingestão
Envio de registros inline ou por arquivo, validação, erros por linha, duplicados e acompanhamento.
Toda carga de registros é uma ingestão, criada em POST /v1/datasets/{id}/ingestions (escopo write). Há dois caminhos:
| Caminho | Quando usar | Como |
|---|---|---|
| Inline | Até 20 mil registros e 12 MiB por chamada | Os registros vão no corpo, em records |
| Arquivo | Qualquer volume | NDJSON ou CSV enviado direto para uma URL de upload |
Nos dois casos o processamento é assíncrono e atômico: a ingestão carrega tudo o que for aceito numa transação só, ou não carrega nada.
Inline
curl -s -X POST https://nexus-v2.openi.com.br/v1/datasets/<dataset_id>/ingestions \
-H "Authorization: Bearer $NEXUS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: notas-2026-10-08' \
-d '{"records": [
{"numero_nf": "NF-1", "doc_tomador": "12.345.678/0001-90", "valor": "100.50", "vencimento": "2026-09-30"},
{"numero_nf": "NF-2", "doc_tomador": "98.765.432/0001-10", "valor": 2500, "vencimento": "2026-10-05"}
]}'Antes de aceitar, a API confere cada registro contra o schema. Campo que não existe no dataset ou campo obrigatório ausente devolve 422 na hora, com a posição de cada problema, e nada é criado:
{
"title": "Unprocessable Entity",
"status": 422,
"detail": "records do not match the dataset schema",
"errors": [{ "location": "body.records[1].cnpj", "message": "field is not in the dataset schema" }]
}Os valores em si (formato de data, casas decimais, inteiro válido) são validados no processamento, conforme a política de erros.
Arquivo
Crie a ingestão com o formato
curl -s -X POST https://nexus-v2.openi.com.br/v1/datasets/<dataset_id>/ingestions \
-H "Authorization: Bearer $NEXUS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"format": "csv", "csv_delimiter": "semicolon", "error_policy": "skip_invalid"}'A resposta traz status: "awaiting_upload" e upload_url.
Envie o arquivo para a upload_url
curl -s -X PUT --upload-file notas.csv '<upload_url>'A URL vale por uma hora. Se expirar, GET /v1/ingestions/{id} devolve uma nova enquanto a ingestão aguarda o upload.
Coloque na fila
curl -s -X POST https://nexus-v2.openi.com.br/v1/ingestions/<ingestion_id>/complete \
-H "Authorization: Bearer $NEXUS_API_KEY"Sem arquivo enviado, a resposta é 422. Se a ingestão não estiver aguardando upload (já foi enviada para a fila), é 409.
Envie records ou format, nunca os dois: a combinação, ou a falta dos dois, devolve 422.
Formatos
- NDJSON: um objeto JSON por linha, com os mesmos valores aceitos inline.
- CSV: a primeira linha é o cabeçalho, com os nomes dos campos. Célula vazia é valor ausente. Células entre aspas podem conter o delimitador e quebras de linha; aspas dentro delas são escritas em dobro (
"").csv_delimiter:comma(padrão),semicolon,taboupipe. - Os valores seguem os tipos do dataset:
decimalcom ponto e sem separador de milhar (1234.56),datecomoYYYY-MM-DD,timestampem RFC 3339 com fuso. - Rejeitam a ingestão inteira, qualquer que seja a
error_policy: coluna do CSV ou campo do NDJSON fora do schema, coluna obrigatória ausente do cabeçalho, coluna repetida no cabeçalho, CSV malformado, arquivo vazio e linha acima de 4 MiB.
Erros por linha
error_policy decide o que acontece quando alguma linha tem valor inválido:
| Política | Efeito |
|---|---|
reject_all (padrão) | Nada é carregado. A ingestão termina failed |
skip_invalid | As linhas válidas são carregadas e as inválidas ficam de fora. A ingestão termina completed |
Nos dois casos, errors_report_url aponta para um NDJSON com uma linha por problema, válido por uma hora (cada GET gera um link novo):
{"line": 14, "field": "vencimento", "message": "expected a date as YYYY-MM-DD"}
{"line": 27, "field": "valor", "message": "value is required"}O relatório guarda até 10 mil problemas; acima disso, stats.errors_truncated vem true.
Duplicados
O external_id é único no dataset. Um registro cujo external_id já foi carregado, por esta ou por uma ingestão anterior, é ignorado sem erro e contado em stats.rows_duplicate. Registros nunca são sobrescritos, então reenviar um arquivo inteiro é seguro: só os registros novos entram.
Acompanhar
status | Significado |
|---|---|
awaiting_upload | Ingestão por arquivo esperando o upload e o /complete |
queued | Na fila do processamento |
processing | Sendo processada |
completed | Concluída; veja stats |
failed | Nada foi carregado; veja error e errors_report_url |
{
"id": 912,
"dataset_id": "0199a3f2-8a40-7e55-b1c3-4d2e6f8a9b01",
"status": "completed",
"source": "file",
"format": "csv",
"error_policy": "skip_invalid",
"stats": {
"rows_total": 1500,
"rows_valid": 1498,
"rows_rejected": 2,
"rows_inserted": 1450,
"rows_duplicate": 48
},
"errors_report_url": "https://...",
"created_at": "2026-10-08T14:00:02.113Z",
"started_at": "2026-10-08T14:00:05.870Z",
"finished_at": "2026-10-08T14:00:07.402Z"
}Em vez de consultar, cadastre um webhook para ingestion.completed e ingestion.failed. GET /v1/datasets/{id}/ingestions lista as ingestões do dataset, mais recentes primeiro, com filtro por status.
Uma ingestão concluída que carregou registros novos dispara os gatilhos do dataset.

