Revisão de correspondências

Depois de rodar um job de correspondência, revise os resultados. Este guia explica como interpretar os resultados de correspondência, entender as pontuações de confiança e rejeitar grupos propostos ou revogar grupos confirmados.

Ciclo de vida do status da correspondência

As correspondências seguem um ciclo de vida definido:

Quando o motor de correspondência encontra um par de transações que se correspondem, ele cria uma correspondência com status PROPOSED.
As correspondências criadas pelo motor com pontuação 90 ou acima a partir de regras EXACT e TOLERANCE são autoconfirmadas na hora. As correspondências manuais, criadas com POST /v1/matching/manual, começam com status CONFIRMED. As correspondências FUZZY e DATE_LAG continuam PROPOSED e nunca são autoconfirmadas.
As correspondências que não são autoconfirmadas continuam em PROPOSED. A API pública de grupos de correspondência não expõe confirmação manual, mas você pode rejeitar um grupo proposto com a operação de unmatch e um motivo obrigatório.
Rejeitar um grupo PROPOSED ou revogar um grupo CONFIRMED devolve as transações dele ao conjunto de não conciliados. A mudança de status e a devolução das transações acontecem de forma atômica.
Quando o Matcher muda o status das transações de uma correspondência, ele muda todas ou nenhuma. Uma correspondência manual que perde uma disputa por uma transação recebe 409, e o Matcher não aplica nada.

As correspondências FUZZY e DATE_LAG nunca são autoconfirmadas. A autoconfirmação com pontuação ≥ 90 vale para as correspondências EXACT e TOLERANCE criadas pelo motor. Uma correspondência manual começa com status CONFIRMED. Uma correspondência produzida por uma regra FUZZY ou DATE_LAG fica em PROPOSED, independentemente da pontuação dela, mesmo quando pontua 90+. Você pode rejeitá-la pela operação de unmatch. Não existe operação pública de confirmação manual. 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, mas não confirmada	Revisar ou rejeitar pela operação de unmatch
`CONFIRMED`	A correspondência foi autoconfirmada ou criada como correspondência manual	Revogar pela operação de unmatch se estiver incorreta
`REJECTED`	A correspondência foi recusada	As transações voltam ao conjunto de não conciliados
`REVOKED`	Uma correspondência confirmada antes foi revogada	As transações voltam ao conjunto de não conciliados

Faixas de confiança

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

Níveis de confiança

Faixa	Intervalo de pontuação	Comportamento
Elegível para autoconfirmação	90-100	As correspondências EXACT e TOLERANCE criadas pelo motor são confirmadas automaticamente, sem revisão manual. As correspondências manuais são criadas como `CONFIRMED`. As correspondências FUZZY e DATE_LAG continuam `PROPOSED`.
Precisa de revisão	60-89	As correspondências de confiança média continuam `PROPOSED`. Você pode revisá-las e rejeitá-las, mas a API pública não expõe confirmação manual.

Entendendo a pontuação

O Matcher calcula a pontuação de confiança a partir de componentes ponderados:

Componente	Peso	O que mede
Correspondência de valor	40%	O quanto os valores das transações se aproximam
Correspondência de moeda	30%	Se as moedas são iguais
Tolerância de data	20%	O quanto as datas das transações são próximas
Correspondência de referência	10%	Se as referências das transações coincidem

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 as variações

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

Variação de valor

Causas comuns de variação de valor:

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

Momento da liquidação
Diferenças de fuso horário
Data de lançamento vs. data da transação
Processamento em fim de semana/feriado

Candidatos a correspondência, itens em aberto e ajustes

O Matcher oferece três superfícies para trabalhar uma fila de revisão: candidatos a correspondência, itens em aberto e ajustes.

Listar candidatos a correspondência

Obtenha os candidatos de contrapartida ranqueados de uma transação, da maior pontuação para a menor. Cada candidato traz a pontuação de confiança, a regra que produziu a pontuação e as diferenças de valor e de data. O objeto why dele mostra quais campos coincidem.

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 query contextId, transactionId e limit, e retorna um CandidateProposalsResponse. O limit tem padrão 50 e aceita valores de 1 a 200. O seletor de candidatos varre no máximo 5.000 transações não conciliadas no contexto e retorna apenas candidatos 1:1 do lado oposto. Ele aplica o componente de pontuação compartilhado aos dados brutos da transação, sem a normalização de tarifas em tempo de execução nem a correspondência por faixa de variação de FX que uma execução de correspondência usa.

Listar itens em aberto

Itens em aberto são saldos residuais que restam quando uma transação compensa apenas em parte. Acompanhe esses itens para expor valores que ainda precisam de compensação ou que passaram do limite de aging.

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 aceita um filtro status, além de paginação por limit/cursor.

Status dos itens em aberto

Status	Quando ocorre
`OPEN`	Residual novo. O item tem saldo remanescente e nenhuma perna compensou contra ele ainda.
`PARTIALLY_CLEARED`	Pelo menos uma perna compensou contra o saldo, mas ainda resta um residual.
`CLEARED`	O residual foi totalmente compensado dentro da tolerância.
`AGED`	O item continuou em aberto além do limite de aging dele, medido a partir da data de negócio da obrigação ou do horário legado de primeira aparição.
`WITHDRAWN`	Um unmatch desfez a correspondência confirmada que criou a obrigação.

O ciclo de vida normal flui OPEN → PARTIALLY_CLEARED → CLEARED, e qualquer item ainda em aberto pode virar AGED assim que passa do limite de aging. WITHDRAWN é terminal.

Criar um ajuste

Lance um ajuste contábil para registrar uma variação (tarifa bancária, diferença de FX, arredondamento, baixa e assim por diante) contra um grupo de correspondência ou uma 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 exige o parâmetro de query contextId. Campos do corpo:

String

obrigatório

Valor do ajuste

String

obrigatório

Código de moeda de três caracteres.

String

obrigatório

DEBIT ou CREDIT

String

obrigatório

BANK_FEE, FX_DIFFERENCE, ROUNDING, WRITE_OFF ou MISCELLANEOUS

String

obrigatório

Motivo de negócio do ajuste

String

obrigatório

Descrição legível por pessoas

UUID

Grupo de correspondência ao qual o ajuste se aplica

UUID

Transação à qual o ajuste se aplica

Envie pelo menos um de matchGroupId ou transactionId. Para ler os ajustes registrados em um contexto, use GET /v1/matching/contexts/{contextId}/adjustments. Ele aceita um filtro opcional matchGroupId e pagina com cursor.

Referência da API:

Rejeitar ou revogar grupos de correspondência

Use a operação unmatch para rejeitar um grupo PROPOSED ou revogar um grupo CONFIRMED. Depois de uma operação bem-sucedida, o Matcher devolve as transações do grupo para UNMATCHED. A próxima execução pode fazer a correspondência delas de novo. Use DELETE /v1/matching/groups/{matchGroupId} com o parâmetro de query contextId obrigatório e um reason no corpo da requisiçã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 e não deve ficar vazio.

Quando rejeitar ou revogar

Cenários comuns para rejeitar ou revogar um grupo:

Correspondência incorreta confirmada: as transações de um grupo confirmado pertencem a registros diferentes
Informação nova: dados adicionais mostram que a correspondência está errada
Correção na fonte: o sistema de origem emitiu uma correção ou um estorno
Transação duplicada: uma das transações é uma duplicata e recomenda-se removê-la

O que acontece depois do unmatch

Quando você faz o unmatch de um grupo de correspondência:

O status da correspondência muda: um grupo CONFIRMED vira REVOKED. Um grupo ainda PROPOSED vira REJECTED.
Transações devolvidas: todas as transações associadas voltam ao status UNMATCHED de forma atômica com a mudança de status.
Efeitos da confirmação desfeitos: para um grupo CONFIRMED, o Matcher também retira os residuais de itens em aberto do grupo, anula as variações de tarifa dele e retira as exceções que ele levantou. Essas mudanças e a mudança de status acontecem em uma única transação.
Motivo registrado: o grupo guarda o motivo de rejeição ou de revogação informado.
Evento de streaming emitido: um evento match_group.unmatched é emitido apenas quando o grupo estava CONFIRMED antes.
Nova correspondência possível: depois de um unmatch bem-sucedido, a próxima execução pode fazer a correspondência das transações de novo.

Boas práticas

Comece pelas correspondências de menor confiança

Revise primeiro as correspondências com as menores pontuações de confiança. Essas correspondências são as que têm mais chance de estarem erradas. Dê mais atenção a elas.

Entenda os limiares fixos de confiança

Os limiares de confiança não mudam. As correspondências EXACT e TOLERANCE criadas pelo motor com pontuação 90 ou acima são autoconfirmadas. As correspondências manuais começam como CONFIRMED. Pontuações entre 60 e 89 continuam PROPOSED. 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 autoconfirmadas e continuam PROPOSED, independentemente da pontuação.Use o ajuste das regras (prioridade, valores de tolerância) para influenciar quantas correspondências caem em cada faixa.

Informe um motivo claro

Informe um motivo específico ao rejeitar um grupo proposto ou revogar um grupo confirmado. A operação de unmatch exige esse motivo e o guarda junto com o grupo.

Rejeite apenas depois de conferir os dados da fonte

Revise o grupo e as transações de origem dele antes de usar a operação de unmatch. O Matcher expõe essa operação por grupo. Ele não expõe confirmação em lote.

Revise com cuidado as correspondências de valor alto

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

Visão geral

Guias

Console

Operações

Revisão de correspondências

Ciclo de vida do status da correspondência

Definições de status

Faixas de confiança

Níveis de confiança

Entendendo a pontuação

Entendendo as 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 dos itens em aberto

Criar um ajuste

Rejeitar ou revogar grupos de correspondência

Quando rejeitar ou revogar

O que acontece depois do unmatch

Boas práticas

Próximos passos

Resolução de exceções

Pontuação de confiança

​Ciclo de vida do status da correspondência

​Definições de status

​Faixas de confiança

​Níveis de confiança

​Entendendo a pontuação

​Entendendo as 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 dos itens em aberto

​Criar um ajuste

​Rejeitar ou revogar grupos de correspondência

​Quando rejeitar ou revogar

​O que acontece depois do unmatch

​Boas práticas

​Próximos passos

Resolução de exceções

Pontuação de confiança

Ciclo de vida do status da correspondência

Definições de status

Faixas de confiança

Níveis de confiança

Entendendo a pontuação

Entendendo as 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 dos itens em aberto

Criar um ajuste

Rejeitar ou revogar grupos de correspondência

Quando rejeitar ou revogar

O que acontece depois do unmatch

Boas práticas

Próximos passos