Contextos e fontes

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ê declara principalmente a cardinalidade (type), um rótulo de execução obrigatório (interval) e qualquer tolerância de tarifa que a comparação deve permitir. O valor de interval não agenda execuções; a execução automática exige um agendamento de conciliação separado. Um novo contexto começa em DRAFT e permanece assim até que você o ative explicitamente.

Request

cURL

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

string

Nome descritivo para o contexto

string

Cardinalidade da correspondência: 1:1, 1:N ou N:M

string

Rótulo de execução obrigatório (ex.: daily, weekly). Ele não agenda execuções.

string

padrão:"0"

Tolerância absoluta de taxa para comparação de valores, como string decimal (ex. "0.01")

string

padrão:"0"

Tolerância percentual de taxa para comparação de valores, como string decimal ("0.5" significa 0.5%)

string

Modo opcional de normalização de tarifas: NET ou GROSS. Omita-o para manter a normalização de tarifas desabilitada.

boolean

padrão:"false"

Disparar automaticamente uma execução de correspondência quando um arquivo é carregado

Response

{
  "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

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 as dispare automaticamente. Toda execução funciona em um de dois modos:

Modo	O que faz
`DRY_RUN`	Não persiste resultados de correspondência, mutações de transações, artefatos de tarifas nem exceções, mas persiste um `MatchRun` concluído e suas estatísticas
`COMMIT`	Executa a correspondência e persiste os resultados

Dispare uma execução para um contexto:

cURL

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. O envio assíncrono exige que o worker de match runs esteja habilitado; caso contrário, o Matcher rejeita "async": true com HTTP 503.

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 | Listar execuções de correspondência

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:

cURL

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:

cURL

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 quando omitido.

Referência da API: Criar fonte

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`	Fonte do motor de descoberta	Conexões de agregador fornecidas por um binding de fonte

Fontes fetcher

FETCHER identifica um tipo de fonte; ele não habilita a extração automática por si só. Crie a fonte como qualquer outra e conecte a conexão com o agregador upstream por meio de um binding de fonte no trilho de consulta (connectionId) — veja Descoberta para saber como as conexões são configuradas.

cURL

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 é excluída da prontidão do contexto, da correspondência e das listagens de fontes, mas mantém todo o histórico até que você a restaure. O arquivamento não desabilita seus bindings; desabilite-os ou exclua-os separadamente para interromper os despachos do agendador.

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`	Exclui a fonte da prontidão, da correspondência e das listagens; os bindings permanecem habilitados até serem alterados separadamente.
Restaurar fonte	`POST /v1/contexts/{contextId}/sources/{sourceId}/restore`	Reativa uma fonte previamente arquivada.

Referência da API:

Bindings de fonte

Os bindings definem como o agendador de bindings pode extrair os dados de uma fonte sem o carregamento manual de arquivos. Um binding de fonte vincula uma fonte ao trilho que fornece suas transações, além de uma duração que determina quando ele está devido. 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).

Os bindings ficam em /v1/contexts/{contextId}/sources/{sourceId}/bindings.

Um binding só é despachado quando o agendador de bindings está habilitado (ele vem desabilitado por padrão), o binding está habilitado e está devido. 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 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

cURL

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

string

obrigatório

Trilho pelo qual a fonte é puxada: file ou query (obrigatório).

string (UUID)

Conexão do motor de descoberta no trilho de consulta. Obrigatório para query, rejeitado para file.

string

Formato declarado que o binding produz (chave descritora com namespace de região/família, ex: br/cnab400/default).

string

String de duração do Go lida pelo agendador de bindings, como 1h ou 30m. As sintaxes cron e @every são inválidas.

boolean

Indica se o agendador pode despachar o binding quando ele estiver devido. O padrão é true; habilitá-lo não o executa imediatamente.

Referência da API:

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

cURL

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

Pausar um contexto

Para temporariamente impedir que um contexto seja usado em execuções de conciliação, atualize seu status para PAUSED:

cURL

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.

cURL

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

Referência da API: Arquivar contexto

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.

cURL

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

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.

cURL

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 taxas e mapeamentos de campos foram copiados. Um clone bem-sucedido é retornado no status ACTIVE.

Referência da API: Clonar contexto

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.
Um contexto permanece em Draft até que uma atualização explícita defina seu status como ACTIVE. A ativação valida as fontes obrigatórias dos lados esquerdo e direito, os mapeamentos de campos ou as opções CAMT, as regras de correspondência e as regras de tarifas quando a normalização de tarifas está habilitada.
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 é 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.

Ciclo de Vida do Contexto do Matcher — Ciclo de vida de um 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 descritivos

Use nomes explícitos que reflitam contas, sistemas e propósito.

Comece com limites conservadores

Favoreça precisão sobre automação inicialmente. Ajuste os limites baseado nos resultados observados.

Separe preocupações

Use múltiplos contextos em vez de uma única conciliação ampla.

Sinalize fontes regulatórias

Sempre marque fontes com requisitos de compliance.

Alinhe fusos horários

Certifique-se de que os fusos horários das fontes reflitam o feed de dados original.

Documente convenções de sinal

Defina explicitamente a semântica de débito e crédito para cada fonte.

Próximos passos

Mapeamento de campos

Defina como os campos da fonte mapeiam para o schema do Matcher.

Regras de correspondência

Configure as regras que orientam a conciliação.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Contextos e fontes

O que é um contexto de conciliação?

Tipos de contexto

Um-para-um (1:1)

Um-para-muitos (1:n)

Muitos-para-muitos (n:m)

Criando um contexto de conciliação

Request

Campos do contexto

Response

Executando conciliação

O que é uma fonte?

Adicionando fontes a um contexto

Tipos de fonte

Fontes fetcher

Gerenciando fontes

Bindings de fonte

Criar um binding no trilho de consulta

Campos

Gerenciando contextos

Atualizar um contexto

Pausar um contexto

Arquivar um contexto

Restaurar um contexto

Clonar um contexto

Ciclo de vida do contexto

Boas práticas

Próximos passos

Mapeamento de campos

Regras de correspondência

​O que é um contexto de conciliação?

​Tipos de contexto

​Um-para-um (1:1)

​Um-para-muitos (1:n)

​Muitos-para-muitos (n:m)

​Criando um contexto de conciliação

​Request

​Campos do contexto

​Response

​Executando conciliação

​O que é uma fonte?

​Adicionando fontes a um contexto

​Tipos de fonte

​Fontes fetcher

​Gerenciando fontes

​Bindings de fonte

​Criar um binding no trilho de consulta

​Campos

​Gerenciando contextos

​Atualizar um contexto

​Pausar um contexto

​Arquivar um contexto

​Restaurar um contexto

​Clonar um contexto

​Ciclo de vida do contexto

​Boas práticas

​Próximos passos

Mapeamento de campos

Regras de correspondência

O que é um contexto de conciliação?

Tipos de contexto

Um-para-um (1:1)

Um-para-muitos (1:n)

Muitos-para-muitos (n:m)

Criando um contexto de conciliação

Request

Campos do contexto

Response

Executando conciliação

O que é uma fonte?

Adicionando fontes a um contexto

Tipos de fonte

Fontes fetcher

Gerenciando fontes

Bindings de fonte

Criar um binding no trilho de consulta

Campos

Gerenciando contextos

Atualizar um contexto

Pausar um contexto

Arquivar um contexto

Restaurar um contexto

Clonar um contexto

Ciclo de vida do contexto

Boas práticas

Próximos passos