Revisando correspondências

Após executar um job de correspondência, você precisa revisar os resultados. Este guia explica como interpretar os resultados das correspondências, entender as pontuações de confiança e aprovar ou rejeitar correspondências propostas.

Ciclo de vida do status da correspondência

As correspondências avançam por um ciclo de vida definido:

Quando o motor de correspondência encontra um par de transações que pertencem juntas, ele cria uma correspondência com status PROPOSED.
Correspondências de alta confiança (pontuação 90 ou acima) provenientes das regras EXACT e TOLERANCE, mais as correspondências manuais, são confirmadas automaticamente de imediato. Correspondências FUZZY e DATE_LAG sempre requerem revisão manual e nunca são confirmadas automaticamente.
Correspondências de menor confiança aguardam revisão manual: um analista pode então confirmá-las ou rejeitá-las.
Transações rejeitadas retornam ao pool de não correspondidas para outra tentativa de correspondência.

Correspondências FUZZY e DATE_LAG nunca são confirmadas automaticamente. A confirmação automática com pontuação ≥ 90 se aplica às regras EXACT e TOLERANCE, mais as correspondências manuais. Uma correspondência produzida por uma regra FUZZY ou DATE_LAG sempre permanece em PROPOSED para revisão manual, independentemente de sua pontuação — mesmo uma correspondência FUZZY com pontuação 90+. Veja Pontuação de confiança.

Ciclo de vida do status da correspondência — Ciclo de vida do status de uma correspondência.

Definições de status

Status	Descrição	Próximas ações
`PROPOSED`	Correspondência identificada pelo sistema, aguardando confirmação	Revisar, confirmar ou rejeitar
`CONFIRMED`	A correspondência foi aprovada (automática ou manual)	Revogar se incorreta
`REJECTED`	A correspondência foi recusada	Transações retornam ao pool de não correspondidas
`REVOKED`	Uma correspondência previamente confirmada foi revogada	Transações retornam ao pool de não correspondidas

Níveis de confiança

O Matcher atribui uma pontuação de confiança (0-100) a cada correspondência proposta. A pontuação determina como a correspondência é tratada.

Níveis de confiança

Nível	Faixa de pontuação	Comportamento
Aprovado automaticamente	90-100	Correspondências de alta confiança são confirmadas automaticamente sem revisão manual (regras EXACT e TOLERANCE, mais as correspondências manuais; correspondências FUZZY e DATE_LAG sempre requerem revisão).
Necessita revisão	60-89	Correspondências de média confiança requerem revisão manual antes da confirmação.
Sem correspondência	Abaixo de 60	Candidatos de baixa confiança não são propostos como correspondências e se tornam exceções.

Entendendo a pontuação

A pontuação de confiança é calculada a partir de componentes ponderados:

Componente	Peso	O que mede
Correspondência de valor	40%	Quão próximos estão os valores das transações
Correspondência de moeda	30%	Se as moedas são as mesmas
Tolerância de data	20%	Quão próximas estão as datas das transações
Correspondência de referência	10%	Se as referências das transações correspondem

Exemplo de detalhamento da pontuação:

Match: BANK-001 ↔ LED-001

Amount: $1,000.00 vs $1,000.00 → 100% × 40% = 40 points
Currency: USD vs USD → 100% × 30% = 30 points
Date: 2024-01-15 vs 2024-01-15 → 100% × 20% = 20 points
Reference: PAY-001 vs PAY-001 → match → 10 points
 ─────────────────────────
Total Confidence: 100 points

Entendendo variações

Quando correspondências têm diferenças, revise os detalhes da variação:

Variação de valor

Causas comuns de variação de valor:

Taxas bancárias
Diferenças de conversão de moeda
Diferenças de arredondamento
Pagamentos parciais

Variação de data

Causas comuns de variação de data:

Tempo de liquidação
Diferenças de fuso horário
Data de lançamento vs. data da transação
Processamento em finais de semana/feriados

Candidatos a correspondência, itens em aberto e ajustes

À medida que você trabalha uma fila de revisão, três perguntas surgem repetidamente: por que o motor propôs esse pareamento?, o que ainda está pendente após uma correspondência parcial? e como eu lanço uma pequena diferença para que ambos os lados se equilibrem? O Matcher responde a cada uma delas com uma superfície dedicada — candidatos a correspondência, itens em aberto e ajustes.

Listar candidatos a correspondência

Recupere as propostas de candidatos ranqueadas que o motor considerou para uma transação — o “porquê” por trás de uma correspondência proposta, incluindo as contribuições por componente.

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/candidates?contextId={contextId}&transactionId={transactionId}&limit=20" \
 -H "Authorization: Bearer $TOKEN"

GET /v1/matching/candidates aceita os parâmetros de consulta contextId, transactionId e limit, e retorna um CandidateProposalsResponse.

Listar itens em aberto

Itens em aberto são saldos residuais deixados quando uma transação é apenas parcialmente compensada. Acompanhe-os para expor valores que ainda precisam ser liquidados ou que envelheceram além do seu limite.

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/open-items?status=OPEN&limit=50" \
 -H "Authorization: Bearer $TOKEN"

GET /v1/matching/contexts/{contextId}/open-items suporta um filtro status, além da paginação limit/cursor.

Status de itens em aberto

Status	Quando ocorre
`OPEN`	Residual novo — o item tem um saldo remanescente e nenhuma perna se compensou contra ele ainda.
`PARTIALLY_CLEARED`	Pelo menos uma perna se compensou contra o saldo, mas ainda resta um residual.
`CLEARED`	O residual foi totalmente compensado dentro da tolerância.
`AGED`	O item excedeu seu limite de envelhecimento enquanto ainda estava em aberto (não resolvido além do SLA configurado).

O ciclo de vida flui OPEN → PARTIALLY_CLEARED → CLEARED, com qualquer item ainda em aberto podendo se tornar AGED assim que ultrapassa o limite de envelhecimento.

Criar um ajuste

Lance um ajuste contábil para contabilizar uma variação (taxa bancária, diferença de câmbio, arredondamento, baixa contábil e assim por diante) contra um grupo de correspondência ou transação.

cURL

curl -X POST "https://api.matcher.example.com/v1/matching/adjustments?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "amount": "10.50",
   "currency": "BRL",
   "direction": "DEBIT",
   "type": "BANK_FEE",
   "reason": "Variance due to bank processing fee",
   "description": "Bank wire fee adjustment",
   "matchGroupId": "019c96a0-0b74-768c-8d25-2bf065dca2f8"
 }'

POST /v1/matching/adjustments requer o parâmetro de consulta contextId. Campos do corpo:

amount

String

obrigatório

Valor do ajuste

currency

String

obrigatório

Código de moeda ISO 4217

direction

String

obrigatório

DEBIT ou CREDIT

type

String

obrigatório

BANK_FEE, FX_DIFFERENCE, ROUNDING, WRITE_OFF ou MISCELLANEOUS

reason

String

obrigatório

Motivo de negócio para o ajuste

description

String

obrigatório

Descrição legível por humanos

matchGroupId

UUID

Grupo de correspondência ao qual o ajuste se aplica

transactionId

UUID

Transação à qual o ajuste se aplica

Referência da API: Listar candidatos a correspondência | Listar itens em aberto | Criar ajuste

Revogando correspondências confirmadas

Às vezes você precisa reverter uma correspondência porque ela foi aprovada incorretamente. A operação unmatch quebra um grupo de correspondência existente e retorna suas transações ao status UNMATCHED para que possam ser correspondidas novamente. Use DELETE /v1/matching/groups/{matchGroupId} com o parâmetro de consulta obrigatório contextId e um reason no corpo da solicitação (operationId unmatch):

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": "incorrect match - amounts do not match"
 }'

Um unmatch bem-sucedido retorna 204 No Content. O campo reason é obrigatório (não vazio).

Desfazer a correspondência de um grupo cria uma trilha de auditoria completa. Esta operação deve ser usada com cuidado e apenas quando necessário.

Quando revogar

Cenários comuns para revogar:

Correspondência incorreta confirmada: A correspondência foi aprovada mas as transações na verdade pertencem a registros diferentes
Nova informação: Dados adicionais mostram que a correspondência está errada
Correção na origem: O sistema de origem emitiu uma correção ou reversão
Transação duplicada: Uma das transações era uma duplicata que deveria ser removida

O que acontece após revogar

Quando a correspondência de um grupo é desfeita:

O status da correspondência muda: Um grupo CONFIRMED passa a REVOKED; um grupo ainda em PROPOSED passa a REJECTED
Transações retornadas: Todas as transações associadas retornam ao status UNMATCHED
Trilha de auditoria criada: Registro completo de quem desfez a correspondência e o motivo fornecido
Webhook acionado: Um evento match_group.unmatched é emitido (apenas quando o grupo estava previamente em CONFIRMED)
Re-correspondência possível: As transações podem ser correspondidas novamente na próxima execução

Melhores práticas

Comece pelas correspondências de menor confiança

Revise primeiro as correspondências com as menores pontuações de confiança. Estas são mais propensas a estar incorretas e precisam de mais atenção.

Entenda os limites de confiança fixos

Os limites de confiança são fixos no sistema. Para as regras EXACT e TOLERANCE, mais as correspondências manuais, pontuações de 90 ou acima são confirmadas automaticamente. Pontuações entre 60 e 89 requerem revisão manual. Pontuações abaixo de 60 se tornam exceções. Esses valores não são configuráveis por contexto. As correspondências FUZZY e DATE_LAG são a exceção: elas nunca são confirmadas automaticamente e sempre requerem revisão, independentemente da pontuação. Use o ajuste de regras (prioridade, valores de tolerância) para influenciar quantas correspondências caem em cada faixa.

Documente suas decisões

Sempre adicione notas ao confirmar ou rejeitar correspondências. Isso cria uma trilha de auditoria e ajuda os membros da equipe a entender o raciocínio.

Use as operações em lote com sabedoria

Confirmar em lote é eficiente, mas use apenas após revisar uma amostra. Nunca confirme em lote sem entender o que você está aprovando.

Revise correspondências de alto valor cuidadosamente

Independentemente da pontuação de confiança, dê atenção extra a correspondências de alto valor. O impacto de uma correspondência incorreta é proporcional ao valor.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Revisando correspondências

Ciclo de vida do status da correspondência

Definições de status

Níveis de confiança

Níveis de confiança

Entendendo a pontuação

Entendendo variações

Variação de valor

Variação de data

Candidatos a correspondência, itens em aberto e ajustes

Listar candidatos a correspondência

Listar itens em aberto

Status de itens em aberto

Criar um ajuste

Revogando correspondências confirmadas

Quando revogar

O que acontece após revogar

Melhores práticas

Próximos passos

Resolvendo exceções

Pontuação de confiança

​Ciclo de vida do status da correspondência

​Definições de status

​Níveis de confiança

​Níveis de confiança

​Entendendo a pontuação

​Entendendo variações

​Variação de valor

​Variação de data

​Candidatos a correspondência, itens em aberto e ajustes

​Listar candidatos a correspondência

​Listar itens em aberto

​Status de itens em aberto

​Criar um ajuste

​Revogando correspondências confirmadas

​Quando revogar

​O que acontece após revogar

​Melhores práticas

​Próximos passos

Resolvendo exceções

Pontuação de confiança

Ciclo de vida do status da correspondência

Definições de status

Níveis de confiança

Níveis de confiança

Entendendo a pontuação

Entendendo variações

Variação de valor

Variação de data

Candidatos a correspondência, itens em aberto e ajustes

Listar candidatos a correspondência

Listar itens em aberto

Status de itens em aberto

Criar um ajuste

Revogando correspondências confirmadas

Quando revogar

O que acontece após revogar

Melhores práticas

Próximos passos