> ## 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. # Conceitos do Matcher > Aprenda os cinco conceitos centrais do Matcher que moldam cada conciliação que você monta: contextos, fontes, mapas de campos, regras de correspondência e correspondências. Os cinco conceitos centrais do Matcher: **contextos**, **fontes**, **mapas de campos**, **regras** e **correspondências**. ## Contexto *** Um **contexto** define o que você concilia. Ele é o contêiner de configuração para fontes e regras. Suas fontes e regras inline são opcionais. > [!NOTE] > > Um contexto responde: *o que corresponde ao quê?* > [!NOTE] > > Você pode começar com um rascunho vazio. Para ativá-lo, configure pelo menos uma fonte `LEFT` e uma fonte `RIGHT`, mapeie cada fonte (ou declare opções `camt053` válidas, que se automapeiam) e adicione uma regra de correspondência. Se você habilitar a normalização de tarifas, adicione também uma regra de tarifa. ### Tipos de contexto | Tipo | Descrição | Exemplo | | - | - | - | | **1:1** | Conciliação um para um | Extrato bancário vs registros do ERP | | **1:N** | Conciliação um para muitos | Um pagamento cobrindo várias faturas | | **N:M** | Conciliação muitos para muitos | Cenários de netting ou de agregação | O tipo também fixa as fontes por lado. Um contexto `1:1` precisa de exatamente uma fonte `LEFT` e uma fonte `RIGHT`, um contexto `1:N` precisa de exatamente uma fonte `LEFT`, e um contexto `N:M` precisa de pelo menos uma fonte em cada lado. Uma execução de correspondência falha quando as fontes não se encaixam no tipo. ### Exemplo Um contexto chamado **"Chase Bank vs ERP System"** faria o seguinte: * Definir o Chase Bank como uma fonte de conciliação * Definir o seu sistema ERP como outra fonte * Especificar as regras usadas para conciliar transações entre eles ## Fonte *** Uma **fonte** é de onde as transações vêm. Um contexto em rascunho pode começar sem fontes. Um contexto ativável precisa de pelo menos uma fonte em cada lado da correspondência. ### Tipos de fonte * **LEDGER**: categoria de fonte ledger * **BANK**: categoria de fonte bancária * **GATEWAY**: categoria de fonte de gateway de pagamento * **CUSTOM**: categoria de fonte personalizada * **FETCHER**: uma categoria de fonte do Discovery ### Configuração da fonte Cada fonte exige: * **Nome**: rotule a fonte (por exemplo, "Chase Checking") * **Tipo**: categoria (`LEDGER`, `BANK`, `GATEWAY`, `CUSTOM` ou `FETCHER`) * **Lado**: qual lado da correspondência ela alimenta (`LEFT` ou `RIGHT`) **Config** é opcional. Se você omitir, o Matcher guarda uma config vazia e usa os padrões do parser para as chaves de política ausentes. Os mapas de campos traduzem os campos de cada fonte para o schema padrão do Matcher. ## Mapa de campos *** Um **mapa de campos** traduz nomes de campos externos para o schema padrão do Matcher. Cada sistema chama as coisas de um jeito. Os mapas de campos normalizam isso. ### Campos padrão | Campo | Obrigatório | Tipo | Descrição | | - | - | - | - | | `external_id` | Sim | String | Identificador da transação no sistema de origem | | `amount` | Sim | Decimal | Valor da transação (positivo ou negativo) | | `currency` | Sim | String | Código de moeda ISO 4217 | | `date` | Sim | DateTime | Data da transação | | `description` | Não | String | Descrição da transação | | `fee_amount` | Não | Decimal | Coluna opcional de valor da tarifa | | `fee_currency` | Não | String | Coluna opcional de moeda da tarifa | | `direction` | Não | Object | `{column, debit, credit}`: a coluna que marca cada linha como débito ou crédito. Uma linha de débito é importada com valor negativo, uma de crédito com valor positivo. Apenas CSV, JSON e XML | O vocabulário canônico permanece fechado. O Matcher rejeita um mapa de campos que declare qualquer outra chave. Quando você mapeia `direction`, use uma coluna de valor sem sinal. O Matcher rejeita uma linha com valor com sinal, com a célula de direção vazia ou com um valor de direção desconhecido. Quando você envia um arquivo com o formato `camt053`, o Matcher usa o mapeamento ISO 20022 embutido e ignora o mapa de campos. A ativação trata como mapeada uma fonte que declara opções `camt053`. ### Exemplo de mapeamento Você mapeia um extrato bancário que expõe `TXN_ID`, `VALUE`, `CCY` e `POST_DATE` assim: ```json theme={null} { "external_id": "TXN_ID", "amount": "VALUE", "currency": "CCY", "date": "POST_DATE" } ``` ## Regra de correspondência *** Uma **regra de correspondência** diz ao Matcher como comparar transações. As regras rodam em ordem crescente de prioridade. Uma transação reivindicada por uma regra anterior fica indisponível para as regras seguintes, que ainda avaliam as transações restantes. ### Tipos de regra * **EXACT**: compara exatamente os campos configurados. Valor, moeda, data (por dia) e referência vêm habilitados por padrão. * **TOLERANCE**: corresponde valores dentro da tolerância absoluta e/ou percentual configurada. Moeda e referência também precisam corresponder por padrão. As tolerâncias de valor omitidas e `dateWindowDays` têm padrão `0`, então a regra não permite variação nem janela de data até você configurar uma. * **DATE\_LAG**: corresponde dentro de uma faixa configurada de diferença de dias. `minDays` e `maxDays` têm ambos o padrão `0` (mesmo dia). DATE\_LAG apenas propõe. Nunca autoconfirma. * **FUZZY**: gradua as referências normalizadas das transações. Usa `Reference`, preenchido a partir do `ExternalID` da transação. Um `description` do mapa de campos não é entrada para FUZZY. FUZZY apenas propõe. Nunca autoconfirma, então uma pessoa revisa cada ligação difusa. ### Ordem de prioridade Números menores rodam primeiro. Uma regra reivindica as transações que ela corresponde. As regras seguintes continuam com as transações restantes. | Prioridade | Regra | Descrição | | - | - | - | | 1 | Correspondência exata | Valor, data e referência devem coincidir | | 2 | Tolerância no mesmo dia | Mesma data, valor dentro de 0,5% | | 3 | Tolerância de uma semana | Dentro de 7 dias, valor dentro de 1% | > [!NOTE] > > Essas prioridades e valores são regras ilustrativas, não padrões do motor. Configure os valores conforme a sua política de conciliação. ### Parâmetros das regras | Tipo de regra | Parâmetros | | - | - | | EXACT | `matchAmount`, `matchCurrency`, `matchDate`, `matchReference`: quais campos devem coincidir exatamente | | TOLERANCE | Valores `percentTolerance` e/ou `absTolerance` não negativos no nível raiz (números ou strings decimais). `percentTolerance` é uma fração: `0.005` é 0,5%. A diferença permitida é o maior entre `absTolerance` e `percentTolerance` vezes o maior valor absoluto, com o `percentageBase` padrão. Opcionalmente, defina `dateWindowDays` (`0` por padrão; máximo `3650`). Não envolva esses valores em um objeto `tolerance`. | | DATE\_LAG | `minDays`, `maxDays`: faixa permitida de diferença de dias. Ambos têm padrão `0`, devem ficar de `0` a `3650`, e `maxDays` deve ser pelo menos `minDays`; `inclusive` tem padrão `true` e controla os dois limites. Os valores precisam ser iguais, a menos que você defina `feeTolerance`. | | FUZZY | `minSimilarity`: limiar de referência normalizada de `0` a `1` (padrão `0.80`), mais verificações de valor, moeda e data, ativas por padrão. | ## Correspondência *** Uma **correspondência** acontece quando transações de fontes diferentes são conciliadas juntas. ### Status da correspondência | Status | Descrição | | - | - | | `PROPOSED` | O Matcher encontrou, aguardando confirmação | | `CONFIRMED` | Aprovada automaticamente ou manualmente | | `REJECTED` | Rejeitada manualmente | | `REVOKED` | Uma correspondência antes confirmada foi desfeita, devolvendo suas transações para `UNMATCHED` | ### Padrões de correspondência #### Correspondência 1:1 Uma transação de cada fonte é conciliada. ``` Bank: $100.00 on Jan 15 → ERP: $100.00 on Jan 15 ``` #### Correspondência 1:N Uma transação é conciliada contra várias transações. ``` Bank: $300.00 → ERP: $100.00 + $100.00 + $100.00 ``` #### Correspondência N:1 Várias transações são conciliadas contra uma única transação. ``` Bank: $50.00 + $50.00 + $50.00 → ERP: $150.00 ``` #### Correspondência N:M Várias transações de cada lado são conciliadas juntas. A avaliação N:M executa apenas as regras `EXACT` e `TOLERANCE`. Ela considera até quatro transações por lado em um grupo. Ela ignora um bucket de candidatos que tenha mais de 40 transações em um lado. ``` Bank: $100.00 + $200.00 → ERP: $150.00 + $150.00 ``` ### Itens de correspondência Cada grupo de correspondência contém **itens de correspondência**, que registram a participação e a alocação das transações. Isso permite conciliação parcial em cenários de divisão e de agregação. ## Exceção *** Uma **exceção** registra uma transação que precisa de revisão, incluindo transações não conciliadas e transações conciliadas com condições residuais, como variação de câmbio. ### Status da exceção | Status | Descrição | | - | - | | `OPEN` | Aguardando atribuição | | `ASSIGNED` | Alguém está investigando | | `PENDING_RESOLUTION` | Uma resolução está em andamento, aguardando conclusão | | `RESOLVED` | Tratada | ### Severidade O Matcher classifica as exceções automaticamente para você saber o que priorizar. O valor é o valor absoluto do valor base da transação ou, quando ela não tem valor base, do valor dela. Para um item em aberto envelhecido, é o valor absoluto do saldo em aberto. | Severidade | Critérios padrão | | - | - | | **Crítica** | Valor ≥ 100.000 ou idade ≥ 120 horas | | **Alta** | Valor ≥ 10.000 ou idade ≥ 72 horas | | **Média** | Valor ≥ 1.000 ou idade ≥ 24 horas | | **Baixa** | Todos os demais casos | O classificador avalia os critérios de cima para baixo. Quando uma exceção atende aos critérios de mais de uma severidade, vale a severidade mais alta entre as que coincidem. O Matcher limita uma exceção com motivo `FEE_DATA_MISSING` a **Média**, qualquer que seja o valor ou a idade dela. ### Workflows de resolução * **Resolver**: registre um rótulo de resolução e um motivo opcional para fechar uma exceção. * **Forçar correspondência**: resolva uma exceção forçando uma correspondência com um motivo de substituição e notas depois de revisão manual. * **Ajustar lançamento**: resolva uma exceção criando um lançamento de ajuste com motivo, notas, valor positivo, moeda, momento de efeito e uma direção opcional `DEBIT` ou `CREDIT`. * **Correspondência manual**: resolva uma exceção pareando a transação dela em uma correspondência manual que leva o `exceptionId`. Uma execução de correspondência posterior também pode fechar uma exceção automaticamente. Veja [Resolver exceções](https://docs.lerian.studio/pt/products/matcher/daily-reconciliation/matcher-resolving-exceptions.md#resolved-by-a-match). ## Pontuação de confiança *** Uma **pontuação de confiança** indica a confiabilidade de uma correspondência automática em uma escala de 0–100. Pontuações mais altas representam alinhamento mais forte entre as transações. ### Cálculo da pontuação | Componente | Peso | Descrição | | - | - | - | | Correspondência de valor | 40% | Peso total quando os valores correspondem pela regra ou a regra não verifica valores; caso contrário, `0` | | Correspondência de moeda | 30% | Peso total quando as moedas correspondem; caso contrário, `0` | | Tolerância de data | 20% | Peso total quando as datas ficam dentro da janela da regra ou a regra não verifica datas; caso contrário, `0` | | Referência | 10% | Alinhamento da referência normalizada (graduado de 0–1 para regras FUZZY) | ### Faixas de confiança | Faixa | Intervalo de pontuação | Comportamento do sistema | | - | - | - | | **Aprovada automaticamente** | ≥ 90 | Confirmada automaticamente para correspondências EXACT e TOLERANCE. As correspondências FUZZY e DATE\_LAG sempre vão para revisão | | **Precisa de revisão** | 60–89 | Marcada para revisão manual | > [!NOTE] > > O motor fixa os pesos de confiança e os limiares das faixas. Eles não são configuráveis. ## Log de auditoria *** Um **log de auditoria** é um registro imutável e append-only criado por um workflow instrumentado. Ele dá rastreabilidade às ações que o Matcher registra. ### Eventos registrados Apenas os workflows instrumentados para emitir um evento de auditoria criam entradas. Os produtores verificados incluem: * Mutações de contexto, de fonte, de mapa de campos e de regra * Workflows de exceção, incluindo forçar correspondência e ajustar lançamento ### Conteúdo da entrada de auditoria | Campo | Descrição | | - | - | | `createdAt` | Timestamp de criação do registro (UTC), que pode diferir do momento da ação auditada | | `actorId` | Identificador do ator, quando informado | | `action` | Ação executada | | `entityType` | Tipo da entidade afetada | | `entityId` | Identificador da entidade afetada | | `changes` | Dados estruturados do evento em JSON; os eventos emitidos incluem `occurred_at` e quaisquer mudanças informadas | | `tenantSeq` | Número de sequência por tenant | | `prevHash` / `recordHash` | Cadeia de hash que liga cada entrada à anterior | > [!WARNING] > > Os logs de auditoria são append-only. O arquivamento exporta partições mensais antigas para o armazenamento de objetos e depois as remove do banco de dados. ## Próximos passos *** > [card] [Arquitetura](https://docs.lerian.studio/pt/products/matcher/matcher-architecture.md) > > Veja como os contextos delimitados implementam esses conceitos. > [card] [Início rápido](https://docs.lerian.studio/pt/products/matcher/getting-started/matcher-quick-start.md) > > Aplique esses conceitos em um fluxo guiado e prático. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.