Revisão de correspondências

​

Ciclo de vida do status da correspondência

• 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 elegíveis criadas pelo motor (pontuação 90 ou acima) a partir de regras EXACT e TOLERANCE são autoconfirmadas na hora. As correspondências manuais 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 devolve as transações dele ao conjunto de não conciliados. Você pode revogar um grupo CONFIRMED apenas quando o Matcher também consegue reverter todo efeito de residual/item em aberto que a confirmação aplicou. Em caso de sucesso, essas mudanças e a devolução das transações acontecem de forma atômica.

​

Definições de status

​

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

​

Variação de valor

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

​

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

​

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 dos 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": "Variance due to bank processing fee",
   "description": "Bank wire fee adjustment",
   "matchGroupId": "019c96a0-0b74-768c-8d25-2bf065dca2f8"
 }'

​

Rejeitar ou revogar 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: 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

1. Os residuais confirmados vêm primeiro: o Matcher verifica se consegue reverter todo efeito de residual/item em aberto de um grupo CONFIRMED. Se um lançamento posterior ou uma obrigação mais nova em conflito bloqueia a reversão, a operação retorna 409 Conflict e deixa o grupo, as transações e os itens em aberto sem mudança.
2. O status da correspondência muda: um grupo CONFIRMED vira REVOKED. Um grupo ainda PROPOSED vira REJECTED.
3. Transações devolvidas: em caso de sucesso, todas as transações associadas voltam ao status UNMATCHED.
4. Efeitos de item em aberto revertidos: em um unmatch de grupo confirmado, lançamentos compensatórios no ledger retiram os efeitos residuais do grupo na mesma transação. Se isso não deixa nenhuma contribuição ativa por trás de uma obrigação, ela vira WITHDRAWN terminal e não é levada adiante.
5. Motivo registrado: o grupo guarda o motivo de rejeição ou de revogação informado.
6. Evento de streaming emitido: um evento match_group.unmatched é emitido apenas quando o grupo estava CONFIRMED antes.
7. 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

​

Próximos passos