Visão geral
Conceitos do Nexus e o fluxo de integração, do dataset ao match.
Conceitos
| Termo | O que é |
|---|---|
| Tenant | Sua conta no Nexus. Todo dado (datasets, regras, jobs, matches) pertence a um tenant e só é visível para ele. |
| Chave de API | Credencial do tenant (nxk_...) com escopo read, write ou admin. Ver Autenticação. |
| Dataset | Base de registros com schema tipado: campos, tipos, normalização e o campo que identifica cada registro (external_id). Ver Datasets. |
| Registro | Uma linha de um dataset: uma nota fiscal, um pagamento, uma venda. Registros são imutáveis depois de carregados. |
| Ingestão | Um envio de registros para um dataset, inline ou por arquivo, processado de forma assíncrona. Ver Ingestão. |
| Ruleset | Regra 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. |
| Job | Execuçã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. |
| Match | Resultado da conciliação: os registros de cada lado, o score e o status (matched, possible, partial, confirmed, rejected, reverted). |
| Gatilho | Cria um job sozinho sempre que uma ingestão adiciona registros a um dos datasets do par. Ver Gatilhos. |
| Workflow | Sequência de etapas, cada uma com seu ruleset, em que uma etapa pode usar o resultado da anterior. Ver Workflows. |
| Webhook | Endpoint 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.

