Contextos e fontes

Contextos e fontes definem como a conciliação é estruturada no Matcher. Um contexto estabelece o escopo da conciliação, enquanto fontes representam os sistemas que fornecem dados transacionais.

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 matching 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
Matching 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

Criação básica de contexto

Request

cURL

curl -X POST "https://api.matcher.example.com/v1/config/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Conciliação Bancária Diária",
   "interval": "daily",
   "type": "1:1"
 }'

Response

{
  "id":"969a11cd-6b7d-4e71-b82b-0828e0603149",
  "tenantId":"11111111-1111-1111-1111-111111111111",
  "name":"Conciliação Bancária Diária",
  "type":"1:1",
  "interval":"daily",
  "status":"ACTIVE",
  "feeToleranceAbs":"0",
  "feeTolerancePct":"0",
  "createdAt":"2026-02-02T16:31:22Z",
  "updatedAt":"2026-02-02T16:31:22Z"
}

Referência da API: Criar contexto

Executando conciliação

O Matcher processa transações através de execuções de match. Você pode disparar o matching manualmente ou visualizar o histórico de execuções anteriores.

Execuções manuais de match

Dispare uma execução de match 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"
 }'

Response

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING"
}

Referência da API: Executar match

Defina mode: "DRY_RUN" para visualizar os resultados sem confirmar os matches.

Modos de execução de match

Modo	Descrição
`DRY_RUN`	Visualiza matches sem persistir resultados
`COMMIT`	Executa matching e persiste resultados

Visualizando histórico de execuções

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/runs" \
 -H "Authorization: Bearer $TOKEN"

Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
      "mode": "COMMIT",
      "status": "COMPLETED",
      "startedAt": "2026-01-20T06:00:00Z",
      "completedAt": "2026-01-20T06:05:23Z",
      "createdAt": "2026-01-20T06:00:00Z"
    }
  ],
  "limit": 20,
  "hasMore": false
}

Referência da API: Listar execuções de match

Status das execuções de match

Status	Descrição
`PENDING`	Execução está na fila
`PROCESSING`	Execução em progresso
`COMPLETED`	Execução finalizada com sucesso
`FAILED`	Execução encontrou um erro

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

Criar uma fonte bancária

cURL

curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Banco Chase - Conta 1234",
   "type": "BANK"
 }'

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "name": "Banco Chase - Conta 1234",
  "type": "BANK",
  "config": {},
  "createdAt": "2026-02-02T16:35:00Z",
  "updatedAt": "2026-02-02T16:35:00Z"
}

Referência da API: Criar fonte

Criar uma fonte de ledger

cURL

curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Ledger Principal - GL 1000",
   "type": "LEDGER"
 }'

Tipos de fonte

Tipo	Descrição	Uso típico
`LEDGER`	Contas do razão geral	Sistemas contábeis internos
`BANK`	Extratos bancários	Feeds de bancos externos
`GATEWAY`	Transações de processadores de pagamento	Gateways de pagamento
`CUSTOM`	Integrações customizadas	Qualquer outra fonte de dados

Configuração da fonte

Fontes aceitam um objeto config opcional para metadados adicionais:

cURL

curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Gateway de Pagamento",
   "type": "GATEWAY",
   "config": {
     "currency": "USD",
     "provider": "stripe"
   }
 }'

O objeto config é flexível e pode armazenar quaisquer pares chave-valor relevantes para sua integração.

Gerenciando contextos

Atualizar um contexto

cURL

curl -X PUT "https://api.matcher.example.com/v1/config/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Conciliação Bancária Diária - Atualizada",
   "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 PUT "https://api.matcher.example.com/v1/config/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "status": "PAUSED"
 }'

Pausar um contexto:

Impede novas execuções de match
Preserva dados históricos
Permite reativação futura definindo o status de volta para ACTIVE

Excluir um contexto

cURL

curl -X DELETE "https://api.matcher.example.com/v1/config/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN"

Referência da API: Excluir contexto

Ciclo de vida do contexto

Um contexto de conciliação segue um ciclo de vida bem definido que controla quando o matching pode ser executado 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 a conciliação para um período está completa, o contexto é Closed, preservando todos os resultados e registros de auditoria para referência futura.

Este ciclo de vida garante o controle operacional, a execução previsível e a rastreabilidade completa ao longo dos períodos de reconciliaçã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 match

Configure as regras que orientam a conciliação.

Introduction

Primeiros passos

Configurações

Reconciliação diária

Integrações

Referência

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

Criação básica de contexto

Request

Response

Executando conciliação

Execuções manuais de match

Response

Modos de execução de match

Visualizando histórico de execuções

Response

Status das execuções de match

O que é uma fonte?

Adicionando fontes a um contexto

Criar uma fonte bancária

Response

Criar uma fonte de ledger

Tipos de fonte

Configuração da fonte

Gerenciando contextos

Atualizar um contexto

Pausar um contexto

Excluir um contexto

Ciclo de vida do contexto

Boas práticas

Próximos passos

Mapeamento de campos

Regras de match

Introduction

Primeiros passos

Configurações

Reconciliação diária

Integrações

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

​Criação básica de contexto

​Request

​Response

​Executando conciliação

​Execuções manuais de match

​Response

​Modos de execução de match

​Visualizando histórico de execuções

​Response

​Status das execuções de match

​O que é uma fonte?

​Adicionando fontes a um contexto

​Criar uma fonte bancária

​Response

​Criar uma fonte de ledger

​Tipos de fonte

​Configuração da fonte

​Gerenciando contextos

​Atualizar um contexto

​Pausar um contexto

​Excluir um contexto

​Ciclo de vida do contexto

​Boas práticas

​Próximos passos

Mapeamento de campos

Regras de match

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

Criação básica de contexto

Request

Response

Executando conciliação

Execuções manuais de match

Response

Modos de execução de match

Visualizando histórico de execuções

Response

Status das execuções de match

O que é uma fonte?

Adicionando fontes a um contexto

Criar uma fonte bancária

Response

Criar uma fonte de ledger

Tipos de fonte

Configuração da fonte

Gerenciando contextos

Atualizar um contexto

Pausar um contexto

Excluir um contexto

Ciclo de vida do contexto

Boas práticas

Próximos passos