> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Correspondências por divisão e agregação > Concilie padrões de transação 1:1, 1:N (divisão e agregação) e N:M usando tipos de contexto e flags de alocação nas regras para controlar como os valores são distribuídos. 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: 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 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 ```bash cURL theme={null} 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](/pt/products/matcher/reference/matcher-confidence-scoring). ## Criar um contexto 1:N *** Para habilitar a correspondência por divisão ou agregação, crie um contexto com o tipo `1:N`: ```bash cURL theme={null} 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](/pt/reference/products/matcher/create-context) ## 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`: ```bash cURL theme={null} 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 ```bash cURL theme={null} 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 ```bash cURL theme={null} 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. ```bash cURL theme={null} 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. ```bash cURL theme={null} 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: 1. **Ordenar**: o Matcher ordena as transações de forma determinística para garantir resultados reprodutíveis entre execuções. 2. **Iterar**: o motor percorre os candidatos na ordem de prioridade. 3. **Alocar**: o Matcher distribui os valores conforme a configuração `allocationDirection` (`LEFT_TO_RIGHT` ou `RIGHT_TO_LEFT`). 4. **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 *** A correspondência muitos para muitos é complexa. Comece com padrões mais simples e habilite N:M apenas quando for necessário. Pequenas diferenças de arredondamento são comuns em pagamentos divididos. Defina allocationToleranceValue com alguns centavos para evitar exceções falsas. Defina allowPartial como true apenas quando você espera correspondências parciais. Isso evita correspondências falsas vindas de dados incompletos. Sempre teste primeiro a correspondência por divisão e agregação no modo DRY\_RUN para conferir os resultados da alocação. Acompanhe os valores residuais ao longo do tempo. Residuais crescentes podem indicar problemas sistemáticos de correspondência. ## Próximos passos *** Configure as regras e as opções de alocação. Segurança e controle de acesso.