Visão geral

Este guia descreve, em ordem prática, como uma aplicação cliente integra com o Nexus para:

autenticar requisições;
ingerir dados (criar data source → configurar dataset + fields → carregar dados por webhook, arquivo, Postgres, OpenFinance ou Openi → criar rule set);
executar matching e consultar resultados;
receber eventos por webhook de saída.

Glossário rápido

Termo	O que é
Data source	Origem de dados configurada no Nexus. Pode ser `webhook`, `postgres`, `file`, `openfinance` ou `openi`.
Slug	Identificador público da URL de ingestão (`/hooks/{slug}`).
Dataset	Coleção de registros (records) extraídos de um data source. É a unidade usada pelos rule sets.
Field	Chave canônica extraída do payload (ex.: `amount`, `doc`). É o que as regras referenciam.
Record	Um registro individual dentro de um dataset (uma transação, uma nota fiscal, etc.).
Rule set	Regra de matching que casa records de dois datasets (left × right) por meio de uma expressão JSONata + parâmetros de pontuação.
Match	Resultado da comparação de um par (record left, record right) sob um rule set. Possui `score` e `decision`.

Convenções

<API_BASE> é a URL base do Nexus (ex.: https://nexus-api.openi.com.br).
Todos os corpos de requisição/resposta são application/json salvo indicação em contrário.
Uploads de arquivos usam multipart/form-data.
Erros seguem o envelope { "error": { "code": "<CODE>", "message": "<descrição>" } } com o status HTTP apropriado. Exceção: 409 WINDOW_EXPIRED em /hooks/{slug} retorna { "ok": false, "code": "WINDOW_EXPIRED" } (sem o campo error).
Datas são ISO 8601 em UTC.
UUIDs são v4.