> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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 rejeitar ou revogar um grupo de correspondência. Depois de rodar um job de correspondência, você precisa revisar 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 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. **As correspondências FUZZY e DATE\_LAG nunca são autoconfirmadas.** A autoconfirmação com pontuação ≥ 90 vale para as correspondências elegíveis 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`, independente da pontuação dela, mesmo uma correspondência FUZZY com pontuação 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](/pt/products/matcher/reference/matcher-confidence-scoring#fuzzy-matches-never-auto-confirm). Ciclo de vida do status da 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 elegíveis 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. | | Sem correspondência | Abaixo de 60 | Os candidatos de confiança baixa não são propostos como correspondências e viram exceções. | ### 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 as propostas de candidatos ranqueadas que o motor considerou para uma transação, o "porquê" de uma correspondência proposta, incluindo as contribuições por componente. ```bash cURL theme={null} 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 do lado oposto e retorna apenas candidatos 1:1. 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. ```bash cURL theme={null} 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 de grupo confirmado removeu a última contribuição ativa por trás da obrigação. O item permanece como histórico, mas é terminal e não pode ser compensado nem levado adiante. | 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. Um unmatch bem-sucedido de grupo confirmado retira os efeitos residuais daquele grupo. Se nenhuma contribuição ativa continua por trás da obrigação, o item termina como `WITHDRAWN`. Esse status significa que o unmatch levou o item de volta. Ele não significa que o item foi compensado nem que envelheceu. ### 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. ```bash cURL theme={null} 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: Valor do ajuste String de moeda não vazia. O Matcher não valida se ela pertence à ISO 4217 nesse ajuste. `DEBIT` ou `CREDIT` `BANK_FEE`, `FX_DIFFERENCE`, `ROUNDING`, `WRITE_OFF` ou `MISCELLANEOUS` Motivo de negócio do ajuste Descrição legível por pessoas Grupo de correspondência ao qual o ajuste se aplica Transação à qual o ajuste se aplica Envie pelo menos um de `matchGroupId` ou `transactionId`. Referência da API: * [Listar candidatos a correspondência](/pt/reference/products/matcher/list-match-candidates) * [Listar itens em aberto](/pt/reference/products/matcher/list-open-items) * [Criar ajuste](/pt/reference/products/matcher/create-adjustment) ## 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`): ```bash cURL theme={null} 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. Para um grupo `CONFIRMED`, o Matcher verifica a reversão do residual/item em aberto antes de mudar o grupo ou as transações dele. Uma operação bem-sucedida acrescenta os lançamentos compensatórios no ledger, revoga o grupo e devolve as transações dele para `UNMATCHED`, tudo de forma atômica. A operação de unmatch exige um motivo não vazio. Para um grupo confirmado, ela reverte os efeitos de residual/item em aberto junto com o grupo e as transações dele, ou retorna **409 Conflict** antes de mudar qualquer coisa. Um lançamento ativo posterior sobre o residual bloqueia a reversão anterior. Uma obrigação ativa mais nova na mesma identidade também bloqueia a reversão quando restaurar um item terminal geraria conflito. ### 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. **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 *** 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. Os limiares de confiança não mudam. As correspondências elegíveis 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`, e pontuações abaixo de 60 viram 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 autoconfirmadas e continuam `PROPOSED`, independente 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 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. 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. 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 *** Trate as transações sem correspondência automática. Veja em profundidade como o Matcher calcula as pontuações de confiança.