Openi DeveloperDeveloper
Guia de integração

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:

CaminhoQuando usarComo
InlineAté 20 mil registros e 12 MiB por chamadaOs registros vão no corpo, em records
ArquivoQualquer volumeNDJSON 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, tab ou pipe.
  • Os valores seguem os tipos do dataset: decimal com ponto e sem separador de milhar (1234.56), date como YYYY-MM-DD, timestamp em 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íticaEfeito
reject_all (padrão)Nada é carregado. A ingestão termina failed
skip_invalidAs 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

statusSignificado
awaiting_uploadIngestão por arquivo esperando o upload e o /complete
queuedNa fila do processamento
processingSendo processada
completedConcluída; veja stats
failedNada 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.

On this page