> ## 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 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. > [!NOTE] > > **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](https://docs.lerian.studio/pt/products/matcher/reference/matcher-confidence-scoring.md#rule-types-that-never-auto-confirm). ![Ciclo de vida do status da correspondência](https://mintcdn.com/lerian-49cb71fc/aExJLTeJEpnHlOuM/images/pt/d2/matcher-match-status.svg?fit=max\&auto=format\&n=aExJLTeJEpnHlOuM\&q=85\&s=b70a5923cea1a1ae548dfc1b922b6d89) 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. ```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 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. ```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 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. ```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: **amount** `String` *required* Valor do ajuste **currency** `String` *required* Código de moeda de três caracteres. **direction** `String` *required* `DEBIT` ou `CREDIT` **type** `String` *required* `BANK_FEE`, `FX_DIFFERENCE`, `ROUNDING`, `WRITE_OFF` ou `MISCELLANEOUS` **reason** `String` *required* Motivo de negócio do ajuste **description** `String` *required* 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`. > [!TIP] > > Referência da API: > > * [Listar candidatos a correspondência](https://docs.lerian.studio/pt/reference/products/matcher/list-match-candidates.md) > * [Listar itens em aberto](https://docs.lerian.studio/pt/reference/products/matcher/list-open-items.md) > * [Criar ajuste](https://docs.lerian.studio/pt/reference/products/matcher/create-adjustment.md) ## 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`): ```bash cURL theme={null} 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](https://docs.lerian.studio/pt/reference/events/matcher.md). 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. > [!NOTE] > > 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`): ```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. 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 *** > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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 *** > [card] [Resolução de exceções](https://docs.lerian.studio/pt/products/matcher/daily-reconciliation/matcher-resolving-exceptions.md) > > Trate as transações sem correspondência automática. > [card] [Pontuação de confiança](https://docs.lerian.studio/pt/products/matcher/reference/matcher-confidence-scoring.md) > > Veja em detalhe como o Matcher calcula as pontuações de confiança. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.