Correspondências por divisão e agregação

A conciliação do mundo real muitas vezes envolve transações que não correspondem 1:1. Um único pagamento pode cobrir várias faturas, ou vários depósitos podem se consolidar em um lançamento bancário. O Matcher trata esses cenários complexos com a correspondência por divisão e agregação.

Visão geral

O tipo de contexto controla a cardinalidade da correspondência. O Matcher oferece três tipos de contexto:

Tipo de contexto	Descrição	Exemplo
1:1 — um para um	Uma fonte para um destino	Pagamento de uma única fatura
1:N — um para muitos / muitos para um	Uma fonte para muitos destinos (divisão) ou muitas fontes para um destino (agregação)	Pagamento em lote cobrindo faturas; depósitos consolidados em um banco
N:M — muitos para muitos	Qualquer combinação de fontes e destinos	Netting complexo

Não existe um tipo de contexto N:1 separado. A correspondência por agregação (muitas fontes para um destino) usa o tipo de contexto 1:N na direção de agregação. O mesmo tipo de contexto cobre tanto a divisão quanto a agregação.

Como funciona

Dois mecanismos controlam o comportamento de divisão e agregação:

Tipo de contexto: determina a cardinalidade da correspondência (1:1, 1:N ou N:M).
Flags de alocação da regra: controlam como o Matcher distribui os valores dentro de um grupo de correspondência.

Não existe uma configuração “divisão” ou “agregação” separada no contexto. O tipo de contexto define os padrões permitidos, e a config da regra controla o comportamento de alocação.

Mapeamento dos tipos de contexto

Tipo de contexto	Padrões permitidos
`1:1`	Apenas uma fonte para um destino
`1:N`	Uma fonte para muitos destinos (divisão), ou muitas fontes para um destino (agregação)
`N:M`	Qualquer combinação de fontes e destinos

Configurações de alocação da regra

Todos os tipos de regra aceitam flags de alocação no seu config:

Campo	Tipo	Descrição
`allowPartial`	Boolean	Permite a alocação parcial dos valores da transação
`allocationDirection`	String	Ordem de alocação: `LEFT_TO_RIGHT` ou `RIGHT_TO_LEFT`
`allocationToleranceMode`	String	Como a tolerância é medida: `ABS` (absoluta) ou `PERCENT`
`allocationToleranceValue`	Decimal	Limiar de tolerância para os residuais da alocação
`allocationUseBaseAmount`	Boolean	Usa o valor base (convertido) para a alocação
`feeAware`	Boolean	Alocação 1:N consciente de tarifas: consome a parcela bruta de cada candidato (líquido + tarifa) em vez de apenas o líquido. Útil para divisões de marketplace em que o repasse é líquido de tarifas
`nmDeductionBand`	Decimal	Apenas regras TOLERANCE. Faixa de pagamento a menor para o solver N:M, como fração decimal do valor de face da fatura curta (`0.05` = 5%). Deixa um subconjunto de pagamentos pagar a menos um subconjunto de faturas dentro da faixa. Zero ou ausente desabilita

Exemplo: regra de tolerância com alocação

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 2,
   "config": {
     "percentTolerance": 0.01,
     "absTolerance": 5.0,
     "matchCurrency": true,
     "allowPartial": true,
     "allocationDirection": "LEFT_TO_RIGHT",
     "allocationToleranceMode": "ABS",
     "allocationToleranceValue": 10.0,
     "matchScore": 85,
     "matchBaseScore": 80
   }
 }'

O Matcher aceita e valida matchScore e matchBaseScore. As duas chaves continuam reservadas/inertes. Elas não mudam a pontuação de confiança calculada. O Matcher sempre calcula a confiança a partir dos pesos internos fixos dos componentes (valor 40, moeda 30, data 20, referência 10). Veja Pontuação de confiança.

Criar um contexto 1:N

Para habilitar a correspondência por divisão ou agregação, crie um contexto com o tipo 1:N:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Reconciliation",
   "type": "1:N",
   "interval": "daily"
 }'

Referência da API: Criar contexto

Correspondência 1:N por divisão

Uma transação da fonte corresponde a várias transações do destino.

Casos de uso comuns

Pagamento em lote: uma única transferência cobrindo várias faturas
Folha de pagamento: um débito bancário para vários pagamentos de salário
Liquidação: um repasse do gateway para vários pedidos

Exemplo: pagamento de faturas em lote

Fonte (extrato bancário):

ID	Valor	Referência
bank_001	US$ 15.000,00	BULK-PAY-2024-001

Destinos (lançamentos do ledger):

ID	Valor	Fatura
inv_001	US$ 5.000,00	INV-2024-001
inv_002	US$ 7.500,00	INV-2024-002
inv_003	US$ 2.500,00	INV-2024-003

Resultado: correspondência 1:3 com alocação total

Correspondência por agregação (muitos para um)

Várias transações da fonte correspondem a uma transação do destino. Essa é a direção de agregação do tipo de contexto 1:N. Não é um tipo N:1 separado.

Casos de uso comuns

Depósitos bancários: vários cheques depositados como um único crédito
Liquidações de cartão: lote diário de transações como um único depósito
Consolidação de caixa: vários comprovantes de caixa para um único depósito

Exemplo: depósito consolidado

Fontes (ponto de venda):

ID	Valor	Caixa
pos_001	US$ 1.250,00	REG-01
pos_002	US$ 980,00	REG-02
pos_003	US$ 1.770,00	REG-03

Destino (extrato bancário):

ID	Valor	Referência
bank_002	US$ 4.000,00	DEPOSIT-20240120

Resultado: correspondência 3:1 com alocação total

Correspondência N:M muitos para muitos

Várias transações da fonte correspondem a várias transações do destino. Esse é o padrão mais complexo.

Casos de uso comuns

Netting entre empresas: várias faturas compensadas contra vários pagamentos
Liquidações de negociação: compensação complexa com execuções parciais
Reconhecimento de receita: várias entregas contra vários adiantamentos

Exemplo: netting entre empresas

Fontes (contas a pagar da Empresa A):

ID	Valor	Referência
pay_001	US$ 10.000,00	IC-PAY-001
pay_002	US$ 8.000,00	IC-PAY-002

Destinos (contas a receber da Empresa A):

ID	Valor	Referência
rec_001	US$ 12.000,00	IC-REC-001
rec_002	US$ 6.000,00	IC-REC-002

Resultado: correspondência 2:2, US$ 18.000 conciliados no total Para habilitar a correspondência N:M, crie um contexto com o tipo N:M:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Intercompany Netting",
   "type": "N:M",
   "interval": "weekly"
 }'

Executar e revisar correspondências

Depois de configurar o contexto e as regras, dispare uma execução de correspondência e revise os grupos resultantes.

Executar a correspondência

cURL

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'

Ver o histórico de execuções de correspondência

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/runs" \
 -H "Authorization: Bearer $TOKEN"

Ver os grupos de correspondência de uma execução

Você deve enviar o parâmetro de query contextId. A resposta é uma lista de grupos de correspondência paginada por cursor, cada um contendo suas transações conciliadas (em todas as cardinalidades) e as pontuações de confiança.

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN"

Quebrar (desfazer) um grupo de correspondência

Para reverter um grupo incorreto, desfaça a correspondência. O Matcher rejeita um grupo PROPOSED com um motivo, e as transações dele voltam para UNMATCHED. Para um grupo CONFIRMED, o Matcher também reverte os efeitos de residual e de itens em aberto que a confirmação aplicou, de forma atômica com a revogação do grupo e a devolução das transações. Você deve enviar o parâmetro de query contextId e um reason no corpo.

cURL

curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "incorrect match - amounts do not match"
 }'

Se a reversão do grupo confirmado remove a última contribuição viva por trás de uma obrigação, aquele item em aberto vira WITHDRAWN terminal. Ele permanece como histórico, mas não é compensável e nenhuma outra execução o carrega. O Matcher verifica a reversibilidade antes de mudar qualquer coisa. O endpoint retorna 409 Conflict se um lançamento vivo posterior ainda se apoia no residual. Ele também retorna esse erro se uma obrigação viva mais recente entrar em conflito com a restauração de um item terminal na mesma identidade. Nos dois casos, ele deixa o grupo, as transações e os itens em aberto inalterados.

Algoritmo de correspondência

O algoritmo depende do tipo de contexto.

Alocação sequencial determinística 1:N

Para cenários de divisão e agregação (1:N), o Matcher usa alocação sequencial determinística:

Ordenar: o Matcher ordena as transações de forma determinística para garantir resultados reprodutíveis entre execuções.
Iterar: o motor percorre os candidatos na ordem de prioridade.
Alocar: o Matcher distribui os valores conforme a configuração allocationDirection (LEFT_TO_RIGHT ou RIGHT_TO_LEFT).
Acompanhar residuais: o Matcher acompanha qualquer valor que sobre sem alocação. Se allowPartial é true, o Matcher limita ao valor restante uma perna que ultrapassa. Uma divisão coberta a menos ainda gera uma exceção de diagnóstico.

Solver de correspondência de conjuntos N:M

Para cenários N:M, o Matcher não aloca sequencialmente. Ele usa um solver limitado de seleção de subconjuntos. O solver agrupa os candidatos pela identidade de correspondência da regra. Depois ele procura um subconjunto de transações da esquerda e um subconjunto de transações da direita que conciliem entre si. O solver limita a cardinalidade por lado. A seleção continua determinística sobre a entrada ordenada. Cada grupo proposto deve passar pelo filtro fixo de confiança (pontuação mínima 60). Nenhuma transação cai em dois grupos propostos dentro de uma execução. Nas regras TOLERANCE, a chave nmDeductionBand deixa o solver admitir um subconjunto de pagamentos que paga a menos um subconjunto de faturas dentro da faixa.

Motivos de exceção

As transações que o Matcher não consegue conciliar por completo aparecem como exceções tipadas:

SPLIT_INCOMPLETE: existem alocações, mas elas não cobrem por completo o valor do destino, independentemente de allowPartial.
OVER_SETTLED: uma perna ultrapassou o que liquidou. O Matcher apresenta o excedente liquidado a mais como uma quebra tipada.

Você pode filtrar a lista de exceções por esses valores de reason.

Boas práticas

Comece com 1:N antes de N:M

A correspondência muitos para muitos é complexa. Comece com padrões mais simples e habilite N:M apenas quando for necessário.

Use a tolerância de alocação para arredondamentos

Pequenas diferenças de arredondamento são comuns em pagamentos divididos. Defina allocationToleranceValue com alguns centavos para evitar exceções falsas.

Habilite a alocação parcial de forma deliberada

Defina allowPartial como true apenas quando você espera correspondências parciais. Isso evita correspondências falsas vindas de dados incompletos.

Simule antes de efetivar

Sempre teste primeiro a correspondência por divisão e agregação no modo DRY_RUN para conferir os resultados da alocação.

Monitore os residuais

Acompanhe os valores residuais ao longo do tempo. Residuais crescentes podem indicar problemas sistemáticos de correspondência.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Correspondências por divisão e agregação

Visão geral

Como funciona

Mapeamento dos tipos de contexto

Configurações de alocação da regra

Exemplo: regra de tolerância com alocação

Criar um contexto 1:N

Correspondência 1:N por divisão

Casos de uso comuns

Exemplo: pagamento de faturas em lote

Correspondência por agregação (muitos para um)

Casos de uso comuns

Exemplo: depósito consolidado

Correspondência N:M muitos para muitos

Casos de uso comuns

Exemplo: netting entre empresas

Executar e revisar correspondências

Executar a correspondência

Ver o histórico de execuções de correspondência

Ver os grupos de correspondência de uma execução

Quebrar (desfazer) um grupo de correspondência

Algoritmo de correspondência

Alocação sequencial determinística 1:N

Solver de correspondência de conjuntos N:M

Motivos de exceção

Boas práticas

Próximos passos

Regras de correspondência

Segurança

​Visão geral

​Como funciona

​Mapeamento dos tipos de contexto

​Configurações de alocação da regra

​Exemplo: regra de tolerância com alocação

​Criar um contexto 1:N

​Correspondência 1:N por divisão

​Casos de uso comuns

​Exemplo: pagamento de faturas em lote

​Correspondência por agregação (muitos para um)

​Casos de uso comuns

​Exemplo: depósito consolidado

​Correspondência N:M muitos para muitos

​Casos de uso comuns

​Exemplo: netting entre empresas

​Executar e revisar correspondências

​Executar a correspondência

​Ver o histórico de execuções de correspondência

​Ver os grupos de correspondência de uma execução

​Quebrar (desfazer) um grupo de correspondência

​Algoritmo de correspondência

​Alocação sequencial determinística 1:N

​Solver de correspondência de conjuntos N:M

​Motivos de exceção

​Boas práticas

​Próximos passos

Regras de correspondência

Segurança

Visão geral

Como funciona

Mapeamento dos tipos de contexto

Configurações de alocação da regra

Exemplo: regra de tolerância com alocação

Criar um contexto 1:N

Correspondência 1:N por divisão

Casos de uso comuns

Exemplo: pagamento de faturas em lote

Correspondência por agregação (muitos para um)

Casos de uso comuns

Exemplo: depósito consolidado

Correspondência N:M muitos para muitos

Casos de uso comuns

Exemplo: netting entre empresas

Executar e revisar correspondências

Executar a correspondência

Ver o histórico de execuções de correspondência

Ver os grupos de correspondência de uma execução

Quebrar (desfazer) um grupo de correspondência

Algoritmo de correspondência

Alocação sequencial determinística 1:N

Solver de correspondência de conjuntos N:M

Motivos de exceção

Boas práticas

Próximos passos