> ## 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. # Primeiros passos com o Matcher > Percorra o ciclo de vida de conciliação em cinco estágios do Matcher. Defina um contexto, conecte fontes, ajuste regras, rode a correspondência e resolva exceções passo a passo. Este guia percorre o ciclo de vida da conciliação no Matcher, da configuração inicial à revisão dos resultados. Ele foca nos conceitos e nas decisões de cada estágio. Para instruções passo a passo da API com exemplos de requisição e resposta, veja o [início rápido da API do Matcher](/pt/reference/products/matcher/matcher-developer-quick-start). ## O ciclo de vida da conciliação *** Cada conciliação no Matcher segue o mesmo ciclo de vida de cinco estágios: Crie um contexto que descreve o que você concilia e registra o intervalo de conciliação dele. Registre os sistemas cujas transações você quer comparar. Configure os critérios que o Matcher usa para parear transações. Envie os dados e deixe o Matcher achar os pares, começando por uma prévia antes do commit. Revise as transações não conciliadas e decida como tratá-las. As seções abaixo explicam cada estágio. ## Defina o escopo com um contexto *** Um **contexto** é o contêiner de nível mais alto de um workflow de conciliação. Ele responde três perguntas: * **O que você concilia?** Por exemplo, uma conta bancária contra seu razão geral. * **Qual tipo de pareamento?** Um para um, um para muitos ou muitos para muitos. * **Qual rótulo de intervalo descreve o período de conciliação?** Por exemplo, `daily`, `weekly` ou `on-demand`. O valor obrigatório `interval` é metadado de texto livre. Ele não agenda execução. As execuções automáticas usam um `ReconciliationSchedule` separado, apoiado em cron, com cadência mínima de cinco minutos. | Tipo de pareamento | Quando usar | Exemplo | | ------------------ | ------------------------------------------------------ | ------------------------------------------ | | `1:1` | Cada transação tem exatamente uma contraparte | Extrato bancário vs. lançamentos do ledger | | `1:N` | Um registro corresponde a vários do outro lado | Uma única fatura paga em parcelas | | `N:M` | Vários registros dos dois lados se relacionam entre si | Pagamentos em lote divididos entre contas | A maioria das conciliações começa com `1:1`. Você pode mudar o tipo de pareamento depois, conforme seu processo evolui. Referência da API: * [Criar contexto](/pt/reference/products/matcher/create-context) * [Atualizar contexto](/pt/reference/products/matcher/update-context) ## Conecte as fontes de dados *** Cada contexto precisa de pelo menos **duas fontes**: os sistemas cujos dados de transação você quer comparar. Uma fonte representa um único feed de dados, como um extrato bancário, uma exportação de ledger ou um arquivo de gateway de pagamento. ### Tipos de fonte | Tipo | Uso típico | | --------- | ------------------------------------------------------ | | `BANK` | Extratos bancários e extratos de conta | | `LEDGER` | Exportações do razão geral ou de ERP | | `GATEWAY` | Dados de processador de pagamento (Stripe, Adyen etc.) | | `FETCHER` | Dados extraídos pelo Discovery | | `CUSTOM` | Qualquer outro dado estruturado | ### Mapeamento de campos Arquivos de transações de sistemas diferentes raramente usam os mesmos nomes de coluna. Os **mapas de campo** traduzem as colunas da sua fonte para o schema padrão do Matcher, para que as transações possam ser comparadas. Por exemplo, um arquivo de banco pode chamar a data da transação de "Post Date", enquanto seu ledger a chama de "posting\_date". Os mapas de campo normalizam as duas para o campo `date` do Matcher. Cada transação deve fornecer pelo menos quatro campos depois do mapeamento: | Campo | Descrição | | ------------- | ------------------------------------------------ | | `external_id` | Identificador único dentro da fonte | | `amount` | Valor da transação | | `currency` | Código de moeda ISO 4217 (por exemplo, USD, BRL) | | `date` | Data da transação | Referência da API: [Criar fonte](/pt/reference/products/matcher/create-source) | [Criar mapa de campo](/pt/reference/products/matcher/create-field-map) ## Defina as regras de correspondência *** As regras definem **como o Matcher decide se duas transações são a mesma**. Você pode empilhar várias regras com prioridades diferentes. O Matcher as avalia em ordem: apenas as transações que a primeira regra deixou não conciliadas passam para a próxima. ### Tipos de regra | Regra | O que ela faz | Quando usar | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **Exata** | Exige valores idênticos nos campos selecionados | Quando os dados estão limpos e os sistemas estão sincronizados | | **Tolerância** | Permite pequenas diferenças numéricas ou de data | Quando tarifas bancárias, arredondamento ou atrasos de processamento causam pequenas divergências | | **Fuzzy** | Usa similaridade normalizada de texto nas referências. Valor, moeda e data devem coincidir por padrão, mas você pode configurar cada verificação de forma independente. | Quando referências em texto livre ou truncadas variam entre as fontes | | **Defasagem de data** | Permite uma janela de datas configurável | Quando as datas de liquidação diferem entre sistemas | ### Configuração inicial recomendada 1. **Prioridade 1: regra Exata** em valor, moeda e data. Isso pega todas as correspondências perfeitas primeiro. 2. **Prioridade 10: regra de Tolerância** com uma pequena tolerância de valor (por exemplo, 1%) e uma janela de datas de 2 dias. Isso pega correspondências aproximadas causadas por tarifas ou por prazos. Conforme você observa os resultados ao longo do tempo, ajuste as regras ou adicione novas para melhorar sua taxa de correspondência. Referência da API: [Criar regra de correspondência](/pt/reference/products/matcher/create-match-rule) ## Rode a correspondência *** Depois que as fontes estiverem configuradas e os dados enviados, você pode rodar o motor de correspondência. ### Primeiro a prévia, depois o commit O Matcher oferece dois modos de execução: | Modo | Comportamento | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Dry run** | Calcula as correspondências e gera uma prévia sem persistir artefatos de correspondência nem exceções. Ele cria e conclui um registro `MatchRun`. | | **Commit** | Persiste os resultados: correspondências confirmadas, pontuações de confiança e exceções. | Sempre comece com um dry run. Revise a prévia para verificar a qualidade das correspondências antes do commit. ### Entenda as pontuações de confiança Cada correspondência recebe uma pontuação de confiança de 0 a 100: | Faixa de pontuação | Significado | Ação necessária | | ------------------ | --------------- | ------------------------------------------------------------------------------------------------------ | | 90–100 | Confiança alta | Elegível para confirmação automática, exceto os grupos `FUZZY` e `DATE_LAG`, que sempre exigem revisão | | 60–89 | Confiança média | Marcada para revisão manual | | Abaixo de 60 | Confiança baixa | Não conciliada — vira uma exceção | As pontuações derivam dos componentes correspondidos e dos pesos configurados para eles. As regras exata e de tolerância usam o mesmo esquema de pesos. Nenhum dos dois tipos de regra gera pontuações mais altas por natureza. Referência da API: [Rodar correspondência](/pt/reference/products/matcher/run-match) | [Listar grupos de execução de correspondência](/pt/reference/products/matcher/list-match-run-groups) ## Resolva as exceções *** Exceções são transações que o Matcher não conseguiu parear automaticamente. Elas representam os itens que precisam de atenção humana. ### Severidade das exceções O Matcher classifica cada exceção por severidade com base no valor da transação e no tempo que ela está não conciliada: | Severidade | Critério | SLA sugerido | | ----------- | -------------------------------------------------- | ------------ | | **Crítica** | Valor >= 100.000 ou não conciliada há >= 120 horas | 24 horas | | **Alta** | Valor >= 10.000 ou não conciliada há >= 72 horas | 72 horas | | **Média** | Valor >= 1.000 ou não conciliada há >= 24 horas | 5 dias | | **Baixa** | Todas as outras | 7 dias | ### Opções de resolução * **Forçar correspondência**: pareie a transação manualmente com uma contraparte quando você souber que as duas pertencem uma à outra. * **Criar ajuste**: registre um lançamento de correção para dar conta da diferença. * **Desfazer correspondência**: se uma correspondência confirmada estiver errada, desfaça-a para que as duas transações voltem ao conjunto não conciliado. * **Despachar**: envie a exceção pela rota de JIRA ou de webhook configurada para ela. Essa ação dirigida pelo chamador não muda o status dela. Referência da API: * [Listar exceções](/pt/reference/products/matcher/list-exceptions) * [Desfazer correspondência do grupo](/pt/reference/products/matcher/unmatch-group) ## Cenário de exemplo *** Uma fintech concilia o extrato bancário diário dela com os registros do ledger interno. **Configuração:** * Contexto: "Daily Bank Reconciliation", tipo `1:1`, intervalo `daily` * Duas fontes: extrato do Chase Bank (`BANK`) e razão geral (`LEDGER`) * Duas regras: correspondência Exata (prioridade 1) e correspondência por Tolerância com 1% e janela de 2 dias (prioridade 10) **Workflow diário:** 1. O financeiro envia o extrato bancário e a exportação do ledger. 2. O Matcher roda um dry run. A prévia mostra 95% das transações conciliadas com confiança alta. 3. O time revisa a prévia e faz o commit dos resultados. 4. Cinco transações continuam como exceções: duas têm pequenas diferenças de tarifa, três não têm contraparte. 5. O time resolve as exceções de tarifa criando ajustes. As três transações ausentes são escaladas para investigação. ## Próximos passos *** Guia completo para configurar contextos de conciliação. Aprofundamento em todos os tipos de regra e opções de configuração. Mapeie diferentes formatos de arquivo para o schema padrão do Matcher. Estratégias para tratar transações não conciliadas.