> ## 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. # Contextos e fontes > Saiba como os contextos definem o escopo da conciliação e como as fontes conectam os sistemas que alimentam dados de transações no Matcher. Contextos e fontes são a forma como você diz ao Matcher **o que** conciliar e **de onde vêm os números**. São os dois blocos de construção que você configura antes de qualquer correspondência acontecer. * Um **contexto** é uma conciliação específica com a qual você se importa — por exemplo, *"nossa conta bancária principal vs. nossos livros contábeis."* Ele define o escopo: quais sistemas são comparados, quais regras se aplicam e sobre qual período. * Uma **fonte** é um dos sistemas que alimenta números nessa comparação — um extrato bancário, uma exportação de ERP, um arquivo de liquidação de um processador de pagamentos ou um razão contábil. Todo contexto compara exatamente dois lados entre si, então cada um precisa de pelo menos duas fontes. Acerte esses elementos e tudo o que vem depois — correspondência, exceções e relatórios — segue naturalmente. ## O que é um contexto de conciliação? *** Um contexto de conciliação define os limites operacionais de um processo de conciliação. Ele especifica: * Quais fontes de dados são comparadas * Quais regras de correspondência se aplicam * Como as exceções são tratadas * A janela de tempo coberta pela conciliação **Exemplos comuns:** * *Conta Bancária 1234 vs Razão Geral* (conciliação bancária diária) * *Gateway de Pagamento vs Sistema de Receita* (conciliação de pagamentos) * *Intercompany Entidade A vs Entidade B* (conciliação intercompany) ## Tipos de contexto *** O Matcher permite usar diferentes cardinalidades de conciliação baseadas na estrutura das transações. ### Um-para-um (1:1) Cada transação é conciliada contra uma única contraparte. **Casos de uso típicos:** * Extratos bancários * Correspondência de pagamentos diretos ### Um-para-muitos (1:n) Uma transação é conciliada contra múltiplas contrapartes. **Casos de uso típicos:** * Pagamentos divididos * Depósitos em lote * Faturas consolidadas ### Muitos-para-muitos (n:m) Múltiplas transações são conciliadas entre múltiplas contrapartes. **Casos de uso típicos:** * Arranjos de netting * Alocação complexa de pagamentos * Fluxos financeiros multi-leg ## Criando um contexto de conciliação *** Uma vez que você sabe o que está conciliando, crie o contexto. Nesta etapa você está principalmente declarando a cardinalidade (`type`), com que frequência ele é executado (`interval`) e qualquer tolerância de taxa que a comparação deve permitir. Um novo contexto começa em `DRAFT` para que você possa adicionar fontes e regras antes de colocá-lo em produção. #### Request ```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": "Daily Bank Reconciliation", "interval": "daily", "type": "1:1", "feeToleranceAbs": 0, "feeTolerancePct": 0, "feeNormalization": "NET", "autoMatchOnUpload": false }' ``` #### Campos do contexto Nome descritivo para o contexto Cardinalidade da correspondência: `1:1`, `1:N` ou `N:M` Frequência de conciliação (ex: `daily`, `weekly`) Tolerância absoluta de taxa para comparação de valores Tolerância percentual de taxa para comparação de valores Modo de normalização de taxa: `NET` ou `GROSS` Disparar automaticamente uma execução de correspondência quando um arquivo é carregado #### Response ```json theme={null} { "id":"019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "tenantId":"11111111-1111-1111-1111-111111111111", "name":"Daily Bank Reconciliation", "type":"1:1", "interval":"daily", "status":"DRAFT", "feeToleranceAbs":"0", "feeTolerancePct":"0", "feeNormalization":"NET", "autoMatchOnUpload":false, "createdAt":"2026-02-02T16:31:22Z", "updatedAt":"2026-02-02T16:31:22Z" } ``` Referência da API: [Criar contexto](/pt/reference/matcher/create-context) ## Executando conciliação *** Um contexto não concilia por conta própria — você dispara uma **execução de correspondência**. Uma execução aplica as regras ativas do contexto às transações em suas fontes e, em seguida, produz correspondências e exceções. Você pode disparar execuções manualmente ou deixar que um [agendamento](/pt/matcher/configuration/matcher-schedules) as dispare automaticamente. Toda execução funciona em um de dois modos: | Modo | O que faz | | --------- | ------------------------------------------------------------------------------------------------- | | `DRY_RUN` | Prévia das correspondências sem salvar nada — use-o para validar mudanças de regras com segurança | | `COMMIT` | Executa a correspondência e persiste os resultados | Dispare uma execução para um contexto: ```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": "COMMIT" }' ``` Por padrão, uma execução é **síncrona** — ela ocorre dentro da requisição e a resposta carrega o status final. Para grandes volumes, defina `"async": true` para enviar a execução e acompanhar seu progresso por consulta. Ambos os modos retornam **HTTP 202 Accepted**, portanto leia o `status` da resposta, não o código HTTP, para saber o resultado. Uma execução síncrona retorna um `COMPLETED` ou `FAILED` terminal; uma execução assíncrona retorna `QUEUED`, e você consulta `GET /v1/matching/runs/{runId}`. Enquanto está em andamento, uma execução passa por `PROCESSING` e `FINALIZING` (trate ambos como ainda não concluídos) antes de alcançar `COMPLETED` ou `FAILED`. Para revisar execuções passadas, liste o histórico de execuções de um contexto com `GET /v1/matching/contexts/{contextId}/runs`. Referência da API: [Executar correspondência](/pt/reference/matcher/run-match) | [Listar execuções de correspondência](/pt/reference/matcher/list-match-runs) ## O que é uma fonte? *** Uma fonte representa um sistema ou feed de dados que fornece transações para um contexto de conciliação. Cada contexto requer pelo menos duas fontes. **Fontes típicas incluem:** * Feeds de extratos bancários * Exportações do razão geral do ERP * Streams de transações de processadores de pagamento * Sistemas contábeis internos ## Adicionando fontes a um contexto *** Um contexto precisa de pelo menos duas fontes — uma para cada lado da comparação. O campo `side` (`LEFT` ou `RIGHT`) declara qual lado uma fonte alimenta; o Matcher concilia o lado `LEFT` contra o lado `RIGHT`. Atribua um lado a cada fonte e mantenha a atribuição consistente. Crie uma fonte com um `name`, `type`, `side` e um objeto `config`. Deixe `config` vazio (`{}`) quando a fonte não precisa de configurações específicas de conexão — como no caso de um feed bancário no lado `LEFT`: ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Chase Bank - Account 1234", "type": "BANK", "side": "LEFT", "config": {} }' ``` Aponte o outro lado para uma segunda fonte. `config` carrega as configurações de conexão e parsing específicas da fonte quando são necessárias — por exemplo, um gateway de pagamento no lado `RIGHT`: ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Payment Gateway", "type": "GATEWAY", "side": "RIGHT", "config": { "currency": "USD", "provider": "stripe" } }' ``` `name`, `type`, `side` e `config` são todos obrigatórios (`name` tem de 1 a 50 caracteres; `config` pode ser `{}`). Referência da API: [Criar fonte](/pt/reference/matcher/create-source) ### Tipos de fonte | Tipo | Descrição | Uso típico | | --------- | --------------------------------- | -------------------------------------------------- | | `LEDGER` | Razão interno | Sistemas contábeis internos (incluindo Midaz) | | `BANK` | Feed de extratos bancários | Feeds de bancos externos | | `GATEWAY` | Gateway de pagamento | Processadores de pagamento (Stripe, Adyen, PayPal) | | `CUSTOM` | Feed sob medida | Qualquer outra fonte de dados | | `FETCHER` | Extração pelo motor de descoberta | Conexões de agregador puxadas automaticamente | ### Fontes fetcher Uma fonte `FETCHER` tem seus dados puxados automaticamente em vez de serem carregados. Crie-a como qualquer outra fonte, depois conecte a conexão com o agregador upstream através de um [binding de fonte](#bindings-de-fonte) no trilho de consulta (`connectionId`) — veja [Descoberta](/pt/matcher/integrations/matcher-discovery) para saber como as conexões são configuradas. ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Open Banking Aggregator", "type": "FETCHER", "side": "LEFT", "config": { "provider": "pluggy" } }' ``` ## Gerenciando fontes *** As fontes suportam um ciclo de vida CRUD completo em `/v1/contexts/{contextId}/sources`. Você pode renomear ou reconfigurar uma fonte a qualquer momento, e **o arquivamento é lógico e reversível** — uma fonte arquivada para de alimentar novos dados, mas mantém todo o seu histórico até você restaurá-la. | Ação | Método e caminho | Observações | | --------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------- | | Criar fonte | `POST /v1/contexts/{contextId}/sources` | Corpo: `name`, `type`, `side`, `config` (veja acima). | | Listar fontes | `GET /v1/contexts/{contextId}/sources` | Lista as fontes do contexto. | | Obter fonte | `GET /v1/contexts/{contextId}/sources/{sourceId}` | Recupera uma única fonte por id. | | Atualizar fonte | `PATCH /v1/contexts/{contextId}/sources/{sourceId}` | Atualiza campos mutáveis da fonte (ex: `name`, `config`). | | Arquivar fonte | `POST /v1/contexts/{contextId}/sources/{sourceId}/archive` | Arquiva a fonte de forma lógica; ela para de alimentar novos dados, mas é retida. | | Restaurar fonte | `POST /v1/contexts/{contextId}/sources/{sourceId}/restore` | Reativa uma fonte previamente arquivada. | Referência da API: * [Criar fonte](/pt/reference/matcher/create-source) * [Obter fonte](/pt/reference/matcher/retrieve-source) * [Atualizar fonte](/pt/reference/matcher/update-source) * [Arquivar fonte](/pt/reference/matcher/archive-source) * [Restaurar fonte](/pt/reference/matcher/restore-source) ## Bindings de fonte *** Os bindings são a forma como uma fonte puxa seus próprios dados automaticamente, para que ninguém precise carregar arquivos manualmente. Um **binding de fonte** vincula uma fonte ao trilho que fornece suas transações, além de um agendamento de intervalo indicando com que frequência puxar. Exatamente um trilho é relevante por `kind` de binding: * `file` — busca arquivos por meio de um transporte (preenche `transportConfig`). * `query` — puxa linhas através de uma conexão do motor de descoberta (preenche `connectionId`; veja [Descoberta](/pt/matcher/integrations/matcher-discovery)). Os bindings ficam em `/v1/contexts/{contextId}/sources/{sourceId}/bindings`. | Ação | Método e caminho | | ----------------- | ------------------------------------------------------------------------- | | Criar binding | `POST /v1/contexts/{contextId}/sources/{sourceId}/bindings` | | Listar bindings | `GET /v1/contexts/{contextId}/sources/{sourceId}/bindings` | | Obter binding | `GET /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}` | | Atualizar binding | `PATCH /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}` | | Excluir binding | `DELETE /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}` | A listagem retorna **todos** os bindings, habilitados e desabilitados, de forma que um binding desabilitado permaneça visível em vez de desaparecer silenciosamente. ### Criar um binding no trilho de consulta ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/bindings" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "kind": "query", "connectionId": "550e8400-e29b-41d4-a716-446655440000", "format": "br/cnab400/default", "scheduleSpec": "@every 1h", "enabled": true }' ``` #### Campos Trilho pelo qual a fonte é puxada: `file` ou `query` (obrigatório). Conexão do motor de descoberta no trilho de consulta. Obrigatório para `query`, rejeitado para `file`. Formato declarado que o binding produz (chave descritora com namespace de região/família, ex: `br/cnab400/default`). Agendamento de intervalo que o agendador de bindings lê (cron ou duração `@every`). Se o binding é executado imediatamente. O padrão é `true`. Referência da API: * [Criar binding de fonte](/pt/reference/matcher/create-source-binding) * [Listar bindings de fonte](/pt/reference/matcher/list-source-bindings) * [Obter binding de fonte](/pt/reference/matcher/get-source-binding) * [Atualizar binding de fonte](/pt/reference/matcher/update-source-binding) * [Excluir binding de fonte](/pt/reference/matcher/delete-source-binding) ## Gerenciando contextos *** À medida que as conciliações evoluem, você ajustará as configurações de um contexto, o pausará, o aposentará ou o copiará. Essas operações de ciclo de vida preservam o histórico para que você nunca perca uma trilha de auditoria. ### Atualizar um contexto ```bash cURL theme={null} curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Daily Bank Reconciliation - Updated", "interval": "weekly", "status": "PAUSED" }' ``` Referência da API: [Atualizar contexto](/pt/reference/matcher/update-context) ### Pausar um contexto Para temporariamente impedir que um contexto seja usado em execuções de conciliação, atualize seu status para `PAUSED`: ```bash cURL theme={null} curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "PAUSED" }' ``` Pausar um contexto: * Impede novas execuções de correspondência * Preserva dados históricos * Permite reativação futura definindo o status de volta para `ACTIVE` ### Arquivar um contexto Arquivar é uma exclusão lógica reversível. Em vez de remover permanentemente um contexto, ela move o contexto para o status `ARCHIVED`, preservando todo o seu histórico (fontes, regras, execuções de correspondência e registros de auditoria) enquanto o exclui da listagem de contextos padrão. ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/archive" \ -H "Authorization: Bearer $TOKEN" ``` Arquivar um contexto: * Define o status do contexto como `ARCHIVED` * Preserva o histórico completo e a trilha de auditoria * Exclui o contexto da listagem padrão * Pode ser revertido a qualquer momento com o endpoint de [restauração](#restaurar-um-contexto) Referência da API: [Arquivar contexto](/pt/reference/matcher/archive-context) ### Restaurar um contexto Restaurar reverte um arquivamento, movendo o contexto de `ARCHIVED` de volta para `DRAFT` para que ele possa ser revisado e reconfigurado antes de ser reativado. ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/restore" \ -H "Authorization: Bearer $TOKEN" ``` Restaurar um contexto: * Define o status do contexto de `ARCHIVED` de volta para `DRAFT` * **Não** retoma a correspondência automaticamente — revise e reative o contexto para executar a conciliação novamente * Retorna `409 Conflict` se chamado em um contexto que não está arquivado Referência da API: [Restaurar contexto](/pt/reference/matcher/restore-context) ### Clonar um contexto Para duplicar um contexto existente com suas fontes, regras, regras de taxas e mapeamentos de campos, use o endpoint de clonagem. Isso é útil para criar templates ou replicar configurações entre ambientes. As regras de taxas clonadas continuam referenciando as mesmas tabelas de taxas do contexto de origem; as tabelas de taxas em si não são copiadas. ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/clone" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Q1 2025 Reconciliation (Copy)", "includeSources": true, "includeRules": true, "includeFeeSchedules": true }' ``` A resposta informa quantas fontes, regras, regras de taxas e mapeamentos de campos foram copiados. O contexto clonado inicia no status `DRAFT`, para que você possa revisar e ajustar a configuração antes de ativá-lo. Referência da API: [Clonar contexto](/pt/reference/matcher/clone-context) ## Ciclo de vida do contexto *** Um contexto de conciliação segue um ciclo de vida bem definido que controla quando a correspondência pode ser executada e como os dados são preservados. * Um contexto é primeiro criado em **Draft**, onde fontes e configurações são definidas. * Uma vez que todas as fontes necessárias estão em vigor, o contexto se torna **Active** e está elegível para execuções de conciliação. * Um contexto ativo pode ser temporariamente **Paused** para parar a execução sem afetar a configuração ou dados históricos. * Quando um contexto não é mais necessário, ele pode ser **Archived** por meio do endpoint de [arquivamento](#arquivar-um-contexto). Arquivar é uma exclusão lógica reversível: move o contexto para `ARCHIVED`, preserva o histórico completo e os registros de auditoria, e o exclui da listagem padrão. Um contexto arquivado pode voltar para **Draft** a qualquer momento com o endpoint de [restauração](#restaurar-um-contexto). Ciclo de Vida do Contexto do Matcher Este ciclo de vida garante controle operacional, execução previsível e rastreabilidade completa ao longo dos períodos de conciliação. ## Boas práticas *** Use nomes explícitos que reflitam contas, sistemas e propósito. Favoreça precisão sobre automação inicialmente. Ajuste os limites baseado nos resultados observados. Use múltiplos contextos em vez de uma única conciliação ampla. Sempre marque fontes com requisitos de compliance. Certifique-se de que os fusos horários das fontes reflitam o feed de dados original. Defina explicitamente a semântica de débito e crédito para cada fonte. ## Próximos passos *** Defina como os campos da fonte mapeiam para o schema do Matcher. Configure as regras que orientam a conciliação.