Correspondências divididas e agregadas

A reconciliação no mundo real frequentemente envolve transações que não correspondem 1:1. Um único pagamento pode cobrir múltiplas faturas, ou vários depósitos podem se consolidar em uma única entrada bancária. O Matcher lida com esses cenários complexos através de correspondência dividida e agregada.

Visão geral

A cardinalidade da correspondência é controlada pelo tipo de contexto. O Matcher suporta três tipos de contexto:

Tipo de contexto	Descrição	Exemplo
1:1 — Um para um	Uma origem para um destino	Pagamento de fatura única
1:N — Um para vários / vários para um	Uma origem para vários destinos (divisão) ou várias origens para um destino (agregação)	Pagamento em lote cobrindo faturas; depósitos consolidados em um banco
N:M — Vários para vários	Qualquer combinação de origens e destinos	Compensação complexa

Não existe um tipo de contexto N:1 separado. A correspondência agregada (várias origens para um destino) é simplesmente o tipo de contexto 1:N aplicado na direção de agregação: o mesmo tipo de contexto cobre tanto a divisão quanto a agregação.

Como funciona

O comportamento de divisão e agregação é controlado por dois mecanismos:

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

Não existe uma configuração separada de “split” ou “aggregate” no contexto. O tipo de contexto define quais padrões são permitidos, e a configuração da regra controla o comportamento de alocação.

Mapeamento de tipo de contexto

Tipo de contexto	Padrões permitidos
`1:1`	Apenas uma origem para um destino
`1:N`	Uma origem para vários destinos (split), ou várias origens para um destino (aggregate)
`N:M`	Qualquer combinação de origens e destinos

Configurações de alocação da regra

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

Campo	Tipo	Descrição
`allowPartial`	Boolean	Permitir alocação parcial dos valores das transações
`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	Limite de tolerância para residuais de alocação
`allocationUseBaseAmount`	Boolean	Usar valor base (convertido) para alocação
`feeAware`	Boolean	Alocação 1:N ciente de tarifas: consome a parcela bruta de cada candidato (líquido + tarifa) em vez de apenas o líquido. Útil para splits de marketplace em que o repasse chega líquido de tarifas
`nmDeductionBand`	Decimal	Apenas regras TOLERANCE. Banda de pagamento a menor para o solver N:M, como fração decimal do valor de face da fatura paga a menor (`0.05` = 5%). Permite que um subconjunto de pagamentos pague a menor um subconjunto de faturas dentro da banda. Zerada ou ausente, fica desativada

Exemplo: regra tolerance 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
   }
 }'

matchScore e matchBaseScore são aceitos e validados, mas são reservados/inertes — eles não alteram a pontuação de confiança calculada. A confiança é sempre calculada a partir dos pesos fixos dos componentes internos (valor 40, moeda 30, data 20, referência 10). Veja Pontuação de confiança.

Criando um contexto 1:N

Para habilitar correspondência dividida ou agregada, crie um contexto com 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 dividida 1:N

Uma transação de origem corresponde a múltiplas transações de destino.

Casos de uso comuns

Pagamento em lote: Uma única transferência cobrindo múltiplas faturas
Folha de pagamento: Um débito bancário para múltiplos pagamentos de salário
Liquidação: Um pagamento de gateway para múltiplos pedidos

Exemplo: pagamento de faturas em lote

Origem (Extrato Bancário):

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

Destinos (Lançamentos Contábeis):

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

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

Correspondência agregada (vários para um)

Múltiplas transações de origem correspondem a uma transação de destino. Esta é 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: Múltiplos 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: Múltiplos recebimentos de caixa registradora para um depósito

Exemplo: depósito consolidado

Origens (Ponto de Venda):

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

Destino (Extrato Bancário):

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

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

Correspondência N:M muitos-para-muitos

Múltiplas transações de origem correspondem a múltiplas transações de destino. Este é o padrão mais complexo.

Casos de uso comuns

Compensação intercompany: Múltiplas faturas compensadas contra múltiplos pagamentos
Liquidações de negociação: Compensação complexa com preenchimentos parciais
Reconhecimento de receita: Múltiplas entregas contra múltiplos adiantamentos

Exemplo: compensação intercompany

Origens (Contas a Pagar da Empresa A):

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

Destinos (Contas a Receber da Empresa A):

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

Resultado: Correspondência 2:2, $18.000 total correspondido Para habilitar correspondência N:M, crie um contexto com 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"
 }'

Executando e revisando matches

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

Executar 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"
 }'

Visualizar histórico de execuções

cURL

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

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

O parâmetro de consulta contextId é obrigatório. A resposta é uma lista paginada por cursor de grupos de correspondência, cada um contendo suas transações correspondidas (em todas as cardinalidades) e seus scores de confiança.

cURL

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

Desfazer (desemparelhar) um grupo de correspondência

Para reverter um grupo incorreto, use unmatch. Um grupo PROPOSED é rejeitado com um motivo e suas transações retornam a UNMATCHED. Para um grupo CONFIRMED, o Matcher também reverte os efeitos residuais/de itens em aberto aplicados por essa confirmação, de forma atômica com a revogação do grupo e a devolução de suas transações. O parâmetro de consulta contextId é obrigatório, e um reason é enviado 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 remover a última contribuição ainda ativa por trás de uma obrigação, esse item em aberto passa ao status terminal WITHDRAWN: ele permanece como histórico, mas não pode ser compensado nem carregado para outra execução. O Matcher verifica se a reversão é possível antes de alterar qualquer coisa. Se uma entrada posterior ainda ativa permanecer sobre o residual, ou se uma obrigação mais recente e ativa entrar em conflito ao restaurar um item terminal com a mesma identidade, o endpoint retorna 409 Conflict e deixa o grupo, as transações e os itens em aberto inalterados.

Algoritmo de correspondência

O algoritmo depende do tipo de contexto.

1:N — alocação sequencial determinística

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

Ordenar: As transações são ordenadas deterministicamente para garantir resultados reproduzíveis entre execuções.
Iterar: O motor percorre os candidatos em ordem de prioridade.
Alocar: Os valores são distribuídos de acordo com a configuração allocationDirection (LEFT_TO_RIGHT ou RIGHT_TO_LEFT).
Rastrear residuais: Quaisquer valores não alocados restantes são rastreados. Se allowPartial for true, uma perna que ultrapassa é limitada ao valor restante; um split com cobertura incompleta ainda gera uma exceção de diagnóstico.

N:M — solver de correspondência de conjuntos

Para cenários N:M, o Matcher não aloca sequencialmente. Ele usa um solver limitado de seleção de subconjuntos: os candidatos são agrupados pela identidade de correspondência da regra, e o solver busca um subconjunto de transações do lado esquerdo e um subconjunto do lado direito que se conciliem entre si, com cardinalidade limitada por lado. A seleção é determinística sobre a entrada ordenada, cada grupo proposto precisa superar o limite fixo de confiança (pontuação mínima de 60), e nenhuma transação cai em dois grupos propostos dentro da mesma execução. Em regras TOLERANCE, a chave nmDeductionBand permite ao solver admitir um subconjunto de pagamentos que paga a menor um subconjunto de faturas dentro da banda.

Razões de exceção

Transações que não podem ser totalmente conciliadas aparecem como exceções tipadas:

SPLIT_INCOMPLETE — existem alocações, mas elas não cobrem totalmente o valor alvo, independentemente de allowPartial.
OVER_SETTLED — uma perna ultrapassou o que estava liquidando; o remanescente sobreliquidado é registrado como uma exceção tipada.

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

Melhores 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 necessário.

Use tolerância de alocação para arredondamento

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

Habilite alocação parcial deliberadamente

Defina allowPartial como true apenas quando correspondências parciais são esperadas. Isso evita correspondências falsas de dados incompletos.

Faça dry-run antes de confirmar

Sempre teste correspondência dividida e agregada no modo DRY_RUN primeiro para verificar os resultados de alocação.

Monitore 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 divididas e agregadas

Visão geral

Como funciona

Mapeamento de tipo de contexto

Configurações de alocação da regra

Exemplo: regra tolerance com alocação

Criando um contexto 1:N

Correspondência dividida 1:N

Casos de uso comuns

Exemplo: pagamento de faturas em lote

Correspondência agregada (vários para um)

Casos de uso comuns

Exemplo: depósito consolidado

Correspondência N:M muitos-para-muitos

Casos de uso comuns

Exemplo: compensação intercompany

Executando e revisando matches

Executar correspondência

Visualizar histórico de execuções

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

Desfazer (desemparelhar) um grupo de correspondência

Algoritmo de correspondência

1:N — alocação sequencial determinística

N:M — solver de correspondência de conjuntos

Razões de exceção

Melhores práticas

Próximos passos

Regras de Correspondência

Segurança

​Visão geral

​Como funciona

​Mapeamento de tipo de contexto

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

​Exemplo: regra tolerance com alocação

​Criando um contexto 1:N

​Correspondência dividida 1:N

​Casos de uso comuns

​Exemplo: pagamento de faturas em lote

​Correspondência agregada (vários para um)

​Casos de uso comuns

​Exemplo: depósito consolidado

​Correspondência N:M muitos-para-muitos

​Casos de uso comuns

​Exemplo: compensação intercompany

​Executando e revisando matches

​Executar correspondência

​Visualizar histórico de execuções

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

​Desfazer (desemparelhar) um grupo de correspondência

​Algoritmo de correspondência

​1:N — alocação sequencial determinística

​N:M — solver de correspondência de conjuntos

​Razões de exceção

​Melhores práticas

​Próximos passos

Regras de Correspondência

Segurança

Visão geral

Como funciona

Mapeamento de tipo de contexto

Configurações de alocação da regra

Exemplo: regra tolerance com alocação

Criando um contexto 1:N

Correspondência dividida 1:N

Casos de uso comuns

Exemplo: pagamento de faturas em lote

Correspondência agregada (vários para um)

Casos de uso comuns

Exemplo: depósito consolidado

Correspondência N:M muitos-para-muitos

Casos de uso comuns

Exemplo: compensação intercompany

Executando e revisando matches

Executar correspondência

Visualizar histórico de execuções

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

Desfazer (desemparelhar) um grupo de correspondência

Algoritmo de correspondência

1:N — alocação sequencial determinística

N:M — solver de correspondência de conjuntos

Razões de exceção

Melhores práticas

Próximos passos