Rulesets e matching
Como escrever um ruleset: blocking, matchers em CEL, pontuação, limiares, ambiguidade e versões.
Um ruleset descreve como registros de dois datasets se relacionam. Ele não aponta para datasets: os campos aparecem como left.campo e right.campo, e o par de datasets é escolhido em cada job. O mesmo ruleset serve para qualquer par cujos schemas tenham os campos que ele usa.
Estrutura
{
"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 }
},
{
"name": "raiz-cnpj",
"keys": [{ "left": "left.doc_raiz", "right": "right.doc_raiz" }],
"window": { "left": "left.vencimento", "right": "right.data_pagamento", "days": 15 }
}
],
"matchers": [
{ "name": "emitida", "score": 0, "required": true, "expr": "left.status == 'EMITIDA'" },
{ "name": "valor", "score": 50, "required": true, "expr": "closeness(left.valor, right.valor, 100)" },
{ "name": "data", "score": 30, "expr": "decay(days_between(left.vencimento, right.data_pagamento), 15)" },
{ "name": "nome", "score": 20, "expr": "token_similarity(left.razao_social, right.nome_pagador)" }
]
}
}| Atributo | Papel |
|---|---|
blocking | Quais pares são comparados. Pelo menos uma passada |
matchers | Como cada par é pontuado. Pelo menos um |
thresholds | A partir de que score o par vira matched ou possible |
ambiguity_margin | Distância mínima entre o melhor e o segundo melhor candidato para aceitar o match sem revisão |
composite | Opcional: conciliação 1:N, N:1 e N:M sobre o que o 1:1 deixou aberto. Ver Composição |
Blocking
Comparar todos os registros de um lado com todos do outro não escala. Cada passada de blocking define uma chave de igualdade: só são comparados pares em que os campos da chave são iguais.
keys: um ou mais pares de campos (left.xcomright.y). Com mais de um, todos precisam ser iguais (chave composta). Os dois campos de cada par têm o mesmo tipo (emdecimal, o mesmoscale) e, de preferência,index: trueno dataset.window(opcional): além da chave, as datas dos dois lados ficam a no máximodaysdias uma da outra (0 a 366). Vale para camposdateetimestamp.- As passadas rodam em ordem, e cada uma só vê os registros que as anteriores não conciliaram. Comece pela chave mais restritiva e afrouxe nas seguintes, como no exemplo: documento completo primeiro, raiz do CNPJ depois.
- Registro sem valor na chave ou na data da janela não entra na passada.
- Uma chave com mais de 5.000 candidatos do lado direito (um documento genérico, por exemplo) é pulada naquela passada e contada em
stats.steps[].truncated_keysdo job. Use uma chave mais seletiva ou uma janela menor.
As chaves usam o valor gravado, já normalizado. Normalize os documentos no dataset, e não na regra.
Matchers
Cada matcher tem um nome, um peso (score) e uma expressão CEL que devolve bool (verdadeiro vale 1) ou double entre 0 e 1:
score do par = Σ (score do matcher × valor da expressão)Os pesos não precisam somar 100, mas somar 100 deixa os limiares fáceis de ler. A API recusa um thresholds.match acima do maior score possível.
required: true: se a expressão der 0, o par é descartado, qualquer que seja o resto. Obrigatórios são avaliados primeiro.score: 0comrequired: trueé um filtro: não pontua, só elimina pares. No exemplo, só notas emitidas entram.- Campo sem valor nunca soma: qualquer expressão que dependa dele vale 0 (e descarta o par, se o matcher for obrigatório). Assim, duas notas sem documento não contam como "mesmo documento". Para aceitar a ausência de propósito, use
present():!present(left.autorizacao) || left.autorizacao == right.autorizacao. breakdownde cada match mostra o valor que cada matcher deu, para calibrar pesos.
Tipos nas expressões
| Campo do dataset | Tipo em CEL | Atenção |
|---|---|---|
string | string | Valor já normalizado |
integer | int | |
decimal | int | Em unidades mínimas: 100.50 com scale: 2 vale 10050. Tolerâncias também: 100 é R$ 1,00 |
boolean | bool | |
date, timestamp | timestamp |
Funções
| Função | Retorno |
|---|---|
closeness(a, b, tol) | 1 quando a == b, caindo em linha reta até 0 quando a diferença chega a tol. Aceita int ou double |
within(a, b, tol) | bool: diferença de no máximo tol (int) |
days_between(d1, d2) | int: dias entre as duas datas, sempre positivo |
decay(x, max) | 1 − x/max, limitado entre 0 e 1. Combine com days_between para pontuar proximidade de datas |
similarity(a, b) | Similaridade Jaro-Winkler entre 0 e 1 |
token_similarity(a, b) | Fração das palavras do texto menor que aparecem no maior, entre 0 e 1. Boa para razão social com palavras fora de ordem ou a mais |
month(d) | Competência AAAA-MM |
abs(x) | Valor absoluto |
sum(lista), min(lista), max(lista) | Agregações de int (e min/max de datas), usadas na composição |
present(campo) | bool: o campo tem valor |
Além delas, os operadores e macros padrão do CEL (==, &&, ||, !, in, ?:, size, exists, all, map, filter) e os métodos de string contains, startsWith, endsWith, matches, substring, charAt, indexOf, lastIndexOf, lowerAscii, upperAscii, trim, replace, split, reverse e size.
left.doc_tomador == right.doc_pagador
closeness(left.valor, right.valor, 500)
within(left.valor, right.valor, 0) && month(left.competencia) == month(right.data_pagamento)
right.historico.contains(left.numero_nf)
left.doc_tomador.substring(0, 8) == right.doc_pagador.substring(0, 8)Limiares e ambiguidade
| Score do par | Resultado |
|---|---|
≥ thresholds.match | matched: conciliado, sem revisão |
≥ thresholds.possible | possible: aguarda revisão (confirmar ou rejeitar) |
| Abaixo | Descartado |
Cada registro fica em no máximo um match por ruleset. Os pares são aceitos do maior score para o menor, e um registro já usado sai da disputa.
ambiguity_margin protege contra o match errado quando há dois candidatos parecidos: se o segundo melhor candidato ainda livre ficar a menos de ambiguity_margin pontos do melhor, o resultado é possible, mesmo acima do limiar de match. Um candidato que já foi usado por um par melhor não conta. Empate exato vira possible mesmo com margem 0.
Exclusividade por ruleset
A conciliação é por ruleset: um registro tem no máximo um match efetivo (matched, confirmed ou partial) em cada ruleset, e pode estar conciliado em rulesets diferentes ao mesmo tempo. Uma venda pode estar casada com a transação da adquirente num ruleset e com o recebível em outro.
Cada job só carrega os registros ainda abertos naquele ruleset. Rodar de novo não concilia nada duas vezes e não repete trabalho de revisão: um possible igual a outro ainda pendente não é gravado de novo, e um conjunto de registros já rejeitado não volta.
Versões
Toda definição é imutável. Para mudar a regra, publique uma nova versão:
curl -s -X POST https://nexus-v2.openi.com.br/v1/rulesets/<ruleset_id>/versions \
-H "Authorization: Bearer $NEXUS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"definition": { ... }}'- O job usa a versão mais recente, a não ser que
ruleset_versionseja informado. A versão usada fica registrada no job. PATCH /v1/rulesets/{id}só renomeia.DELETEapaga o ruleset; jobs e matches existentes continuam como estão.GET /v1/rulesets/{id}/versionslista as versões eGET /v1/rulesets/{id}/versions/{v}traz uma delas.
Validar contra os datasets
A criação confere a estrutura (limiares, nomes repetidos, sintaxe das expressões). A checagem de campos e tipos depende do par de datasets e acontece na criação do job, ou antes, sob demanda:
curl -s -X POST https://nexus-v2.openi.com.br/v1/rulesets/<ruleset_id>/versions/1/validate \
-H "Authorization: Bearer $NEXUS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"left_dataset_id": "<notas_id>", "right_dataset_id": "<pagamentos_id>"}'A resposta é {"valid": true} ou 422 com um item por problema:
{
"title": "Unprocessable Entity",
"status": 422,
"detail": "invalid ruleset",
"errors": [
{ "location": "definition.blocking[0].keys[0].right", "message": "\"right.doc_pagador\" is not a field of the right dataset; use a reference such as right.field_name" },
{ "location": "definition.matchers[2].expr", "message": "expression must return a double between 0 and 1 or a bool, got int" }
]
}Para calibrar pesos e limiares com dados reais sem gravar nada, rode o job com dry_run: true e compare as estatísticas. Ver Jobs e revisão.

