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

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

name

string

Nome descritivo para o contexto

type

string

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

interval

string

Frequência de conciliação (ex: daily, weekly)

feeToleranceAbs

decimal

padrão:"0"

Tolerância absoluta de taxa para comparação de valores

feeTolerancePct

decimal

padrão:"0"

Tolerância percentual de taxa para comparação de valores

feeNormalization

string

padrão:"NET"

Modo de normalização de taxa: NET ou GROSS

autoMatchOnUpload

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

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.

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, side e config são todos obrigatórios (name tem de 1 a 50 caracteres; config pode ser {}).

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

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

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

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": "@every 1h",
   "enabled": true
 }'

Campos

kind

string

obrigatório

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

connectionId

string (UUID)

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

format

string

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

scheduleSpec

string

Agendamento de intervalo que o agendador de bindings lê (cron ou duração @every).

enabled

boolean

Se o binding é executado imediatamente. O padrão é true.

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

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

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.

​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