Openi DeveloperDeveloper
Guia de integração

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 como trehsholds.
  • 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

RecursoTipo do id
Datasets, rulesets, workflows, jobs, gatilhos, webhooksUUID (string)
Registros, ingestões, matches, entregas de webhookInteiro (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"
Endpointlimit (padrão / máximo)Ordem
GET /v1/datasets50 / 100Criação
GET /v1/datasets/{id}/records100 / 500Ordem de carga
GET /v1/datasets/{id}/ingestions50 / 100Mais recentes primeiro
GET /v1/jobs50 / 100Mais recentes primeiro
GET /v1/jobs/{id}/matches100 / 500Criação
GET /v1/matches50 / 200Mais recentes primeiro (order=asc inverte)
GET /v1/webhooks/{id}/deliveries50 / 100Mais 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, total vem 10000 e total_capped vem true.
  • 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,possible equivale a status=matched&status=possible.
  • Datas de filtro (created_from, created_to, ingested_from, ingested_to) usam YYYY-MM-DD em UTC, e os dois extremos são inclusivos: created_from=2026-09-01&created_to=2026-09-30 cobre setembro inteiro.
  • Parâmetro vazio é o mesmo que ausente.

Datas e valores

TipoNa resposta
Data e hora (created_at, finished_at...)RFC 3339 em UTC: 2026-10-08T14:03:12.481Z
Campo date de um registroYYYY-MM-DD
Campo timestamp de um registroRFC 3339 em UTC
Campo decimal de um registroString com as casas do scale: "100.50". Nunca ponto flutuante
amount_diff de um matchInteiro 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.

On this page