Contextos e fontes

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 separado. Um novo contexto começa em DRAFT e permanece assim até você ativá-lo explicitamente.

Requisição

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 do contexto

string

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

string

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

string

padrão:"0"

Tolerância absoluta de tarifa para comparação de valor, como string decimal (por exemplo "0.01")

string

padrão:"0"

Tolerância percentual de tarifa para comparação de valor, como string decimal ("0.5" significa 0,5%)

string

Modo opcional de normalização de tarifa: NET ou GROSS. Omita o campo para deixar a normalização de tarifa desabilitada.

boolean

padrão:"false"

Dispara automaticamente uma execução de correspondência depois do upload de um arquivo

Resposta

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

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 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:

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 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:

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:

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 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:

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 como padrão quando omitido.

Referência da API: Criar fonte

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 no trilho de consulta (connectionId). Veja Discovery para saber como configurar conexões.

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"
   }
 }'

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:

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.

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

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 em que o scheduler puxa a fonte: file ou query (obrigatório).

string (UUID)

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

string

Formato declarado que o binding produz (chave de descritor com namespace de região/família, por exemplo br/cnab400/default).

string

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.

boolean

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:

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

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

Como pausar um contexto

Para manter um contexto temporariamente fora das execuções de conciliação, atualize o status dele 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 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.

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
Tira o contexto da listagem padrão
É reversível a qualquer momento com o endpoint restore

Referência da API: Arquivar contexto

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.

cURL

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

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.

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 tarifa e mapas de campo o Matcher copiou. Um clone bem-sucedido retorna em status ACTIVE.

Referência da API: Clonar contexto

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

Ciclo de vida do contexto do Matcher — Ciclo de vida de um contexto do Matcher

Boas práticas

Use nomes descritivos

Use nomes explícitos que reflitam contas, sistemas e finalidade.

Comece com limiares conservadores

Prefira precisão a automação no começo. Ajuste os limiares conforme os resultados observados.

Separe as responsabilidades

Use vários contextos em vez de uma única conciliação ampla.

Marque as fontes regulatórias

Sempre marque as fontes com requisitos de conformidade.

Alinhe os fusos horários

Garanta que os fusos horários das fontes reflitam o feed de dados original.

Documente as convenções de sinal

Defina explicitamente a semântica de débito e crédito de 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 guiam 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)

Como criar um contexto de conciliação

Requisição

Campos do contexto

Resposta

Como rodar a conciliação

O que é uma fonte?

Como adicionar fontes a um contexto

Tipos de fonte

Fontes de descoberta

Como gerenciar fontes

Bindings de fonte

Como criar um binding no trilho de consulta

Campos

Como gerenciar contextos

Como atualizar um contexto

Como pausar um contexto

Como arquivar um contexto

Como restaurar um contexto

Como 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)

​Como criar um contexto de conciliação

​Requisição

​Campos do contexto

​Resposta

​Como rodar a conciliação

​O que é uma fonte?

​Como adicionar fontes a um contexto

​Tipos de fonte

​Fontes de descoberta

​Como gerenciar fontes

​Bindings de fonte

​Como criar um binding no trilho de consulta

​Campos

​Como gerenciar contextos

​Como atualizar um contexto

​Como pausar um contexto

​Como arquivar um contexto

​Como restaurar um contexto

​Como 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)

Como criar um contexto de conciliação

Requisição

Campos do contexto

Resposta

Como rodar a conciliação

O que é uma fonte?

Como adicionar fontes a um contexto

Tipos de fonte

Fontes de descoberta

Como gerenciar fontes

Bindings de fonte

Como criar um binding no trilho de consulta

Campos

Como gerenciar contextos

Como atualizar um contexto

Como pausar um contexto

Como arquivar um contexto

Como restaurar um contexto

Como clonar um contexto

Ciclo de vida do contexto

Boas práticas

Próximos passos