Este guia apresenta um fluxo completo de conciliação usando o Matcher.
Você irá definir um contexto de conciliação, configurar fontes e regras, ingerir dados de transações, executar jobs de matching e revisar os resultados.
Pré-requisitos
Antes de começar, certifique-se de ter:
Acesso à API do Matcher com um token de autenticação válido
Arquivos de transações de exemplo (fornecidos abaixo)
Dados de exemplo
Este exemplo concilia um extrato bancário contra registros internos do ledger usando dois arquivos CSV.
Bank_statement.csv
transaction_id,amount,currency,date,reference
BANK-001,1000.00,USD,2024-01-15,Invoice payment
BANK-002,250.50,USD,2024-01-16,Subscription fee
BANK-003,500.00,USD,2024-01-17,Consulting services
BANK-004,75.00,USD,2024-01-18,Office supplies
Ledger_transactions.csv
transaction_id,amount,currency,date,reference
LED-001,1000.00,USD,2024-01-15,Invoice payment
LED-002,250.50,USD,2024-01-16,Monthly subscription
LED-003,500.00,USD,2024-01-17,Consulting services
LED-005,120.00,USD,2024-01-19,Travel expenses
- Três pares de transações são conciliados
- Uma transação bancária e uma transação do ledger permanecem não conciliadas
- Transações não conciliadas são criadas como exceções
Passo 1: criar um contexto de conciliação
Crie um contexto de conciliação para definir o escopo da conciliação.
Request
curl -X POST "https://api.matcher.example.com/v1/config/contexts" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Banco vs Ledger - Janeiro 2024",
"type": "1:1",
"interval": "daily"
}'
Response
{
"id": "969a11cd-6b7d-4e71-b82b-0828e0603149",
"tenantId": "11111111-1111-1111-1111-111111111111",
"name": "Banco vs Ledger - Janeiro 2024",
"type": "1:1",
"interval": "daily",
"status": "ACTIVE",
"feeToleranceAbs": "0",
"feeTolerancePct": "0",
"createdAt": "2024-01-20T10:00:00Z",
"updatedAt": "2024-01-20T10:00:00Z"
}
Guarde o ID do contexto. Ele é necessário nas etapas seguintes.
Passo 2: adicionar fontes de dados
Anexe as fontes de dados que serão conciliadas dentro deste contexto.
Fonte bancária
Request
curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/sources" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Extrato Banco Chase",
"type": "BANK"
}'
Response
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
"name": "Extrato Banco Chase",
"type": "BANK",
"config": {},
"createdAt": "2024-01-20T10:01:00Z",
"updatedAt": "2024-01-20T10:01:00Z"
}
Fonte do ledger
Request
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",
"type": "LEDGER"
}'
Response
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
"name": "Ledger Principal",
"type": "LEDGER",
"config": {},
"createdAt": "2024-01-20T10:02:00Z",
"updatedAt": "2024-01-20T10:02:00Z"
}
Passo 3: criar uma regra de match
Defina como as transações são comparadas durante a conciliação.
Este exemplo aplica um match exato em valor, moeda e data.
Request
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": {
"fields": ["amount", "currency", "date"]
}
}'
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
"type": "EXACT",
"priority": 1,
"config": {
"fields": ["amount", "currency", "date"]
},
"createdAt": "2024-01-20T10:03:00Z",
"updatedAt": "2024-01-20T10:03:00Z"
}
Passo 4: fazer upload dos arquivos de transações
Faça upload dos dados de transações para cada fonte configurada.
Aguarde até que ambos os jobs de ingestão sejam concluídos antes de iniciar o job de matching.
Passo 5: executar o job de matching
Comece com um dry run para visualizar os resultados da conciliação sem persistir as alterações.
Dry run
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"
}'
Revisar resultados
O dry run retorna:
- Matches propostos com scores de confiança
- Transações não conciliadas classificadas como exceções
- Um resumo da efetividade da conciliação
Passo 6: confirmar resultados
Se os resultados visualizados estiverem corretos, execute o job novamente usando o modo COMMIT para finalizar a conciliação.
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"
}'
Entendendo os resultados
Após a conciliação:
- Matches de alta confiança são automaticamente confirmados
- Transações não conciliadas são registradas como exceções
- Todas as ações são persistidas no log de auditoria
Agora você pode revisar, rotear ou resolver exceções conforme necessário.
Resumo
Este início rápido cobriu o ciclo de vida completo da conciliação:
Contexto definido
Escopo da conciliação estabelecido
Fontes adicionadas
Fontes bancárias e do ledger configuradas
Regras criadas
Lógica de matching exato aplicada
Dados ingeridos
Arquivos de transações enviados
Matching executado
Dry run revisado e resultados confirmados
Exceções identificadas
Transações não conciliadas isoladas
Próximos passos
