> ## 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 e quais regras se aplicam. * 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 **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](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-schedules.md) separado. #### 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 **name** `string` Nome descritivo do contexto **type** `string` Cardinalidade de correspondência: `1:1`, `1:N` ou `N:M` **interval** `string` Rótulo de execução obrigatório (por exemplo `daily`, `weekly`). Ele não agenda execuções. **feeToleranceAbs** `string` (default: 0) Tolerância absoluta quando o Matcher compara uma tarifa real com a tarifa esperada, como string decimal (por exemplo `"0.01"`) **feeTolerancePct** `string` (default: 0) Tolerância relativa para a mesma comparação de tarifa, em percentual, como string decimal (`"0.5"` tolera 0,5%, não 50%) **feeNormalization** `string` Modo opcional de normalização de tarifa: `NET` ou `GROSS`. Omita o campo para deixar a normalização de tarifa desabilitada. **autoMatchOnUpload** `boolean` (default: false) Dispara automaticamente uma execução de correspondência depois do upload de um arquivo **signConvention** `string` (default: SAME) Como os dados do contexto carregam o sinal: `SAME` ou `OPPOSITE`. Com `SAME`, um pagamento carrega o mesmo sinal do que ele liquida, e um valor negativo é um estorno. Com `OPPOSITE`, um pagamento carrega o sinal oposto ao da fatura que ele liquida. Depois que o contexto carrega um saldo parcial, o Matcher recusa a alteração com `409`. Ele também recusa a alteração enquanto uma execução de correspondência está em andamento. **agedBreakThresholdDays** `integer` Limite opcional de envelhecimento dos itens em aberto, em dias (1 ou mais). Em uma execução `COMMIT`, um saldo de item em aberto mais antigo que esse limite gera uma exceção `AGED_BREAK`. Omita o campo para desabilitar o envelhecimento. Na atualização, `0` o desabilita. **agedBreakCalendar** `string` Calendário opcional de dias úteis para `agedBreakThresholdDays`: `US_FED` ou `BR_ANBIMA`. Omita o campo para contar dias corridos. #### 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, "signConvention":"SAME", "createdAt":"2026-02-02T16:31:22Z", "updatedAt":"2026-02-02T16:31:22Z" } ``` > [!TIP] > > Referência da API: [Criar contexto](https://docs.lerian.studio/pt/reference/products/matcher/create-context.md) ## 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 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](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-schedules.md) 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. Quando a submissão assíncrona não está disponível, o Matcher rejeita `"async": true` com HTTP 503. > [!NOTE] > > Os dois modos retornam **HTTP 202 Accepted** quando dão certo, então leia o `status` da resposta para distingui-los. > > Uma execução síncrona retorna `COMPLETED`. Quando ela falha, a requisição retorna uma resposta de problema. 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`. > [!TIP] > > Referência da API: > > * [Rodar correspondência](https://docs.lerian.studio/pt/reference/products/matcher/run-match.md) > * [Listar execuções de correspondência](https://docs.lerian.studio/pt/reference/products/matcher/list-match-runs.md) ## 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`. O objeto `config` também guarda ajustes de importação, como a [detecção de duplicatas](https://docs.lerian.studio/pt/products/matcher/daily-reconciliation/matcher-uploading-files.md): ```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, 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" }' ``` > [!NOTE] > > `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. > [!TIP] > > Referência da API: [Criar fonte](https://docs.lerian.studio/pt/reference/products/matcher/create-source.md) ### 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 | Linhas que o motor de extração puxa de uma conexão de Discovery | ### Fontes de descoberta `FETCHER` identifica um tipo de fonte. O `config` dela deve trazer `connection_id`, o id de uma conexão de [Discovery](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-discovery.md), e cada conexão alimenta uma fonte `FETCHER`. As linhas que o motor de extração puxa dessa conexão chegam a essa fonte. Para puxar de forma agendada, adicione um [binding de fonte](#source-bindings) no trilho de consulta com o mesmo `connectionId`. ```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": { "connection_id": "8f14e45f-ceea-4f6a-9d1b-2b6f3c7a9e10" } }' ``` ## 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 da listagem padrão 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. Adicione `includeArchived=true` para incluir as fontes arquivadas. | | 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 da listagem padrão; os bindings continuam habilitados até serem alterados separadamente. | | Restaurar fonte | `POST /v1/contexts/{contextId}/sources/{sourceId}/restore` | Reativa uma fonte arquivada antes. | > [!TIP] > > Referência da API: > > * [Criar fonte](https://docs.lerian.studio/pt/reference/products/matcher/create-source.md) > * [Obter fonte](https://docs.lerian.studio/pt/reference/products/matcher/retrieve-source.md) > * [Atualizar fonte](https://docs.lerian.studio/pt/reference/products/matcher/update-source.md) > * [Arquivar fonte](https://docs.lerian.studio/pt/reference/products/matcher/archive-source.md) > * [Restaurar fonte](https://docs.lerian.studio/pt/reference/products/matcher/restore-source.md) ## 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`). As linhas chegam à fonte `FETCHER` cujo `config.connection_id` corresponde, qualquer que seja a fonte e o `format` que o binding nomeia. Veja [Discovery](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-discovery.md). Os bindings ficam em `/v1/contexts/{contextId}/sources/{sourceId}/bindings`. > [!NOTE] > > Os pulls agendados rodam quando a Lerian habilita o scheduler de bindings. Um binding é despachado apenas quando está habilitado e 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/febraban-base", "scheduleSpec": "1h", "enabled": true }' ``` #### Campos **kind** `string` *required* Trilho em que o scheduler puxa a fonte: `file` ou `query` (obrigatório). **connectionId** `string (UUID)` Conexão do motor de descoberta no trilho de consulta. Obrigatória para `query`, rejeitada para `file`. **format** `string` *required* Formato declarado que o binding produz (chave de descritor com namespace de região/família, por exemplo `br/cnab400/febraban-base`). **scheduleSpec** `string` *required* Duração positiva do Go que o scheduler de bindings lê, como `1h`, `30m` ou `@every 1h`. O Matcher recusa a sintaxe cron e valores zero ou negativos com `400`. **enabled** `boolean` Se o scheduler pode despachar o binding quando ele vence. O padrão é `true`. Habilitá-lo não o executa imediatamente. > [!TIP] > > Referência da API: > > * [Criar binding de fonte](https://docs.lerian.studio/pt/reference/products/matcher/create-source-binding.md) > * [Listar bindings de fonte](https://docs.lerian.studio/pt/reference/products/matcher/list-source-bindings.md) > * [Obter binding de fonte](https://docs.lerian.studio/pt/reference/products/matcher/get-source-binding.md) > * [Atualizar binding de fonte](https://docs.lerian.studio/pt/reference/products/matcher/update-source-binding.md) > * [Excluir binding de fonte](https://docs.lerian.studio/pt/reference/products/matcher/delete-source-binding.md) ## 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" }' ``` > [!TIP] > > Referência da API: [Atualizar contexto](https://docs.lerian.studio/pt/reference/products/matcher/update-context.md) ### 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) > [!TIP] > > Referência da API: [Arquivar contexto](https://docs.lerian.studio/pt/reference/products/matcher/archive-context.md) ### 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 > [!TIP] > > Referência da API: [Restaurar contexto](https://docs.lerian.studio/pt/reference/products/matcher/restore-context.md) ### 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. 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`. > [!TIP] > > Referência da API: [Clonar contexto](https://docs.lerian.studio/pt/reference/products/matcher/clone-context.md) ## 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](https://mintcdn.com/lerian-49cb71fc/acz_224gNiM7aYvL/images/pt/d2/matcher-context-lifecycle.svg?fit=max\&auto=format\&n=acz_224gNiM7aYvL\&q=85\&s=f98909408c7f36ac852f431cfd7290eb) Ciclo de vida de um contexto do Matcher ## Boas práticas *** > [accordion] Use nomes descritivos > > Use nomes explícitos que reflitam contas, sistemas e finalidade. > [accordion] Comece com limiares conservadores > > Prefira precisão a automação no começo. Ajuste os limiares conforme os resultados observados. > [accordion] Separe as responsabilidades > > Use vários contextos em vez de uma única conciliação ampla. ## Próximos passos *** > [card] [Mapeamento de campos](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-field-mapping.md) > > Defina como os campos da fonte mapeiam para o schema do Matcher. > [card] [Regras de correspondência](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-match-rules.md) > > Configure as regras que guiam a conciliação. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.