Openi DeveloperDeveloper
Guia de integração

Composição (1:N, N:1, N:M)

Conciliação por soma: um contra vários, vários contra um, subconjunto contra subconjunto e parcelas.

Nem todo registro tem um par único do outro lado. Uma nota pode ser paga em três transferências; um pagamento pode quitar quatro notas. A seção composite do ruleset procura grupos cuja soma fecha, depois das passadas 1:1, sobre os registros que elas deixaram abertos.

ModoEsquerdaDireitaExemplo
1:N1váriosUma nota paga em várias transferências
N:1vários1Várias notas quitadas por um pagamento
N:MváriosváriosDuas notas de R$ 60 e R$ 40 pagas por transferências de R$ 70 e R$ 30

Estrutura

"composite": {
  "modes": ["1:N", "N:1", "N:M"],
  "group_by": [{ "left": "left.doc_tomador", "right": "right.doc_pagador" }],
  "sum": { "left": "left.valor", "right": "right.valor", "tolerance": 0, "tolerance_percent": 0.5 },
  "window": { "left": "left.vencimento", "right": "right.data_pagamento", "days": 30 },
  "max_items": { "left": 10, "right": 12 },
  "strategies": {
    "complete_group": true,
    "amount_variance": { "max_percent": 5 },
    "partial": { "min_members": 2, "min_completion": 0.2 }
  },
  "thresholds": { "match": 80, "possible": 50 },
  "matchers": [
    { "name": "datas", "score": 70, "expr": "decay(days_between(min(lefts.map(l, l.vencimento)), max(rights.map(r, r.data_pagamento))), 30)" },
    { "name": "itens", "score": 30, "expr": "size(lefts) + size(rights) <= 4" }
  ]
}
AtributoPapel
modesQuais modos rodam, na ordem da lista. Cada modo consome os registros que conciliou antes do próximo
group_byChave obrigatória: um grupo só junta registros com os mesmos valores nesses campos. É o que limita a busca
sumCampos somados de cada lado (integer ou decimal, do mesmo tipo e, em decimal, com o mesmo scale) e a tolerância aceita
windowOpcional: limite de dias entre as datas dos registros do grupo (0 a 366)
max_itemsMáximo de registros de cada lado num match, de 2 a 100. Padrão 10
strategiesComportamentos opcionais, descritos abaixo
thresholdsLimiares próprios da composição
matchersPontuação do grupo. Sem matchers, um grupo que fecha pontua 100

Soma e tolerância

  • tolerance é absoluta, em unidades mínimas (centavos com scale: 2).
  • tolerance_percent é relativa ao valor do alvo (o registro único em 1:N e N:1, e o total esperado nos parciais), de 0 a 100.
  • Com as duas, vale a maior.
  • Valores negativos (tarifas, estornos, notas de crédito) entram na soma normalmente: uma nota de R$ 100,00 fecha com um crédito de R$ 102,50 e uma tarifa de −R$ 2,50.

Registros sem valor no campo de soma ou na data da janela ficam fora da composição.

Matchers de grupo

As expressões recebem as listas lefts e rights, com os mesmos campos dos datasets. Em 1:N, lefts tem um elemento só, então a mesma expressão serve para todos os modos. Use as macros do CEL e as agregações:

decay(days_between(min(lefts.map(l, l.vencimento)), max(rights.map(r, r.data_pagamento))), 30)
rights.all(r, lefts.exists(l, similarity(l.razao_social, r.nome_pagador) > 0.8))
sum(rights.map(r, r.valor)) == sum(lefts.map(l, l.valor))

Como no 1:1, required: true descarta o grupo quando a expressão dá 0, e score: 0 com required: true funciona como filtro.

Ambiguidade

O motor guarda as duas melhores combinações de cada busca. Se duas combinações diferentes empatam no melhor score, o resultado é possible: o Nexus não escolhe no chute entre parcelas idênticas. Um matcher de data costuma desempatar esses casos.

Estratégias

EstratégiaEfeito
complete_group: trueTesta primeiro o grupo inteiro: se todos os candidatos somam o alvo, esse é o resultado
amount_variance: { max_percent }Grupo que quase fecha (juros, multa, desconto) vira possible com amount_diff, desde que a diferença fique dentro de max_percent (até 50)
partialSó com 1:N: parcelas que ainda não somam o total viram um match partial, completado por jobs seguintes

Parciais

Com partial, uma nota de R$ 1.000 paga em parcelas de R$ 250 gera, quando chegam as duas primeiras, um match partial com expected_count: 4. Os registros ficam reservados para esse match.

  • min_members (padrão 2): parcelas mínimas para abrir o parcial.
  • min_completion (padrão 0,2): fração mínima do total já paga.
  • uniformity (padrão 0,05): quanto as parcelas podem variar entre si (desvio padrão sobre a média, até 0,5).

No início de cada job do mesmo ruleset, o Nexus tenta completar os parciais abertos com os registros novos. Quando a soma fecha, o match passa a matched e sai o evento match.completed.

No resultado

Matches da composição têm kind (1:N, N:1 ou N:M), pass: -1 e strategy com o caminho que encontrou o grupo:

strategyOrigem
complete_groupO grupo inteiro fechou
subsetBusca de subconjunto
meet_in_the_middleBusca de subconjunto em grupos maiores ou com valores negativos
amount_varianceQuase fechou; sempre possible
partialParcial aberto ou completado

amount_diff traz o total da direita menos o total da esquerda, em unidades mínimas.

Limites

  • Um grupo com mais de 500 registros em um dos lados é pulado e contado em stats.steps[].composite.skipped_groups. Use uma chave de group_by mais seletiva ou uma janela.
  • Quando a busca de um grupo passa do orçamento sem achar solução, ela para e conta em searches_exhausted. Os registros continuam abertos para o próximo job.

On this page