Openi DeveloperDeveloper
Guia de integração

Visão geral

Conceitos do Nexus e o fluxo de integração, do dataset ao match.

Conceitos

TermoO que é
TenantSua conta no Nexus. Todo dado (datasets, regras, jobs, matches) pertence a um tenant e só é visível para ele.
Chave de APICredencial do tenant (nxk_...) com escopo read, write ou admin. Ver Autenticação.
DatasetBase de registros com schema tipado: campos, tipos, normalização e o campo que identifica cada registro (external_id). Ver Datasets.
RegistroUma linha de um dataset: uma nota fiscal, um pagamento, uma venda. Registros são imutáveis depois de carregados.
IngestãoUm envio de registros para um dataset, inline ou por arquivo, processado de forma assíncrona. Ver Ingestão.
RulesetRegra que diz como registros de dois datasets se relacionam: chaves de blocking, matchers em CEL, limiares e composição. Cada alteração publica uma versão imutável. Ver Rulesets e matching.
JobExecução de um ruleset sobre um par de datasets (ou de um workflow). Roda na fila e grava os matches. Ver Jobs e revisão.
MatchResultado da conciliação: os registros de cada lado, o score e o status (matched, possible, partial, confirmed, rejected, reverted).
GatilhoCria um job sozinho sempre que uma ingestão adiciona registros a um dos datasets do par. Ver Gatilhos.
WorkflowSequência de etapas, cada uma com seu ruleset, em que uma etapa pode usar o resultado da anterior. Ver Workflows.
WebhookEndpoint seu que recebe eventos assinados: ingestão concluída, job concluído, matches criados. Ver Webhooks.

Fluxo de integração

O exemplo concilia notas fiscais com pagamentos. Todas as chamadas usam a base https://nexus-v2.openi.com.br e o header Authorization: Bearer $NEXUS_API_KEY.

Crie os datasets

Um dataset por base. O schema define tipos e normalizações aplicadas uma vez, na ingestão. Os campos usados como chave de comparação devem ter index: true.

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": "valor", "type": "decimal", "scale": 2, "required": true},
      {"name": "vencimento", "type": "date", "required": true}
    ]
  }'

Crie da mesma forma o dataset pagamentos, com id_pagamento, doc_pagador, valor e data_pagamento. Guarde o id de cada um.

Envie os registros

Até 20 mil registros por chamada, inline. Volumes maiores vão por arquivo (ver Ingestão).

curl -s -X POST https://nexus-v2.openi.com.br/v1/datasets/<notas_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"}
  ]}'

A resposta é 202 com a ingestão em queued. Acompanhe com GET /v1/ingestions/{id} ou pelo evento ingestion.completed.

Crie o ruleset

O ruleset não referencia datasets: os campos são left.* e right.*, e o par de datasets é informado no job.

curl -s -X POST https://nexus-v2.openi.com.br/v1/rulesets \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "nf-x-pagamentos",
    "definition": {
      "thresholds": {"match": 90, "possible": 70},
      "ambiguity_margin": 3,
      "blocking": [{"name": "documento",
                    "keys": [{"left": "left.doc_tomador", "right": "right.doc_pagador"}],
                    "window": {"left": "left.vencimento", "right": "right.data_pagamento", "days": 15}}],
      "matchers": [
        {"name": "documento", "score": 40, "required": true, "expr": "left.doc_tomador == right.doc_pagador"},
        {"name": "valor", "score": 40, "expr": "closeness(left.valor, right.valor, 100)"},
        {"name": "data", "score": 20, "expr": "decay(days_between(left.vencimento, right.data_pagamento), 15)"}
      ]
    }
  }'

Rode o job

O ruleset é compilado contra os schemas dos dois datasets antes de o job entrar na fila. Campo inexistente ou tipo incompatível devolve 422 na hora.

curl -s -X POST https://nexus-v2.openi.com.br/v1/jobs \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"ruleset_id": "<ruleset_id>", "left_dataset_id": "<notas_id>", "right_dataset_id": "<pagamentos_id>"}'

Para conciliar a cada nova carga sem chamar este endpoint, crie um gatilho.

Consulte e revise os matches

curl -s "https://nexus-v2.openi.com.br/v1/jobs/<job_id>/matches?status=matched" \
  -H "Authorization: Bearer $NEXUS_API_KEY"

Matches possible ficam aguardando revisão: confirme com POST /v1/matches/{id}/confirm ou descarte com POST /v1/matches/{id}/reject. Os mesmos resultados chegam pelos eventos matches.created e matches.possible se você tiver um webhook cadastrado.

Console

A console em https://nexus-v2.openi.com.br/console/ mostra jobs, matches, datasets, registros, ingestões, regras, gatilhos e webhooks do tenant. O login é feito com a própria chave de API.

On this page