> ## 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 > Configure um contexto de conciliação e as fontes dele no Matcher. Escolha a cardinalidade 1:1, 1:N ou N:M, adicione feeds de banco e de ledger e dispare execuções de correspondência. Contextos e fontes são como você diz ao Matcher o que conciliar e de onde vêm os números. Você configura esses dois blocos antes de qualquer correspondência acontecer. * Um **contexto** é uma conciliação específica que importa para você. Por exemplo, *"nossa conta bancária principal vs. nossos livros."* Ele define o escopo: quais sistemas comparar, quais regras se aplicam e em qual período. * Uma **fonte** é um dos sistemas que alimentam 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 ledger. Cada contexto compara exatamente dois lados entre si, então cada um precisa de pelo menos duas fontes. Correspondência, exceções e relatórios dependem desses dois. ## 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 comparar * Quais regras de correspondência se aplicam * Como tratar exceções * 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) * *Entidade Intercompanhia A vs Entidade B* (conciliação intercompanhia) ## Tipos de contexto *** O Matcher permite usar cardinalidades de conciliação diferentes conforme a estrutura da transação. ### Um para um (1:1) O Matcher concilia cada transação contra uma única contraparte. **Casos de uso típicos:** * Extratos bancários * Correspondência direta de pagamentos ### Um para muitos (1:n) O Matcher concilia uma transação contra várias contrapartes. **Casos de uso típicos:** * Pagamentos divididos * Depósitos em lote * Faturas consolidadas ### Muitos para muitos (n:m) O Matcher concilia várias transações entre várias contrapartes. **Casos de uso típicos:** * Acordos de netting * Alocação complexa de pagamentos * Fluxos financeiros com várias pernas ## Como criar um contexto de conciliação *** Depois de saber o que vai conciliar, crie o contexto. Nesta etapa você declara principalmente a cardinalidade (`type`), um rótulo de execução obrigatório (`interval`) e qualquer tolerância de tarifa que a comparação deva permitir. O valor de `interval` não agenda execuções. A execução automática exige um [agendamento de conciliação](/pt/products/matcher/configuration/matcher-schedules) separado. Um novo contexto começa em `DRAFT` e permanece assim até você ativá-lo explicitamente. #### Requisição ```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 do contexto Cardinalidade de correspondência: `1:1`, `1:N` ou `N:M` Rótulo de execução obrigatório (por exemplo `daily`, `weekly`). Ele não agenda execuções. Tolerância absoluta de tarifa para comparação de valor, como string decimal (por exemplo `"0.01"`) Tolerância percentual de tarifa para comparação de valor, como string decimal (`"0.5"` significa 0,5%) Modo opcional de normalização de tarifa: `NET` ou `GROSS`. Omita o campo para deixar a normalização de tarifa desabilitada. Dispara automaticamente uma execução de correspondência depois do upload de um arquivo #### Resposta ```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/products/matcher/create-context) ## Como rodar a conciliação *** Um contexto não concilia sozinho. Você dispara uma **execução de correspondência**. Uma execução aplica as regras ativas do contexto às transações das fontes dele e então produz correspondências e exceções. Você pode disparar execuções na mão ou deixar um [agendamento](/pt/products/matcher/configuration/matcher-schedules) dispará-las automaticamente. Cada execução funciona em um de dois modos: | Modo | O que ele faz | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DRY_RUN` | Não persiste resultados de correspondência, mutações de transação, artefatos de tarifa nem exceções, mas persiste um `MatchRun` concluído e as estatísticas dele | | `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 roda dentro da requisição e a resposta carrega o status final. Para volumes grandes, defina `"async": true` para submeter a execução e acompanhar o progresso dela por polling. A submissão assíncrona exige um worker de execução de correspondência habilitado. Sem ele, o Matcher rejeita `"async": true` com HTTP 503. Os dois modos retornam **HTTP 202 Accepted**, então 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}` por polling. Enquanto está em andamento, uma execução passa por `PROCESSING` e `FINALIZING` (trate os dois como ainda não concluídos) antes de chegar a `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: * [Rodar correspondência](/pt/reference/products/matcher/run-match) * [Listar execuções de correspondência](/pt/reference/products/matcher/list-match-runs) ## O que é uma fonte? *** Uma fonte representa um sistema ou feed de dados que fornece transações a um contexto de conciliação. Cada contexto exige pelo menos duas fontes. **Fontes típicas incluem:** * Feeds de extrato bancário * Exportações do razão geral de ERP * Streams de transações de processadores de pagamento * Sistemas contábeis internos ## Como adicionar 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 `name`, `type`, `side` e um objeto `config`. Deixe `config` vazio (`{}`) quando a fonte não precisar de ajustes de conexão específicos, como em 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 ajustes de conexão e de parsing específicos da fonte quando eles são necessários, 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` e `side` são obrigatórios (`name` tem de 1 a 50 caracteres). `config` é opcional e assume um objeto vazio como padrão quando omitido. Referência da API: [Criar fonte](/pt/reference/products/matcher/create-source) ### Tipos de fonte | Tipo | Descrição | Uso típico | | --------- | ---------------------------- | -------------------------------------------------------- | | `LEDGER` | Ledger interno | Sistemas contábeis internos (incluindo o Midaz) | | `BANK` | Feed de extrato bancário | Feeds bancários externos | | `GATEWAY` | Gateway de pagamento | Processadores de pagamento (Stripe, Adyen, PayPal) | | `CUSTOM` | Feed sob medida | Qualquer outra fonte de dados | | `FETCHER` | Fonte do motor de descoberta | Conexões de agregador fornecidas por um binding de fonte | ### Fontes de descoberta `FETCHER` identifica um tipo de fonte. Ele não habilita a coleta automática sozinho. Crie-o como qualquer outra fonte, depois ligue a conexão do agregador upstream por um [binding de fonte](#source-bindings) no trilho de consulta (`connectionId`). Veja [Discovery](/pt/products/matcher/integrations/matcher-discovery) para saber como configurar conexões. ```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" } }' ``` ## Como gerenciar fontes *** As fontes têm um ciclo de vida CRUD completo em `/v1/contexts/{contextId}/sources`. Você pode renomear ou reconfigurar uma fonte a qualquer momento, e **o arquivamento é suave e reversível**. Uma fonte arquivada fica fora da prontidão do contexto, da correspondência e das listagens de fontes, mas mantém todo o histórico dela até você restaurá-la. O arquivamento não desabilita os bindings dela. Desabilite ou exclua os bindings separadamente para parar o despacho do scheduler. | Ação | Método e caminho | Notas | | --------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | 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 pelo id. | | Atualizar fonte | `PATCH /v1/contexts/{contextId}/sources/{sourceId}` | Atualiza campos mutáveis da fonte (por exemplo `name`, `config`). | | Arquivar fonte | `POST /v1/contexts/{contextId}/sources/{sourceId}/archive` | Tira a fonte da prontidão, da correspondência e das listagens; os bindings continuam habilitados até serem alterados separadamente. | | Restaurar fonte | `POST /v1/contexts/{contextId}/sources/{sourceId}/restore` | Reativa uma fonte arquivada antes. | Referência da API: * [Criar fonte](/pt/reference/products/matcher/create-source) * [Obter fonte](/pt/reference/products/matcher/retrieve-source) * [Atualizar fonte](/pt/reference/products/matcher/update-source) * [Arquivar fonte](/pt/reference/products/matcher/archive-source) * [Restaurar fonte](/pt/reference/products/matcher/restore-source)

Bindings de fonte

*** Os bindings definem como o scheduler de bindings pode puxar dados da fonte sem upload manual de arquivo. Um **binding de fonte** amarra uma fonte ao trilho que fornece as transações dela, mais uma duração que determina quando ele vence. Exatamente um trilho se aplica a cada `kind` de binding: * `file`: busca arquivos por um transporte (preenche `transportConfig`). * `query`: puxa linhas por uma conexão do motor de descoberta (preenche `connectionId`). Veja [Discovery](/pt/products/matcher/integrations/matcher-discovery). Os bindings ficam em `/v1/contexts/{contextId}/sources/{sourceId}/bindings`. Um binding é despachado apenas quando o scheduler de bindings está habilitado (ele vem desabilitado por padrão), o binding está habilitado e o binding está vencido. Criar ou habilitar um binding não o executa imediatamente. | 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 cada binding, habilitado e desabilitado, então um binding desabilitado continua visível em vez de sumir sem aviso. ### Como 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": "1h", "enabled": true }' ``` #### Campos Trilho em que o scheduler puxa a fonte: `file` ou `query` (obrigatório). Conexão do motor de descoberta no trilho de consulta. Obrigatória para `query`, rejeitada para `file`. Formato declarado que o binding produz (chave de descritor com namespace de região/família, por exemplo `br/cnab400/default`). String de duração do Go que o scheduler de bindings lê, como `1h` ou `30m`. As sintaxes cron e `@every` são inválidas. Se o scheduler pode despachar o binding quando ele vence. O padrão é `true`. Habilitá-lo não o executa imediatamente. Referência da API: * [Criar binding de fonte](/pt/reference/products/matcher/create-source-binding) * [Listar bindings de fonte](/pt/reference/products/matcher/list-source-bindings) * [Obter binding de fonte](/pt/reference/products/matcher/get-source-binding) * [Atualizar binding de fonte](/pt/reference/products/matcher/update-source-binding) * [Excluir binding de fonte](/pt/reference/products/matcher/delete-source-binding) ## Como gerenciar contextos *** Você pode alterar as configurações de um contexto, pausá-lo, aposentá-lo ou copiá-lo. Essas operações de ciclo de vida preservam o histórico para você nunca perder uma trilha de auditoria. ### Como 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/products/matcher/update-context) ### Como pausar um contexto Para manter um contexto temporariamente fora das execuções de conciliação, atualize o status dele 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 os dados históricos * Permite reativação futura ao voltar o status para `ACTIVE`

Como arquivar um contexto

Arquivar é uma exclusão suave reversível. Em vez de remover um contexto de forma permanente, leva o contexto para o status `ARCHIVED`, preservando todo o histórico dele (fontes, regras, execuções de correspondência e registros de auditoria) e tirando-o da listagem padrão de contextos. ```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 * Tira o contexto da listagem padrão * É reversível a qualquer momento com o endpoint [restore](#restore-a-context) Referência da API: [Arquivar contexto](/pt/reference/products/matcher/archive-context)

Como restaurar um contexto

Restaurar reverte um arquivamento. Leva o contexto de `ARCHIVED` de volta para `DRAFT`, para você revisar e reconfigurar o contexto antes de reativá-lo. ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/restore" \ -H "Authorization: Bearer $TOKEN" ``` Restaurar um contexto: * Devolve o status do contexto de `ARCHIVED` para `DRAFT` * **Não** retoma a correspondência automaticamente. Revise e reative o contexto para rodar a conciliação de novo * Retorna `409 Conflict` se chamado em um contexto que não está arquivado Referência da API: [Restaurar contexto](/pt/reference/products/matcher/restore-context) ### Como clonar um contexto Para duplicar um contexto existente com as fontes, regras, regras de tarifa e mapas de campo dele, use o endpoint de clone. Use-o para criar templates ou replicar configurações entre ambientes. As regras de tarifa clonadas continuam referenciando as mesmas tabelas de tarifas do contexto de origem. O Matcher não copia as próprias tabelas de tarifas. ```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 }' ``` A resposta informa quantas fontes, regras, regras de tarifa e mapas de campo o Matcher copiou. Um clone bem-sucedido retorna em status `ACTIVE`. Referência da API: [Clonar contexto](/pt/reference/products/matcher/clone-context) ## Ciclo de vida do contexto *** Um contexto de conciliação segue um ciclo de vida que controla quando a correspondência pode rodar e como os dados são preservados. * Um contexto começa em **Rascunho**, onde você configura fontes e ajustes. * Um contexto permanece em **Rascunho** até uma atualização explícita defini-lo como `ACTIVE`. A ativação valida as fontes obrigatórias nos lados `LEFT` e `RIGHT`, os mapeamentos de campo ou as opções CAMT, as regras de correspondência e as regras de tarifa quando você habilita a normalização de tarifa. * Um contexto ativo pode ser temporariamente **Pausado** para parar a execução sem afetar a configuração ou os dados históricos. * Quando você não precisar mais de um contexto, mova-o para **Arquivado** com o endpoint [archive](#archive-a-context). Arquivar é uma exclusão suave reversível: leva o contexto para `ARCHIVED`, preserva o histórico completo e os registros de auditoria e o tira da listagem padrão. Um contexto arquivado pode voltar para **Rascunho** a qualquer momento com o endpoint [restore](#restore-a-context). Ciclo de vida do contexto do Matcher ## Boas práticas *** Use nomes explícitos que reflitam contas, sistemas e finalidade. Prefira precisão a automação no começo. Ajuste os limiares conforme os resultados observados. Use vários contextos em vez de uma única conciliação ampla. Sempre marque as fontes com requisitos de conformidade. Garanta que os fusos horários das fontes reflitam o feed de dados original. Defina explicitamente a semântica de débito e crédito de cada fonte. ## Próximos passos *** Defina como os campos da fonte mapeiam para o schema do Matcher. Configure as regras que guiam a conciliação.