Revisão de correspondências

Revise as correspondências depois de uma execução. Entenda a pontuação de confiança de 0–100, os quatro componentes ponderados dela, as causas de variação e como confirmar, rejeitar ou revogar um grupo de correspondência.

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 confirmar, rejeitar ou revogar grupos de correspondência.

​

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. Você pode confirmar um grupo proposto com a operação de confirmação ou rejeitá-lo com a operação de unmatch e um motivo obrigatório.
• Rejeitar um grupo PROPOSED devolve as transações dele ao conjunto de não conciliados, exceto uma transação que você resolveu separadamente com uma correspondência forçada: ela continua MATCHED. Revogar um grupo CONFIRMED devolve todas as transações. 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 confirmá-la com a operação de confirmação ou rejeitá-la pela operação de unmatch. Veja Pontuação de confiança.

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	Confirmar pela operação de confirmação ou rejeitar pela operação de unmatch
CONFIRMED	A correspondência foi autoconfirmada, confirmada por um revisor 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, exceto uma transação com correspondência forçada
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 depois confirmá-las ou rejeitá-las.

​

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:

amount · String · obrigatório

Valor do ajuste

currency · String · obrigatório

Código de moeda de três caracteres.

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 do ajuste

description · String · obrigatório

Descrição legível por pessoas

matchGroupId · UUID

Grupo de correspondência ao qual o ajuste se aplica

transactionId · 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:

• Listar candidatos a correspondência
• Listar itens em aberto
• Criar ajuste

​

Confirmar um grupo de correspondência proposto

---

Use a operação confirm para aprovar um grupo PROPOSED em uma única etapa. Apenas os papéis operator e admin podem confirmar.

Use POST /v1/matching/groups/{matchGroupId}/confirm com o parâmetro de query contextId obrigatório (operationId confirmMatchGroup):

cURL

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

Uma confirmação bem-sucedida retorna 200 com o grupo de correspondência.

​

O que acontece depois da confirmação

1. O status da correspondência muda: o grupo vira CONFIRMED. Ele mantém a regra e a pontuação de confiança que o motor deu a ele.
2. Transações conciliadas: as transações dele passam a MATCHED.
3. Variações registradas: o Matcher registra variações de tarifa, residuais de itens em aberto e fechamentos de exceções como faz para um grupo autoconfirmado.
4. Entrada de auditoria gravada: uma entrada CONFIRM registra quem confirmou o grupo. A confirmação não é efetivada sem ela.
5. Eventos de streaming emitidos: o Matcher emite match_group.confirmed e transaction.matched para as transações dele. Veja Eventos do Matcher.
6. Reversão possível: um unmatch posterior reverte um grupo confirmado.

Um grupo que não está mais PROPOSED retorna 409 com o código MTCH-0007, e nada muda. O mesmo código responde quando uma transação do grupo mudou depois da proposta.

O Lerian Console não oferece um controle de confirmação. Confirme um grupo proposto pela 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. Ao rejeitar um grupo PROPOSED, uma transação que você resolveu separadamente com uma correspondência forçada continua MATCHED. 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. A requisição aceita um header X-Idempotency opcional. Fazer o unmatch de um grupo que já está rejeitado ou revogado retorna 409 com o código MTCH-0007.

​

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:

1. O status da correspondência muda: um grupo CONFIRMED vira REVOKED. Um grupo ainda PROPOSED vira REJECTED.
2. Transações devolvidas: as transações associadas voltam ao status UNMATCHED de forma atômica com a mudança de status. Ao rejeitar um grupo PROPOSED, uma transação que você resolveu separadamente com uma correspondência forçada continua MATCHED.
3. 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. Se uma correspondência manual ou automática fechou uma exceção, o Matcher marca essa exceção como UNMATCH_WITHDRAWN, e a próxima exceção que o Matcher levantar na transação a reabre. Essas mudanças e a mudança de status acontecem em uma única transação.
4. Motivo registrado: o grupo guarda o motivo de rejeição ou de revogação informado.
5. Evento de streaming emitido: um evento match_group.unmatched é emitido apenas quando o grupo estava CONFIRMED antes.
6. 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 e a operação de confirmaçã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.

​

Próximos passos

---

Resolução de exceções

Trate as transações sem correspondência automática.

Pontuação de confiança

Veja em detalhe como o Matcher calcula as pontuações de confiança.