Início rápido da API do Matcher

Este guia é para desenvolvedores. Se você busca uma visão geral de negócio sobre o que o Matcher faz, veja O que é o Matcher?.

Este guia leva você da criação do seu primeiro contexto de conciliação até a revisão das transações correspondentes.

Antes de começar

Você precisa de:

Uma instância do Matcher em execução
Um token JWT válido para autenticação
Dois arquivos de transação 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.

Etapa 1: Crie um contexto de conciliação

Um contexto define o escopo da sua conciliação: o que você compara e como.

Referência da API: Create context

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 o Matcher pareia as transações:

Tipo	Descrição
`1:1`	Cada transação corresponde a exatamente uma contraparte
`1:N`	Uma transação pode corresponder a várias contrapartes
`N:M`	Várias transações podem corresponder entre os dois lados

Salve o id da resposta. Você vai usá-lo em todas as etapas 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 começa no status DRAFT. Ele passa para ACTIVE quando você estiver pronto para rodar a conciliação.

Etapa 2: Adicione fontes de dados

Para rodar uma correspondência, configure pelo menos duas fontes: os sistemas cujas transações você quer comparar.

Referência da API: Create source

Crie uma fonte de banco

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

Crie uma 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 dois valores de id das fontes.

Tipos de fonte

Tipo	Caso de uso
`BANK`	Extratos bancários
`LEDGER`	Ledger geral / exportações de ERP
`GATEWAY`	Dados de processadora de pagamento
`CUSTOM`	Qualquer outra fonte de dados
`FETCHER`	Dados extraídos pelo mecanismo de extração embutido

Etapa 3: Mapeie os campos de fonte

Seus arquivos de fonte provavelmente usam nomes de coluna diferentes dos que o Matcher espera. Os mapas de campo os traduzem para o schema padrão do Matcher.

Referência da API: Create field map

Mapeie a fonte de banco

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

Mapeie 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 depois do mapeamento:

Campo	Tipo	Descrição
`transaction_id`	String	Identificador exclusivo dentro da fonte
`amount`	Decimal	Valor da transação
`currency`	String	Código de moeda ISO 4217 (por exemplo, USD)
`date`	Date	Data da transação (YYYY-MM-DD)

Opcional, mas recomendado: reference (referência externa ou descrição).

Etapa 4: Crie regras de correspondência

As regras definem como o Matcher compara transações. Comece com uma regra exact, que é a mais precisa.

Referência da API: Create match rule

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

Adicione uma regra tolerance como fallback

Capture pequenas diferenças, como tarifas 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 as regras por prioridade (o número mais baixo primeiro). A regra exact roda primeiro. Apenas as transações não conciliadas passam para a regra tolerance.

Tipos de regra

Tipo	Quando usar	Faixa de prioridade
`EXACT`	Os valores devem corresponder exatamente	1-1000; exclusiva dentro do contexto
`TOLERANCE`	Pequenas diferenças esperadas	1-1000; exclusiva dentro do contexto
`DATE_LAG`	Atrasos de data entre sistemas	1-1000; exclusiva dentro do contexto
`FUZZY`	Referências com pontuação de similaridade; sempre propostas para revisão	1-1000; exclusiva dentro do contexto

Etapa 5: Ative o contexto

Mova o contexto de DRAFT para ACTIVE:

Referência da API: Update context

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "status": "ACTIVE"
 }'

Etapa 6: Envie os arquivos de transação

Envie um arquivo por fonte. O Matcher aceita os formatos CSV, JSON e XML por upload multipart form.

Referência da API: Upload transaction file
List ingestion jobs

Envie as transações do banco

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"

Envie as 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 os dois jobs atingirem o status COMPLETED antes de rodar a correspondência.

Etapa 7: Rode a correspondência

Comece com uma execução dry run para pré-visualizar os resultados sem persistir:

Referência da API: Run 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"
 }'

As duas respostas incluem um runId. Salve-o para a Etapa 8. Revise os resultados do dry run. Quando estiver satisfeito, rode com COMMIT para persistir as correspondências:

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

Etapa 8: Revise os resultados

Referência da API: List match run groups
Unmatch group

Veja os grupos de correspondência

cURL

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

Cada grupo de correspondência contém transações pareadas e uma pontuação de confiança (0-100):

Pontuação	O que acontece
90-100	Confirmado automaticamente, nenhuma ação necessária
60-89	Precisa de revisão manual
Abaixo de 60	Nenhuma correspondência criada, torna-se uma exceção

Desfaça uma correspondência incorreta

Use o endpoint unmatch para rejeitar um grupo de correspondência PROPOSED e devolver suas transações ao pool de não conciliadas. Para um grupo CONFIRMED, o Matcher primeiro verifica se consegue reverter os efeitos residuais/de item em aberto dessa confirmação. Um unmatch bem-sucedido reverte esses efeitos de forma atômica, junto com a revogação do grupo e a devolução das suas transações:

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": "Transactions belong to different records"
 }'

Se a reversão do grupo confirmado remove a última contribuição ativa por trás de uma obrigação, o item em aberto se torna terminal WITHDRAWN: ele permanece como histórico, mas não é compensável nem é levado para outra execução. Se um lançamento ativo posterior ainda sustenta o residual, ou se uma nova obrigação ativa entraria em conflito com a restauração de um item terminal na mesma identidade, o Matcher retorna 409 Conflict antes de alterar o grupo, as transações ou os itens em aberto. Depois de um unmatch bem-sucedido, as transações voltam ao pool de não conciliadas para a próxima execução.

Etapa 9: Trate as exceções

Exceções são transações que o Matcher não conseguiu corresponder automaticamente. O Matcher classifica cada exceção por severidade:

Referência da API: List exceptions

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`	Todos os outros	7 dias

Liste as exceções

cURL

curl -X GET "https://api.matcher.example.com/v1/exceptions" \
 -H "Authorization: Bearer $TOKEN"

Resolva exceções aplicando correspondência forçada, criando ajustes ou despachando para sistemas externos configurados, como JIRA, ServiceNow ou um webhook HTTP.

Próximos passos

Contextos e fontes

Guia completo de configuração de contexto e fonte.

Regras de correspondência

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

Pontuação de confiança

Como o Matcher calcula as pontuações e o que elas significam.

Resolução de exceções

Trate transações não conciliadas.

​Antes de começar

​Etapa 1: Crie um contexto de conciliação

​Etapa 2: Adicione fontes de dados

​Crie uma fonte de banco

​Crie uma fonte de ledger

​Tipos de fonte

​Etapa 3: Mapeie os campos de fonte

​Mapeie a fonte de banco

​Mapeie a fonte de ledger

​Campos obrigatórios

​Etapa 4: Crie regras de correspondência

​Crie uma regra exact

​Adicione uma regra tolerance como fallback

​Tipos de regra

​Etapa 5: Ative o contexto

​Etapa 6: Envie os arquivos de transação

​Envie as transações do banco

​Envie as transações do ledger

​Etapa 7: Rode a correspondência

​Etapa 8: Revise os resultados

​Veja os grupos de correspondência

​Desfaça uma correspondência incorreta

​Etapa 9: Trate as exceções

​Liste as exceções

​Próximos passos

Contextos e fontes

Regras de correspondência

Pontuação de confiança

Resolução de exceções

Antes de começar

Etapa 1: Crie um contexto de conciliação

Etapa 2: Adicione fontes de dados

Crie uma fonte de banco

Crie uma fonte de ledger

Tipos de fonte

Etapa 3: Mapeie os campos de fonte

Mapeie a fonte de banco

Mapeie a fonte de ledger

Campos obrigatórios

Etapa 4: Crie regras de correspondência

Crie uma regra exact

Adicione uma regra tolerance como fallback

Tipos de regra

Etapa 5: Ative o contexto

Etapa 6: Envie os arquivos de transação

Envie as transações do banco

Envie as transações do ledger

Etapa 7: Rode a correspondência

Etapa 8: Revise os resultados

Veja os grupos de correspondência

Desfaça uma correspondência incorreta

Etapa 9: Trate as exceções

Liste as exceções

Próximos passos