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

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, desfaça o emparelhamento. Isso rejeita o grupo com um motivo e reverte todas as suas transações para UNMATCHED. 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"
 }'

Algoritmo de correspondência

Para cenários N:M, o Matcher usa alocação sequencial determinística para parear transações.

Como funciona

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, correspondências parciais são criadas; caso contrário, transações não alocadas se tornam exceções.

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.

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

Como funciona

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

​Como funciona

​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

Como funciona

Melhores práticas

Próximos passos