> ## 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 divididas e agregadas > Concilie transações nos padrões 1:1, 1:N (divisão e agregação) e N:M usando tipos de contexto e flags de alocação de regras para controlar como os valores são distribuídos. 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: 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 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 ```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 } }' ``` `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](/pt/matcher/reference/matcher-confidence-scoring). ## Criando um contexto 1:N *** Para habilitar correspondência dividida ou agregada, crie um contexto com 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/matcher/create-context) ## 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`: ```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" }' ``` ## 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 ```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" }' ``` ### Visualizar histórico de execuções ```bash cURL theme={null} 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. ```bash cURL theme={null} 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. ```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" }' ``` ## 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 *** Configure regras e configurações de alocação. Segurança e controle de acesso.