Openi DeveloperDeveloper
Guia de integração

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)" }
    ]
  }
}
AtributoPapel
blockingQuais pares são comparados. Pelo menos uma passada
matchersComo cada par é pontuado. Pelo menos um
thresholdsA partir de que score o par vira matched ou possible
ambiguity_marginDistância mínima entre o melhor e o segundo melhor candidato para aceitar o match sem revisão
compositeOpcional: 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.x com right.y). Com mais de um, todos precisam ser iguais (chave composta). Os dois campos de cada par têm o mesmo tipo (em decimal, o mesmo scale) e, de preferência, index: true no dataset.
  • window (opcional): além da chave, as datas dos dois lados ficam a no máximo days dias uma da outra (0 a 366). Vale para campos date e timestamp.
  • 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_keys do 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: 0 com required: 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.
  • breakdown de cada match mostra o valor que cada matcher deu, para calibrar pesos.

Tipos nas expressões

Campo do datasetTipo em CELAtenção
stringstringValor já normalizado
integerint
decimalintEm unidades mínimas: 100.50 com scale: 2 vale 10050. Tolerâncias também: 100 é R$ 1,00
booleanbool
date, timestamptimestamp

Funções

FunçãoRetorno
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 parResultado
≥ thresholds.matchmatched: conciliado, sem revisão
≥ thresholds.possiblepossible: aguarda revisão (confirmar ou rejeitar)
AbaixoDescartado

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_version seja informado. A versão usada fica registrada no job.
  • PATCH /v1/rulesets/{id} só renomeia. DELETE apaga o ruleset; jobs e matches existentes continuam como estão.
  • GET /v1/rulesets/{id}/versions lista as versões e GET /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.

On this page