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)	Uma transação do lado esquerdo para muitas transações do lado direito, para uma divisão ou uma 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 transação única fica sempre no lado esquerdo. Para uma agregação, coloque no lado esquerdo a fonte que traz o lançamento consolidado.

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 transação do lado esquerdo para muitas transações do lado direito
`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. O Matcher as aplica em contextos 1:N:

Campo	Tipo	Descrição
`allowPartial`	Boolean	Permite a alocação parcial dos valores da transação
`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	Aloca os valores base (convertidos). Em regras EXACT e TOLERANCE, também liga `matchBaseAmount` e `matchBaseCurrency`.
`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 em contextos `N:M`. 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 divisão com alocação

Em um contexto 1:N, cada transação do lado direito precisa passar nas verificações da regra contra a transação do lado esquerdo. Uma regra que compara valores apenas corresponde pernas iguais ao total, então uma regra de divisão desliga matchAmount e deixa a alocação verificar o total. As regras TOLERANCE sempre comparam valores.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 2,
   "config": {
     "matchAmount": false,
     "matchReference": false,
     "allowPartial": true,
     "allocationToleranceMode": "ABS",
     "allocationToleranceValue": 10.0
   }
 }'

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 do lado esquerdo corresponde a muitas transações do lado direito.

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

Lado esquerdo (extrato bancário):

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

Lado direito (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)

Muitas transações correspondem a uma transação consolidada. Isso usa o tipo de contexto 1:N com a fonte consolidada no lado esquerdo. Não existe 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

Lado direito (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

Lado esquerdo (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"
 }'

Uma execução DRY_RUN informa as estatísticas dela, mas não armazena grupos de correspondência. Para listar grupos de correspondência, execute com COMMIT.

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 e revoga um grupo CONFIRMED. Nos dois casos, as transações dele voltam para UNMATCHED. Revogar um grupo CONFIRMED também retira os residuais de itens em aberto dele, anula as variações de tarifa dele e retira as exceções que ele levantou, na mesma transação. 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"
 }'

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.
Coletar: para cada transação do lado esquerdo, o Matcher coleta as transações do lado direito que passam nas verificações da regra contra ela.
Alocar: o Matcher aloca as transações coletadas na ordem de classificação e para quando o valor restante fica dentro da tolerância de alocação. Ele ignora uma transação em outra moeda. Ele aloca apenas transações com o sinal de liquidação do signConvention do contexto: o sinal da transação do lado esquerdo com SAME (o padrão), o sinal oposto com OPPOSITE.
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. Um grupo tem no máximo 4 transações por lado. O Matcher ignora um bucket que tem mais de 40 transações em qualquer lado. Apenas regras EXACT e TOLERANCE rodam em contextos N:M. 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 transação liquidou a mais uma obrigação que uma execução anterior carregou em aberto. O Matcher mostra 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 e leia as estatísticas da execução. Uma execução de teste não armazena grupos de correspondência.

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

Console

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 divisão 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 divisão 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 divisão 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