Revisando correspondências

​

Ciclo de vida do status da correspondência

• 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 elegíveis criadas pelo motor (pontuação 90 ou acima) pelas regras EXACT e TOLERANCE são confirmadas automaticamente de imediato. Correspondências manuais são criadas com status CONFIRMED. Correspondências FUZZY e DATE_LAG permanecem em PROPOSED e nunca são confirmadas automaticamente.
• Correspondências que não são confirmadas automaticamente permanecem 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 por meio da operação unmatch e de um motivo obrigatório.
• Rejeitar um grupo PROPOSED devolve suas transações ao pool de não correspondidas. Um grupo CONFIRMED só pode ser revogado quando o Matcher também consegue reverter cada efeito residual/de item em aberto aplicado por essa confirmação; se tiver êxito, essas mudanças e a devolução das transações ocorrem de forma atômica.

​

Definições de status

​

Níveis de confiança

​

Níveis de confiança

​

Entendendo a 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

​

Variação de valor

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

​

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

​

Listar candidatos a correspondência

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

​

Listar itens em aberto

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

​

Status de itens em aberto

​

Criar um ajuste

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": "Variação causada por tarifa de processamento bancário",
   "description": "Ajuste de tarifa de transferência bancária",
   "matchGroupId": "019c96a0-0b74-768c-8d25-2bf065dca2f8"
 }'

​

Rejeitando ou revogando grupos de correspondência

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

​

Quando rejeitar ou 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 unmatch

1. Os residuais confirmados são verificados primeiro: O Matcher verifica se cada efeito residual/de item em aberto de um grupo CONFIRMED pode ser revertido. Se uma entrada posterior ou uma obrigação mais recente em conflito bloquear a reversão, a operação retorna 409 Conflict e deixa o grupo, as transações e os itens em aberto inalterados.
2. O status da correspondência muda: Um grupo CONFIRMED passa a REVOKED; um grupo ainda em PROPOSED passa a REJECTED.
3. Transações retornadas: Em caso de sucesso, todas as transações associadas retornam ao status UNMATCHED.
4. Os efeitos de itens em aberto são revertidos: Em um unmatch de grupo confirmado, as entradas compensatórias do ledger retiram os efeitos residuais do grupo na mesma transação. Se não restar contribuição ativa por trás de uma obrigação, ela passa ao status terminal WITHDRAWN e não é carregada para a próxima execução.
5. Motivo registrado: O grupo armazena o motivo fornecido para rejeição ou revogação.
6. Evento de streaming emitido: Um evento match_group.unmatched é emitido apenas quando o grupo estava previamente em CONFIRMED.
7. Nova correspondência possível: As transações podem ser correspondidas novamente na próxima execução após um unmatch bem-sucedido.

​

Melhores práticas

​

Próximos passos