Pular para o conteúdo principal
Coloque o Matcher em funcionamento em minutos. Este guia percorre o caminho completo, desde a criação do primeiro contexto de conciliação até a revisão de transações correspondidas.

​
Antes de começar

Você vai precisar de:
  • Uma instância do Matcher em execução
  • Um token JWT válido para autenticação
  • Dois arquivos de transações para conciliar (CSV, JSON ou XML)
Todos os exemplos usam cURL. Substitua $TOKEN pelo seu token JWT e https://api.matcher.example.com pela URL do seu Matcher.

​
Passo 1: Criar um contexto de conciliação

Um contexto define o escopo da sua conciliação: o que você está comparando e como.
Referência da API: Criar contexto
cURL
curl -X POST "https://api.matcher.example.com/v1/config/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Daily Bank Reconciliation",
   "type": "1:1",
   "interval": "daily"
 }'
O campo type define como as transações são pareadas:
TipoDescrição
1:1Cada transação corresponde a exatamente uma contrapartida
1:NUma transação pode corresponder a múltiplas contrapartidas
N:MMúltiplas transações podem corresponder entre os dois lados
Salve o id da resposta. Você vai usá-lo em todos os passos seguintes. 
{
  "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Bank Reconciliation",
  "type": "1:1",
  "interval": "daily",
  "status": "DRAFT",
  "createdAt": "2026-03-04T12:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}
O contexto inicia com status DRAFT. Ele muda para ACTIVE quando você estiver pronto para executar a conciliação.

​
Passo 2: Adicionar fontes de dados

Todo contexto precisa de pelo menos duas fontes: os sistemas cujas transações você quer comparar.
Referência da API: Criar fonte

​
Criar 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": "Chase Bank - Account 1234",
   "type": "BANK"
 }'

​
Criar 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": "General Ledger - GL 1000",
   "type": "LEDGER"
 }'
Salve os valores de id de ambas as fontes.

​
Tipos de fonte

TipoCaso de uso
BANKExtratos bancários
LEDGERLivro razão / exportações de ERP
GATEWAYDados de processadores de pagamento
CUSTOMQualquer outra fonte de dados

​
Passo 3: Mapear campos das fontes

Seus arquivos de origem provavelmente usam nomes de coluna diferentes dos que o Matcher espera. Mapas de campos traduzem esses nomes para o schema padrão do Matcher.
Referência da API: Criar mapa de campos

​
Mapear a fonte bancária

cURL
curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/sources/{bankSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "Transaction ID": "transaction_id",
     "Amount": "amount",
     "Currency": "currency",
     "Post Date": "date",
     "Description": "reference"
   }
 }'

​
Mapear a fonte de ledger

cURL
curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/sources/{ledgerSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "entry_id": "transaction_id",
     "debit_credit_amount": "amount",
     "currency_code": "currency",
     "posting_date": "date",
     "memo": "reference"
   }
 }'

​
Campos obrigatórios

Toda transação deve ter estes campos após o mapeamento:
CampoTipoDescrição
transaction_idStringIdentificador único dentro da fonte
amountDecimalValor da transação
currencyStringCódigo ISO 4217 (ex.: BRL, USD)
dateDateData da transação (YYYY-MM-DD)
Opcional, mas recomendado: reference (referência externa ou descrição).

​
Passo 4: Criar regras de match

Regras definem como o Matcher compara transações. Comece com uma regra exact, que é a mais precisa.
Referência da API: Criar regra de match

​
Criar regra exact

cURL
curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "matchReference": true,
     "caseInsensitive": true,
     "datePrecision": "DAY"
   }
 }'

​
Adicionar regra tolerance como fallback

Captura pequenas diferenças como taxas bancárias ou arredondamento:
cURL
curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 10,
   "config": {
     "percentTolerance": 0.01,
     "absTolerance": 5.0,
     "dateWindowDays": 2,
     "matchCurrency": true,
     "matchReference": true,
     "caseInsensitive": true
   }
 }'
O Matcher avalia regras por prioridade (menor número primeiro). A regra exact roda primeiro. Apenas transações sem match caem para a regra tolerance.

​
Tipos de regra

TipoQuando usarFaixa de prioridade
EXACTValores devem coincidir exatamente1-10
TOLERANCEPequenas diferenças esperadas11-50
DATE_LAGAtrasos de data entre sistemas51-100

​
Passo 5: Ativar o contexto

Mova o contexto de DRAFT para ACTIVE:
Referência da API: Atualizar contexto
cURL
curl -X PATCH "https://api.matcher.example.com/v1/config/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "status": "ACTIVE"
 }'

​
Passo 6: Fazer upload dos arquivos de transações

Faça upload de um arquivo por fonte. O Matcher aceita formatos CSV, JSON e XML via upload multipart.

​
Upload de transações bancárias

cURL
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@bank_transactions.csv" \
 -F "format=csv"

​
Upload de transações do ledger

cURL
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@ledger_entries.csv" \
 -F "format=csv"
Cada upload cria um job de ingestão. Verifique o status do job:
cURL
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs" \
 -H "Authorization: Bearer $TOKEN"
Aguarde ambos os jobs alcançarem o status COMPLETED antes de executar o matching.

​
Passo 7: Executar o matching

Comece com um dry run para visualizar resultados sem persistir:
Referência da API: Executar match
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": "DRY_RUN"
 }'
Ambas as respostas incluem um runId. Salve-o para o Passo 8. Revise os resultados do dry run. Quando estiver satisfeito, execute com COMMIT para persistir os matches:
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"
 }'

​
Passo 8: Revisar resultados

​
Visualizar grupos de match

cURL
curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN"
Cada grupo de match contém transações pareadas e uma pontuação de confiança (0-100):
PontuaçãoO que acontece
90-100Auto-confirmado, nenhuma ação necessária
60-89Necessita revisão manual
Abaixo de 60Nenhum match criado, torna-se exceção

​
Desfazer um match incorreto

Use o endpoint de unmatch para rejeitar um grupo de match e devolver as transações ao pool de não correspondidas:
cURL
curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "Transações pertencem a registros diferentes"
 }'
As transações retornam ao pool de não correspondidas para a próxima execução.

​
Passo 9: Tratar exceções

Exceções são transações que não puderam ser correspondidas automaticamente. O Matcher classifica cada exceção por severidade:
Referência da API: Listar exceções
SeveridadeCritérioSLA
CRITICALValor >= 100.000 ou idade >= 120h24 horas
HIGHValor >= 10.000 ou idade >= 72h72 horas
MEDIUMValor >= 1.000 ou idade >= 24h5 dias
LOWTodas as outras7 dias

​
Listar exceções

cURL
curl -X GET "https://api.matcher.example.com/v1/exceptions" \
 -H "Authorization: Bearer $TOKEN"
Resolva exceções forçando um match, criando ajustes ou despachando para sistemas externos como JIRA.

​
Próximos passos

Contextos e fontes

Guia completo de configuração de contextos e fontes.

Regras de match

Todos os tipos de regra e opções de configuração em detalhe.

Score de confiança

Como as pontuações são calculadas e o que significam.

Resolvendo exceções

Trate transações não correspondidas.