> ## 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) | 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 | > [!NOTE] > > 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: 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 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. ```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": "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`: ```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" }' ``` > [!TIP] > > Referência da API: [Criar contexto](https://docs.lerian.studio/pt/reference/products/matcher/create-context.md) ## 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`: ```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" }' ``` 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 ```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` e revoga um grupo `CONFIRMED`. Revogar um grupo devolve todas as transações para `UNMATCHED`. Rejeitar uma proposta devolve as transações dela, exceto uma que você resolveu separadamente com uma correspondência forçada. 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. ```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 *** 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. **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. 3. **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`. 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. 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 *** > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] Monitore os residuais > > Acompanhe os valores residuais ao longo do tempo. Residuais crescentes podem indicar problemas sistemáticos de correspondência. ## Próximos passos *** > [card] [Regras de correspondência](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-match-rules.md) > > Configure as regras e as opções de alocação. > [card] [Segurança](https://docs.lerian.studio/pt/products/matcher/reference/matcher-security.md) > > Segurança e controle de acesso. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.