Padrões da API
Identificadores, paginação, datas, valores, corpo das requisições e idempotência.
Requisições
- Base URL:
https://nexus-v2.openi.com.br. Todos os caminhos começam com/v1. - Corpo em JSON (
Content-Type: application/json), limitado a 1 MiB. A criação de ingestão aceita até 12 MiB. Acima do limite, a resposta é413. - Os corpos são estritos: um campo que o endpoint não conhece devolve
422, em vez de ser ignorado. Isso pega erros de digitação comotrehsholds. - Ações que não são CRUD usam um segmento no fim do caminho:
POST /v1/jobs/{id}/cancel,POST /v1/matches/{id}/confirm.
Identificadores
| Recurso | Tipo do id |
|---|---|
| Datasets, rulesets, workflows, jobs, gatilhos, webhooks | UUID (string) |
| Registros, ingestões, matches, entregas de webhook | Inteiro (número no JSON) |
O external_id de um registro é o valor do campo que você escolheu como identificador no dataset (o número da nota, o id do pagamento). Ele é único dentro do dataset; o id numérico é atribuído pelo Nexus.
Paginação
As listagens que podem crescer usam cursor. Passe o next_cursor da resposta no parâmetro cursor da próxima chamada; quando next_cursor não vem, a página é a última.
curl -s "https://nexus-v2.openi.com.br/v1/datasets/<id>/records?limit=500" -H "Authorization: Bearer $NEXUS_API_KEY"
curl -s "https://nexus-v2.openi.com.br/v1/datasets/<id>/records?limit=500&cursor=184467" -H "Authorization: Bearer $NEXUS_API_KEY"| Endpoint | limit (padrão / máximo) | Ordem |
|---|---|---|
GET /v1/datasets | 50 / 100 | Criação |
GET /v1/datasets/{id}/records | 100 / 500 | Ordem de carga |
GET /v1/datasets/{id}/ingestions | 50 / 100 | Mais recentes primeiro |
GET /v1/jobs | 50 / 100 | Mais recentes primeiro |
GET /v1/jobs/{id}/matches | 100 / 500 | Criação |
GET /v1/matches | 50 / 200 | Mais recentes primeiro (order=asc inverte) |
GET /v1/webhooks/{id}/deliveries | 50 / 100 | Mais recentes primeiro |
Rulesets, workflows, gatilhos, webhooks e versões vêm inteiros, sem paginação.
Totais
GET /v1/datasets/{id}/records e GET /v1/matches trazem total, a contagem do que atende aos filtros:
- A contagem vai até 10.000. Acima disso,
totalvem10000etotal_cappedvemtrue. - Se contar levar mais de um segundo,
totalé omitido. A página de dados vem normalmente.
Filtros de listagem
- Listas de valores aceitam vírgula ou parâmetro repetido:
status=matched,possibleequivale astatus=matched&status=possible. - Datas de filtro (
created_from,created_to,ingested_from,ingested_to) usamYYYY-MM-DDem UTC, e os dois extremos são inclusivos:created_from=2026-09-01&created_to=2026-09-30cobre setembro inteiro. - Parâmetro vazio é o mesmo que ausente.
Datas e valores
| Tipo | Na resposta |
|---|---|
Data e hora (created_at, finished_at...) | RFC 3339 em UTC: 2026-10-08T14:03:12.481Z |
Campo date de um registro | YYYY-MM-DD |
Campo timestamp de um registro | RFC 3339 em UTC |
Campo decimal de um registro | String com as casas do scale: "100.50". Nunca ponto flutuante |
amount_diff de um match | Inteiro em unidades mínimas (centavos com scale: 2) |
Atributos opcionais sem valor são omitidos da resposta. Em values de um registro, campo sem valor vem null.
Idempotência
POST /v1/datasets/{id}/ingestions aceita o header Idempotency-Key (até 200 caracteres). Repetir a chamada com a mesma chave devolve a ingestão original, sem criar outra. A chave vale para o tenant inteiro: usá-la em outro dataset devolve 409. Use uma chave por lote lógico (ex.: pagamentos-2026-10-08) e repita com segurança depois de um timeout.
Mesmo sem a chave, um registro com external_id já carregado no dataset é ignorado e contado como duplicado. Ver Ingestão.

