> ## 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 as cinco etapas do ciclo de conciliação, da definição de um contexto até a resolução de exceções na sua primeira rodada de matches. Este guia apresenta o ciclo de vida de conciliação no Matcher, desde a configuração inicial até a revisão de resultados. O foco está nos conceitos e decisões envolvidas em cada etapa. Para instruções passo a passo com exemplos de requisições e respostas da API, consulte o [Início rápido da API do Matcher](/pt/reference/matcher/matcher-developer-quick-start). ## O ciclo de vida da conciliação *** Toda conciliação no Matcher segue o mesmo ciclo de cinco etapas: Criar um contexto que descreve o que você está conciliando e com que frequência. Registrar os sistemas cujas transações você deseja comparar. Definir os critérios que o Matcher usa para parear transações. Fazer upload dos dados e deixar o Matcher encontrar pares, começando com uma prévia antes de confirmar. Revisar transações não conciliadas e decidir como tratá-las. As seções a seguir explicam cada etapa. ## Definir escopo com um contexto *** Um **contexto** é o contêiner principal para um fluxo de conciliação. Ele responde três perguntas: * **O que você está conciliando?** Por exemplo, uma conta bancária contra seu livro razão. * **Que tipo de pareamento?** Um para um, um para muitos ou muitos para muitos. * **Com que frequência?** Diária, semanal, mensal ou sob demanda. | Tipo de pareamento | Quando usar | Exemplo | | ------------------ | ------------------------------------------------------------ | ------------------------------------------ | | `1:1` | Cada transação tem exatamente uma contraparte | Extrato bancário vs. lançamentos contábeis | | `1:N` | Um registro se mapeia para vários do outro lado | Uma única fatura paga em parcelas | | `N:M` | Múltiplos registros em ambos os lados se relacionam entre si | Pagamentos em lote divididos entre contas | A maioria das conciliações começa com `1:1`. Você pode alterar o tipo de pareamento posteriormente conforme seu processo evolui. Referência da API: [Criar contexto](/pt/reference/matcher/create-context) | [Atualizar contexto](/pt/reference/matcher/update-context) ## Conectar fontes de dados *** Cada contexto precisa de pelo menos **duas fontes**: os sistemas cujos dados de transações você deseja comparar. Uma fonte representa um único fluxo de dados, como um extrato bancário, uma exportação do livro razão ou um arquivo de gateway de pagamento. ### Tipos de fontes | Tipo | Uso típico | | --------- | --------------------------------------------------------- | | `BANK` | Extratos bancários e extratos de conta | | `LEDGER` | Exportações do livro razão ou ERP | | `GATEWAY` | Dados de processadores de pagamento (Stripe, Adyen, etc.) | | `CUSTOM` | Qualquer outro dado estruturado | ### Mapeamento de campos Arquivos de transações de sistemas diferentes raramente usam os mesmos nomes de coluna. Os **mapeamentos de campos** traduzem as colunas da sua fonte para o esquema padrão do Matcher para que as transações possam ser comparadas. Por exemplo, um arquivo bancário pode chamar a data da transação de "Post Date", enquanto seu livro razão a chama de "posting\_date". Os mapeamentos de campos normalizam ambas para o campo `date` do Matcher. Cada transação deve fornecer pelo menos quatro campos após o mapeamento: | Campo | Descrição | | ---------------- | ---------------------------------------- | | `transaction_id` | Identificador único dentro da fonte | | `amount` | Valor da transação | | `currency` | Código de moeda ISO 4217 (ex., USD, BRL) | | `date` | Data da transação | Referência da API: [Criar fonte](/pt/reference/matcher/create-source) | [Criar mapeamento de campos](/pt/reference/matcher/create-field-map) ## Configurar regras de match *** As regras definem **como o Matcher decide se duas transações são a mesma**. Você pode empilhar múltiplas regras com prioridades diferentes. O Matcher as avalia em ordem: apenas transações não pareadas pela primeira regra passam para a próxima. ### Tipos de regras | Regra | O que faz | Quando usar | | --------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | **Exata** | Exige valores idênticos nos campos selecionados | Quando os dados são limpos e os sistemas estão sincronizados | | **Tolerância** | Permite pequenas diferenças numéricas ou de data | Quando taxas bancárias, arredondamento ou atrasos de processamento causam discrepâncias menores | | **Defasagem de data** | Permite uma janela de data 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 captura primeiro todos os matches perfeitos. 2. **Prioridade 10 — Regra de tolerância** com uma tolerância de valor pequena (ex., 1%) e uma janela de 2 dias. Isso captura quase-matches causados por taxas ou timing. Conforme você observa resultados ao longo do tempo, ajuste as regras ou adicione novas para melhorar sua taxa de conciliação. Referência da API: [Criar regra de match](/pt/reference/matcher/create-match-rule) ## Executar matching *** Uma vez que as fontes estão configuradas e os dados foram enviados, você pode executar o motor de matching. ### Prévia primeiro, confirmação depois O Matcher suporta dois modos de execução: | Modo | Comportamento | | ----------- | ---------------------------------------------------------------------------- | | **Dry run** | Calcula matches e gera uma prévia. Nada é persistido. | | **Commit** | Persiste os resultados: matches confirmados, scores de confiança e exceções. | Sempre comece com um dry run. Revise a prévia para verificar a qualidade do matching antes de confirmar. ### Entendendo os scores de confiança Cada match recebe um score de confiança de 0 a 100: | Faixa de score | Significado | Ação necessária | | -------------- | --------------- | ---------------------------------------- | | 90–100 | Alta confiança | Auto-confirmado, nenhuma ação necessária | | 60–89 | Confiança média | Marcado para revisão manual | | Abaixo de 60 | Baixa confiança | Não pareado — torna-se uma exceção | Os scores são determinados por quão estreitamente as transações se alinham nos campos comparados e qual regra produziu o match. Regras exatas produzem scores mais altos que regras de tolerância. Referência da API: [Executar match](/pt/reference/matcher/run-match) | [Listar grupos de execução](/pt/reference/matcher/list-match-run-groups) ## Resolver 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 de exceções O Matcher classifica cada exceção por severidade com base no valor da transação e há quanto tempo ela está sem conciliar: | Severidade | Critério | SLA sugerido | | ----------- | ---------------------------------------------- | ------------ | | **Crítica** | Valor >= 100.000 ou sem conciliar >= 120 horas | 24 horas | | **Alta** | Valor >= 10.000 ou sem conciliar >= 72 horas | 72 horas | | **Média** | Valor >= 1.000 ou sem conciliar >= 24 horas | 5 dias | | **Baixa** | Todos os demais | 7 dias | ### Opções de resolução * **Forçar match** — Parear manualmente a transação com uma contraparte quando você sabe que pertencem juntas. * **Criar ajuste** — Registrar um lançamento de correção para contabilizar a diferença. * **Desfazer match** — Se um match confirmado estiver incorreto, desfazê-lo para que ambas as transações retornem ao pool de não conciliadas. * **Despachar** — Encaminhar a exceção para um sistema externo (ex., JIRA, Slack) para investigação. Referência da API: [Listar exceções](/pt/reference/matcher/list-exceptions) | [Desfazer match de grupo](/pt/reference/matcher/unmatch-group) ## Cenário de exemplo *** Uma fintech concilia seu extrato bancário diário contra registros internos do livro razão. **Configuração:** * Contexto: "Conciliação Bancária Diária", tipo `1:1`, intervalo `daily` * Duas fontes: Extrato do Chase Bank (`BANK`) e Livro Razão (`LEDGER`) * Duas regras: Match exato (prioridade 1) e Match por tolerância com 1% e janela de 2 dias (prioridade 10) **Fluxo de trabalho diário:** 1. O time financeiro faz upload do extrato bancário e da exportação do livro razão. 2. O Matcher executa um dry run. A prévia mostra que 95% das transações foram conciliadas com alta confiança. 3. O time revisa a prévia e confirma os resultados. 4. Cinco transações permanecem como exceções: duas têm pequenas diferenças por taxas, três não têm contraparte. 5. O time resolve as exceções de taxas criando ajustes. As três transações faltantes são escaladas para investigação. ## Próximos passos *** Guia completo para configurar contextos de conciliação. Aprofundamento em todos os tipos de regras e opções de configuração. Mapeie diferentes formatos de arquivo para o esquema padrão do Matcher. Estratégias para lidar com transações não conciliadas.