Início rápido da API do Matcher

Este guia é destinado a desenvolvedores. Se você está procurando uma visão geral de nível de negócio sobre o que o Matcher faz e como ele ajuda sua equipe, veja O que é o Matcher?.

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

Tipo	Descrição
`1:1`	Cada transação corresponde a exatamente uma contrapartida
`1:N`	Uma transação pode corresponder a múltiplas contrapartidas
`N:M`	Mú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/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/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

Tipo	Caso de uso
`BANK`	Extratos bancários
`LEDGER`	Livro razão / exportações de ERP
`GATEWAY`	Dados de processadores de pagamento
`CUSTOM`	Qualquer 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/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/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:

Campo	Tipo	Descrição
`transaction_id`	String	Identificador único dentro da fonte
`amount`	Decimal	Valor da transação
`currency`	String	Código ISO 4217 (ex.: BRL, USD)
`date`	Date	Data 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/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/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 20,
   "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

Tipo	Quando usar	Faixa de prioridade
`EXACT`	Valores devem coincidir exatamente	1-10
`TOLERANCE`	Pequenas diferenças esperadas	11-50
`DATE_LAG`	Atrasos de data entre sistemas	51-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/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.

Referência da API: Upload de arquivo de transações
Listar jobs de ingestão

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

Referência da API: Listar grupos de match
Desfazer match

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ção	O que acontece
90-100	Auto-confirmado, nenhuma ação necessária
60-89	Necessita revisão manual
Abaixo de 60	Nenhum 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

Severidade	Critério	SLA
`CRITICAL`	Valor >= 100.000 ou idade >= 120h	24 horas
`HIGH`	Valor >= 10.000 ou idade >= 72h	72 horas
`MEDIUM`	Valor >= 1.000 ou idade >= 24h	5 dias
`LOW`	Todas as outras	7 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.

Listar contextos de conciliação

⌘I

​Antes de começar

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

​Passo 2: Adicionar fontes de dados

​Criar fonte bancária

​Criar fonte de ledger

​Tipos de fonte

​Passo 3: Mapear campos das fontes

​Mapear a fonte bancária

​Mapear a fonte de ledger

​Campos obrigatórios

​Passo 4: Criar regras de match

​Criar regra exact

​Adicionar regra tolerance como fallback

​Tipos de regra

​Passo 5: Ativar o contexto

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

​Upload de transações bancárias

​Upload de transações do ledger

​Passo 7: Executar o matching

​Passo 8: Revisar resultados

​Visualizar grupos de match

​Desfazer um match incorreto

​Passo 9: Tratar exceções

​Listar exceções

​Próximos passos

Contextos e fontes

Regras de match

Score de confiança

Resolvendo exceções

Antes de começar

Passo 1: Criar um contexto de conciliação

Passo 2: Adicionar fontes de dados

Criar fonte bancária

Criar fonte de ledger

Tipos de fonte

Passo 3: Mapear campos das fontes

Mapear a fonte bancária

Mapear a fonte de ledger

Campos obrigatórios

Passo 4: Criar regras de match

Criar regra exact

Adicionar regra tolerance como fallback

Tipos de regra

Passo 5: Ativar o contexto

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

Upload de transações bancárias

Upload de transações do ledger

Passo 7: Executar o matching

Passo 8: Revisar resultados

Visualizar grupos de match

Desfazer um match incorreto

Passo 9: Tratar exceções

Listar exceções

Próximos passos