Pular para o conteúdo principal
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

O Matcher suporta quatro padrões de correspondência:
PadrãoDescriçãoExemplo
1:1Uma origem para um destinoPagamento de fatura única
1:NUma origem para vários destinosPagamento em lote cobrindo faturas
N:1Várias origens para um destinoDepósitos consolidados no banco
N:MVárias origens para vários destinosCompensação complexa

​
Como funciona

O comportamento de divisão e agregação é controlado por dois mecanismos:
  1. Tipo de contexto — determina a cardinalidade da correspondência (1:1, 1:N ou N:M).
  2. 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 contextoPadrões permitidos
1:1Apenas uma origem para um destino
1:NUma origem para vários destinos (split), ou várias origens para um destino (aggregate)
N:MQualquer 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:
CampoTipoDescrição
allowPartialBooleanPermitir alocação parcial dos valores das transações
allocationDirectionStringOrdem de alocação: LEFT_TO_RIGHT ou RIGHT_TO_LEFT
allocationToleranceModeStringComo a tolerância é medida: ABS (absoluta) ou PERCENT
allocationToleranceValueDecimalLimite de tolerância para residuais de alocação
allocationUseBaseAmountBooleanUsar valor base (convertido) para alocação

​
Exemplo: regra tolerance com alocação

cURL
curl -X POST "https://api.matcher.example.com/v1/config/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
   }
 }'

​
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/config/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):
IDValorReferência
bank_001$15.000,00BULK-PAY-2024-001
Destinos (Lançamentos Contábeis):
IDValorFatura
inv_001$5.000,00INV-2024-001
inv_002$7.500,00INV-2024-002
inv_003$2.500,00INV-2024-003
Resultado: Correspondência 1:3 com alocação total

​
Correspondência agregada N:1

Múltiplas transações de origem correspondem a uma transação de destino.

​
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):
IDValorCaixa
pos_001$1.250,00REG-01
pos_002$980,00REG-02
pos_003$1.770,00REG-03
Destino (Extrato Bancário):
IDValorReferência
bank_002$4.000,00DEPOSIT-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):
IDValorReferência
pay_001$10.000,00IC-PAY-001
pay_002$8.000,00IC-PAY-002
Destinos (Contas a Receber da Empresa A):
IDValorReferência
rec_001$12.000,00IC-REC-001
rec_002$6.000,00IC-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/config/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 grupos de correspondência

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

​
Visualizar detalhes do grupo

cURL
curl -X GET "https://api.matcher.example.com/v1/matching/groups/{groupId}" \
 -H "Authorization: Bearer $TOKEN"

​
Confirmar um grupo de correspondência

cURL
curl -X POST "https://api.matcher.example.com/v1/matching/groups/{groupId}/confirm" \
 -H "Authorization: Bearer $TOKEN"

​
Rejeitar um grupo de correspondência

cURL
curl -X POST "https://api.matcher.example.com/v1/matching/groups/{groupId}/reject" \
 -H "Authorization: Bearer $TOKEN"

​
Revogar um grupo de correspondência confirmado

cURL
curl -X POST "https://api.matcher.example.com/v1/matching/groups/{groupId}/revoke" \
 -H "Authorization: Bearer $TOKEN"

​
Algoritmo de correspondência

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

​
Como funciona

  1. Ordenar: As transações são ordenadas deterministicamente para garantir resultados reproduzíveis entre execuções.
  2. Iterar: O motor percorre os candidatos em ordem de prioridade.
  3. Alocar: Os valores são distribuídos de acordo com a configuração allocationDirection (LEFT_TO_RIGHT ou RIGHT_TO_LEFT).
  4. 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

A correspondência muitos-para-muitos é complexa. Comece com padrões mais simples e habilite N:M apenas quando necessário.
Pequenas diferenças de arredondamento são comuns em pagamentos divididos. Defina allocationToleranceValue em alguns centavos para evitar exceções falsas.
Defina allowPartial como true apenas quando correspondências parciais são esperadas. Isso evita correspondências falsas de dados incompletos.
Sempre teste correspondência dividida e agregada no modo DRY_RUN primeiro para verificar os resultados de alocação.
Acompanhe os valores residuais ao longo do tempo. Residuais crescentes podem indicar problemas sistemáticos de correspondência.

​
Próximos passos

Regras de Correspondência

Configure regras e configurações de alocação.

Segurança

Segurança e controle de acesso.