Openi DeveloperDeveloper
Guia de integração

Datasets

Schema tipado, normalização, campos calculados, evolução do schema e consulta de registros.

Um dataset é uma base de registros com schema fixo. Os tipos e as normalizações são aplicados uma vez, na ingestão, e as regras de conciliação são validadas contra esse schema antes de cada job.

Criar um dataset

curl -s -X POST https://nexus-v2.openi.com.br/v1/datasets \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "notas-fiscais",
    "external_id": "numero_nf",
    "fields": [
      {"name": "numero_nf", "type": "string", "required": true},
      {"name": "doc_tomador", "type": "string", "required": true, "normalize": ["digits"], "index": true},
      {"name": "razao_social", "type": "string", "normalize": ["trim", "upper", "unaccent"]},
      {"name": "valor", "type": "decimal", "scale": 2, "required": true},
      {"name": "vencimento", "type": "date", "required": true}
    ],
    "computed": [
      {"name": "doc_raiz", "from": "doc_tomador", "normalize": ["cnpj_root"], "index": true}
    ]
  }'
AtributoRegra
nameÚnico no tenant. Letras minúsculas, dígitos, - e _, começando por letra ou dígito, até 100 caracteres
external_idNome do campo que identifica cada registro. Precisa ser um campo string ou integer obrigatório
fieldsPelo menos um campo. Nomes em minúsculas, dígitos e _, começando por letra, até 63 caracteres
computedOpcional. Campos derivados de um campo string (ver Campos calculados)

Um dataset tem no máximo 200 campos, somando fields e computed.

Tipos

typeNa ingestãoNas regras (CEL)
stringTextostring
integerNúmero inteiro ou string com dígitos (64 bits)int
decimalNúmero ou string com ponto decimal, sem separador de milhar, com no máximo scale casas: "1234.56". Nada é arredondadoint, em unidades mínimas (100.50 com scale: 2 vira 10050)
booleantrue/false, ou as strings "true", "false", "1", "0"bool
dateYYYY-MM-DDtimestamp
timestampRFC 3339 com fuso: 2026-09-24T15:04:05-03:00timestamp

decimal exige scale (0 a 9). O valor é guardado como inteiro em unidades mínimas, então somas e comparações de dinheiro são exatas. Nas regras, tolerâncias de valor também são em unidades mínimas: closeness(left.valor, right.valor, 100) tolera R$ 1,00 com scale: 2.

Normalização

normalize vale só para campos string e aplica as operações na ordem da lista, uma vez, na ingestão. O valor gravado (e visto pelas regras e pela API) já é o normalizado.

OperaçãoEfeitoExemplo
trimRemove espaços nas pontas" ACME " → "ACME"
upperMaiúsculas"Acme" → "ACME"
lowerMinúsculas"Acme" → "acme"
unaccentRemove acentos"José" → "Jose"
digitsMantém só dígitos"12.345.678/0001-90" → "12345678000190"
alnumMantém só letras e dígitos"NF-001/A" → "NF001A"
cnpj_rootRaiz do CNPJ: os 8 primeiros caracteres alfanuméricos, em maiúsculas"12.345.678/0001-90" → "12345678"

Normalize as chaves de comparação na ingestão, e não nas regras: dois documentos só casam por igualdade se chegarem ao mesmo formato.

Campos calculados

Um campo em computed é derivado de um campo string (from) com uma lista de normalizações, e é sempre string. Use para ter duas formas do mesmo dado: o documento completo e a raiz do CNPJ, por exemplo. O Nexus preenche o campo calculado a partir do campo de origem. Não envie campos calculados na ingestão: eles são rejeitados como campo fora do schema.

Índices

index: true cria um índice no campo. Marque os campos usados como chave de blocking e de group_by na composição; eles definem quais registros o job carrega e compara.

Evoluir o schema

O schema só cresce. PATCH /v1/datasets/{id} renomeia o dataset e adiciona campos, sempre opcionais:

curl -s -X PATCH https://nexus-v2.openi.com.br/v1/datasets/<id> \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"add_fields": [{"name": "centro_custo", "type": "string", "normalize": ["upper"]}]}'

Campos existentes não mudam de tipo nem são removidos, e registros já carregados ficam com o campo novo vazio. Para mudar a estrutura, crie outro dataset.

Registros

Registros são imutáveis: uma vez carregados, não são alterados nem apagados pela API. Carregar de novo o mesmo external_id não sobrescreve o registro (ver duplicados).

Listar

GET /v1/datasets/{id}/records lista na ordem de carga, com filtros combinados por E:

ParâmetroFiltra
qPrefixo do external_id, sem diferenciar maiúsculas
filtercampo:operador:valor. Pode repetir
stateopen (sem match efetivo) ou reconciled (com match efetivo). Com ruleset_id, considera só aquele ruleset; sem, qualquer ruleset
ingestion_idSó os registros carregados por uma ingestão
ingested_from, ingested_toDia da carga, YYYY-MM-DD, inclusivos

Operadores de filter:

OperadorTiposExemplo
eq, neTodosstatus:eq:EMITIDA
contains, prefixstring, sem diferenciar maiúsculasrazao_social:contains:acme
gt, gte, lt, lteinteger, decimal, date, timestampvalor:gte:1000.00
empty, presentTodoscentro_custo:empty
curl -s -G https://nexus-v2.openi.com.br/v1/datasets/<id>/records \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  --data-urlencode 'filter=vencimento:gte:2026-09-01' \
  --data-urlencode 'filter=valor:gt:500' \
  --data-urlencode 'state=open'
{
  "data": [
    {
      "id": 184467,
      "external_id": "NF-1",
      "ingestion_id": 912,
      "ingested_on": "2026-10-08",
      "values": {
        "numero_nf": "NF-1",
        "doc_tomador": "12345678000190",
        "razao_social": "ACME LTDA",
        "valor": "100.50",
        "vencimento": "2026-09-30",
        "doc_raiz": "12345678"
      }
    }
  ],
  "next_cursor": 184467,
  "total": 1342
}

Detalhar

GET /v1/datasets/{id}/records/{record_id} devolve o registro e todos os matches de que ele participa, em qualquer ruleset e status.

Datasets derivados

Datasets com kind: "derived" são criados por etapas de workflow que projetam seus matches. Eles têm source_job_id e expiram em 30 dias (expires_at).

Retenção

Registros ficam disponíveis por 13 meses, contados pelo mês de carga, e matches por 13 meses a partir do mês em que foram criados. Depois disso, o mês inteiro é arquivado e sai da API. record_count conta só os registros ainda disponíveis.

On this page