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:

O endereço da API do Matcher que a Lerian fornece a você
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 pelo endereço da API do 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",
   "side": "RIGHT"
 }'

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",
   "side": "LEFT"
 }'

Salve os dois valores de id das fontes. Cada fonte precisa de um side (LEFT ou RIGHT): o contexto concilia as fontes LEFT com as fontes RIGHT.

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": {
     "external_id": "Transaction ID",
     "amount": "Amount",
     "currency": "Currency",
     "date": "Post Date",
     "description": "Description"
   }
 }'

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": {
     "external_id": "entry_id",
     "amount": "debit_credit_amount",
     "currency": "currency_code",
     "date": "posting_date",
     "description": "memo"
   }
 }'

Campos obrigatórios

Toda transação deve ter estes campos depois do mapeamento:

Campo	Tipo	Descrição
`external_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: description, fee_amount, fee_currency e direction. Cada chave do mapeamento é um campo do Matcher. Cada valor é o nome da coluna no seu arquivo, exceto para direction. O valor dela é um objeto {column, debit, credit} para um arquivo que marca cada linha como débito ou crédito em uma coluna separada. Uma linha de débito é importada com valor negativo, e uma de crédito com valor positivo.

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; sempre propostas para revisão	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"
 }'

Se o contexto não estiver pronto, o Matcher recusa a atualização com 409 Conflict e o código MTCH-0103. O array errors da resposta lista cada requisito ausente. O Progresso da configuração lista os requisitos ausentes e a próxima chamada a fazer.

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 "format=csv" \
 -F "file=@bank_transactions.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 "format=csv" \
 -F "file=@ledger_entries.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"
 }'

A resposta inclui um runId. Um dry run não salva grupos de correspondência. Para revisar os resultados, leia as estatísticas agregadas da execução com Get match 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"
 }'

Salve o runId da resposta do COMMIT. Você vai usá-lo na Etapa 8.

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 para correspondências EXACT e TOLERANCE. As correspondências FUZZY e DATE_LAG precisam de revisão manual
60-89	Precisa de revisão manual

Desfaça uma correspondência incorreta

Use o endpoint unmatch para rejeitar um grupo de correspondência PROPOSED ou revogar um CONFIRMED. O Matcher devolve as transações do grupo ao pool de não conciliadas para a próxima execução:

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

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
`CRITICAL`	Valor >= 100.000 ou idade >= 120h
`HIGH`	Valor >= 10.000 ou idade >= 72h
`MEDIUM`	Valor >= 1.000 ou idade >= 24h
`LOW`	Todos os outros

Liste as exceções

cURL

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

Resolva exceções diretamente, aplicando correspondência forçada ou criando lançamentos de ajuste.

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