> ## 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.

# Revisando correspondências

> Interprete os resultados das correspondências, entenda as pontuações de confiança e aprove ou rejeite as correspondências propostas após uma execução de conciliação.

Após executar um job de correspondência, você precisa revisar os resultados. Este guia explica como interpretar os resultados das correspondências, entender as pontuações de confiança e aprovar ou rejeitar correspondências propostas.

## Ciclo de vida do status da correspondência

***

As correspondências avançam por um ciclo de vida definido:

* 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 de alta confiança (pontuação 90 ou acima) provenientes das regras EXACT e TOLERANCE, mais as correspondências manuais, são confirmadas automaticamente de imediato. Correspondências FUZZY e DATE\_LAG sempre requerem revisão manual e nunca são confirmadas automaticamente.
* Correspondências de menor confiança aguardam revisão manual: um analista pode então confirmá-las ou rejeitá-las.
* Transações rejeitadas retornam ao pool de não correspondidas para outra tentativa de correspondência.

<Note>
  **Correspondências FUZZY e DATE\_LAG nunca são confirmadas automaticamente.** A confirmação automática com pontuação ≥ 90 se aplica às regras EXACT e TOLERANCE, mais as correspondências manuais. Uma correspondência produzida por uma regra FUZZY ou DATE\_LAG sempre permanece em `PROPOSED` para revisão manual, independentemente de sua pontuação — mesmo uma correspondência FUZZY com pontuação 90+. Veja [Pontuação de confiança](/pt/matcher/reference/matcher-confidence-scoring#matches-fuzzy-nunca-confirmam-automaticamente).
</Note>

<Frame caption="Ciclo de vida do status de uma correspondência.">
  <img src="https://mintcdn.com/lerian-49cb71fc/dIivJl2jpQJ0JZcX/images/pt/d2/matcher-match-status.svg?fit=max&auto=format&n=dIivJl2jpQJ0JZcX&q=85&s=d9b4c9cc4b19c3f311506bd7cd95983f" alt="Ciclo de vida do status da correspondência" width="652" height="772" data-path="images/pt/d2/matcher-match-status.svg" />
</Frame>

### Definições de status

| Status      | Descrição                                                         | Próximas ações                                    |
| ----------- | ----------------------------------------------------------------- | ------------------------------------------------- |
| `PROPOSED`  | Correspondência identificada pelo sistema, aguardando confirmação | Revisar, confirmar ou rejeitar                    |
| `CONFIRMED` | A correspondência foi aprovada (automática ou manual)             | Revogar se incorreta                              |
| `REJECTED`  | A correspondência foi recusada                                    | Transações retornam ao pool de não correspondidas |
| `REVOKED`   | Uma correspondência previamente confirmada foi revogada           | Transações retornam ao pool de não correspondidas |

## Níveis de confiança

***

O Matcher atribui uma pontuação de confiança (0-100) a cada correspondência proposta. A pontuação determina como a correspondência é tratada.

### Níveis de confiança

| Nível                    | Faixa de pontuação | Comportamento                                                                                                                                                                                                   |
| ------------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Aprovado automaticamente | 90-100             | Correspondências de alta confiança são confirmadas automaticamente sem revisão manual (regras EXACT e TOLERANCE, mais as correspondências manuais; correspondências FUZZY e DATE\_LAG sempre requerem revisão). |
| Necessita revisão        | 60-89              | Correspondências de média confiança requerem revisão manual antes da confirmação.                                                                                                                               |
| Sem correspondência      | Abaixo de 60       | Candidatos de baixa confiança não são propostos como correspondências e se tornam exceções.                                                                                                                     |

### Entendendo a pontuação

A pontuação de confiança é calculada a partir de componentes ponderados:

| Componente                    | Peso | O que mede                                    |
| ----------------------------- | ---- | --------------------------------------------- |
| Correspondência de valor      | 40%  | Quão próximos estão os valores das transações |
| Correspondência de moeda      | 30%  | Se as moedas são as mesmas                    |
| Tolerância de data            | 20%  | Quão próximas estão as datas das transações   |
| Correspondência de referência | 10%  | Se as referências das transações correspondem |

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

***

Quando correspondências têm diferenças, revise os detalhes da variação:

### Variação de valor

Causas comuns de variação de valor:

* Taxas 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:

* 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

***

À medida que você trabalha uma fila de revisão, três perguntas surgem repetidamente: *por que o motor propôs esse pareamento?*, *o que ainda está pendente após uma correspondência parcial?* e *como eu lanço uma pequena diferença para que ambos os lados se equilibrem?* O Matcher responde a cada uma delas com uma superfície dedicada — candidatos a correspondência, itens em aberto e ajustes.

### Listar candidatos a correspondência

Recupere as propostas de candidatos ranqueadas que o motor considerou para uma transação — o "porquê" por trás 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 consulta `contextId`, `transactionId` e `limit`, e retorna um `CandidateProposalsResponse`.

### Listar itens em aberto

Itens em aberto são saldos residuais deixados quando uma transação é apenas parcialmente compensada. Acompanhe-os para expor valores que ainda precisam ser liquidados ou que envelheceram além do seu limite.

```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` suporta um filtro `status`, além da paginação `limit`/`cursor`.

#### Status de itens em aberto

| Status              | Quando ocorre                                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `OPEN`              | Residual novo — o item tem um saldo remanescente e nenhuma perna se compensou contra ele ainda.                      |
| `PARTIALLY_CLEARED` | Pelo menos uma perna se compensou contra o saldo, mas ainda resta um residual.                                       |
| `CLEARED`           | O residual foi totalmente compensado dentro da tolerância.                                                           |
| `AGED`              | O item excedeu seu limite de envelhecimento enquanto ainda estava em aberto (não resolvido além do SLA configurado). |

O ciclo de vida flui `OPEN` → `PARTIALLY_CLEARED` → `CLEARED`, com qualquer item ainda em aberto podendo se tornar `AGED` assim que ultrapassa o limite de envelhecimento.

### Criar um ajuste

Lance um ajuste contábil para contabilizar uma variação (taxa bancária, diferença de câmbio, arredondamento, baixa contábil e assim por diante) contra um grupo de correspondência ou 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` requer o parâmetro de consulta `contextId`. Campos do corpo:

<ParamField path="amount" type="String" required>
  Valor do ajuste
</ParamField>

<ParamField path="currency" type="String" required>
  Código de moeda ISO 4217
</ParamField>

<ParamField path="direction" type="String" required>
  `DEBIT` ou `CREDIT`
</ParamField>

<ParamField path="type" type="String" required>
  `BANK_FEE`, `FX_DIFFERENCE`, `ROUNDING`, `WRITE_OFF` ou `MISCELLANEOUS`
</ParamField>

<ParamField path="reason" type="String" required>
  Motivo de negócio para o ajuste
</ParamField>

<ParamField path="description" type="String" required>
  Descrição legível por humanos
</ParamField>

<ParamField path="matchGroupId" type="UUID">
  Grupo de correspondência ao qual o ajuste se aplica
</ParamField>

<ParamField path="transactionId" type="UUID">
  Transação à qual o ajuste se aplica
</ParamField>

<Tip>Referência da API: [Listar candidatos a correspondência](/pt/reference/matcher/list-match-candidates) | [Listar itens em aberto](/pt/reference/matcher/list-open-items) | [Criar ajuste](/pt/reference/matcher/create-adjustment)</Tip>

## Revogando correspondências confirmadas

***

Às vezes você precisa reverter uma correspondência porque ela foi aprovada incorretamente. A operação **unmatch** quebra um grupo de correspondência existente e retorna suas transações ao status `UNMATCHED` para que possam ser correspondidas novamente.

Use `DELETE /v1/matching/groups/{matchGroupId}` com o parâmetro de consulta obrigatório `contextId` e um `reason` no corpo da solicitaçã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 (não vazio).

<Warning>
  Desfazer a correspondência de um grupo cria uma trilha de auditoria completa. Esta operação deve ser usada com cuidado e apenas quando necessário.
</Warning>

### Quando revogar

Cenários comuns para 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 revogar

Quando a correspondência de um grupo é desfeita:

1. **O status da correspondência muda**: Um grupo `CONFIRMED` passa a `REVOKED`; um grupo ainda em `PROPOSED` passa a `REJECTED`
2. **Transações retornadas**: Todas as transações associadas retornam ao status `UNMATCHED`
3. **Trilha de auditoria criada**: Registro completo de quem desfez a correspondência e o motivo fornecido
4. **Webhook acionado**: Um evento `match_group.unmatched` é emitido (apenas quando o grupo estava previamente em `CONFIRMED`)
5. **Re-correspondência possível**: As transações podem ser correspondidas novamente na próxima execução

## Melhores práticas

***

<AccordionGroup>
  <Accordion title="Comece pelas correspondências de menor confiança">
    Revise primeiro as correspondências com as menores pontuações de confiança. Estas são mais propensas a estar incorretas e precisam de mais atenção.
  </Accordion>

  <Accordion title="Entenda os limites de confiança fixos">
    Os limites de confiança são fixos no sistema. Para as regras EXACT e TOLERANCE, mais as correspondências manuais, pontuações de 90 ou acima são confirmadas automaticamente. Pontuações entre 60 e 89 requerem revisão manual. Pontuações abaixo de 60 se tornam 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 confirmadas automaticamente e sempre requerem revisão, independentemente da pontuação.** Use o ajuste de regras (prioridade, valores de tolerância) para influenciar quantas correspondências caem em cada faixa.
  </Accordion>

  <Accordion title="Documente suas decisões">
    Sempre adicione notas ao confirmar ou rejeitar correspondências. Isso cria uma trilha de auditoria e ajuda os membros da equipe a entender o raciocínio.
  </Accordion>

  <Accordion title="Use as operações em lote com sabedoria">
    Confirmar em lote é eficiente, mas use apenas após revisar uma amostra. Nunca confirme em lote sem entender o que você está aprovando.
  </Accordion>

  <Accordion title="Revise correspondências de alto valor cuidadosamente">
    Independentemente da pontuação de confiança, dê atenção extra a correspondências de alto valor. O impacto de uma correspondência incorreta é proporcional ao valor.
  </Accordion>
</AccordionGroup>

## Próximos passos

***

<Card title="Resolvendo exceções" icon="triangle-exclamation" href="/pt/matcher/daily-reconciliation/matcher-resolving-exceptions" horizontal>
  Lide com transações que não puderam ser correspondidas automaticamente.
</Card>

<Card title="Pontuação de confiança" icon="chart-simple" href="/pt/matcher/reference/matcher-confidence-scoring" horizontal>
  Aprofunde-se em como as pontuações de confiança são calculadas.
</Card>