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

# Resolução de exceções

> Revise, priorize e resolva as transações que o Matcher não conseguiu conciliar automaticamente, usando severidade, ciclo de vida e ações que preservam a auditoria.

Este guia mostra como revisar exceções, priorizar o trabalho pela severidade e resolver itens com o nível certo de documentação.

## O que é uma exceção?

***

Uma exceção marca uma transação que precisa da sua revisão. As causas comuns incluem:

* **Nenhum candidato encontrado**: nenhuma transação na outra fonte atende aos critérios da regra ativa.
* **Rejeição de duplicata**: uma correspondência anterior foi rejeitada e não sobrou candidato alternativo.
* **Desequilíbrio entre fontes**: uma fonte contém transações que não estão na outra.

## Ciclo de vida da exceção

***

As exceções seguem um workflow simples:

* Quando o Matcher não consegue conciliar uma transação, ele cria uma exceção com status `OPEN`.
* Ao atribuir a exceção, ela passa de `OPEN` para `ASSIGNED`. Ao atribuir uma exceção `ASSIGNED`, ela passa para o novo responsável, e o histórico registra os dois responsáveis. A atribuição mantém a data de vencimento já definida. A API não expõe uma operação de remover atribuição. Você deve enviar um `assignee` não vazio.
* A correspondência forçada e o ajuste de lançamento definem `PENDING_RESOLUTION` enquanto a operação está em andamento. Em caso de sucesso, a exceção vai para `RESOLVED`.
* A resolução direta move uma exceção `OPEN` ou `ASSIGNED` para `RESOLVED`.
* Uma correspondência manual que pareia a exceção, ou uma execução posterior que concilia a transação dela, também a move para `RESOLVED`. Veja [Resolvida por uma correspondência](#resolved-by-a-match).
* Uma nova exceção na transação reabre uma exceção `RESOLVED` que uma correspondência automática ou um unmatch fechou: ela volta para `OPEN` sem responsável e sem data de vencimento.
* O despacho grava um evento de auditoria `DISPATCH` e emite `exception.dispatched`. Ele não muda o status da exceção.

![Ciclo de vida de exceção do Matcher](https://mintcdn.com/lerian-49cb71fc/aExJLTeJEpnHlOuM/images/pt/d2/matcher-exception-lifecycle.svg?fit=max\&auto=format\&n=aExJLTeJEpnHlOuM\&q=85\&s=67aa2ebce5168c4f92c426161a46dced)

O ciclo de vida de uma exceção no Matcher

### Definições de status

| Status | Descrição | Quem pode fazer a transição |
| - | - | - |
| `OPEN` | Nova exceção aguardando atribuição | Sistema |
| `ASSIGNED` | Atribuída a um analista para investigação | Sistema, Analista |
| `PENDING_RESOLUTION` | Correspondência forçada ou ajuste de lançamento em andamento | Sistema |
| `RESOLVED` | Fechada com uma resolução auditável | Analista, Sistema |

### Endpoints da máquina de estados

Os endpoints de exceção única a seguir mudam o ciclo de vida ou registram ações relacionadas. Cada um é identificado pelo `exceptionId` da exceção no caminho.

| Endpoint | Método e caminho | Objetivo |
| - | - | - |
| Atribuir exceção | `POST /v1/exceptions/{exceptionId}/assign` | Atribui a exceção a um analista. Corpo: `assignee` (obrigatório). Retorna a exceção atualizada. (`OPEN` → `ASSIGNED`, ou `ASSIGNED` para um novo responsável) |
| Despachar exceção | `POST /v1/exceptions/{exceptionId}/dispatch` | Registra um despacho para um sistema de destino. Corpo: `targetSystem` (obrigatório; `MANUAL` é o valor de destino que registra um despacho), `queue` (opcional). Grava um evento de auditoria `DISPATCH` e emite `exception.dispatched` sem mudar o status. |
| Resolver exceção | `POST /v1/exceptions/{exceptionId}/resolve` | Resolve uma única exceção. Corpo: `resolution` (obrigatório), `reason` (opcional). Espelha a validação da resolução em lote para uma exceção. (`OPEN` ou `ASSIGNED` → `RESOLVED`) |
| Correspondência forçada | `POST /v1/exceptions/{exceptionId}/force-match` | Marca a transação da exceção como conciliada e resolve a exceção. Corpo: `overrideReason` (`POLICY_EXCEPTION`, `OPS_APPROVAL`, `CUSTOMER_DISPUTE` ou `DATA_CORRECTION`) e `notes`. Usa `PENDING_RESOLUTION` enquanto a operação está em andamento. |
| Ajustar lançamento | `POST /v1/exceptions/{exceptionId}/adjust-entry` | Resolve uma exceção criando um lançamento contábil de ajuste. Corpo: `amount`, `currency`, `effectiveAt`, `notes`, `reasonCode` (todos obrigatórios) e `direction` (opcional: `DEBIT` ou `CREDIT`; `DEBIT` quando omitido). Usa `PENDING_RESOLUTION` enquanto a operação está em andamento. |
| Histórico da exceção | `GET /v1/exceptions/{exceptionId}/history` | Retorna o histórico ordenado das transições de estado e das ações da exceção (`HistoryResponse`). Aceita paginação por `cursor`/`limit`. *(somente leitura)* |
| Selecionar IDs de exceção | `GET /v1/exceptions/ids` | Retorna até 10.000 IDs das exceções que atendem aos filtros atuais (`contextId`, `status`, `severity`, `reason`, …). `total` traz a contagem completa, e `truncated` é `true` quando a lista para no limite. Use para montar uma seleção em lote antes de chamar os endpoints em lote. *(somente leitura)* |

> [!NOTE]
>
> O despacho `MANUAL` confirma a entrega localmente sem chamar um sistema externo.

> [!TIP]
>
> Referência da API:
>
> * [Atribuir exceção](https://docs.lerian.studio/pt/reference/products/matcher/assign-exception.md)
> * [Despachar exceção](https://docs.lerian.studio/pt/reference/products/matcher/dispatch-exception.md)
> * [Resolver exceção](https://docs.lerian.studio/pt/reference/products/matcher/resolve-exception.md)
> * [Correspondência forçada](https://docs.lerian.studio/pt/reference/products/matcher/force-match-exception.md)
> * [Ajustar lançamento](https://docs.lerian.studio/pt/reference/products/matcher/adjust-entry-exception.md)
> * [Obter histórico da exceção](https://docs.lerian.studio/pt/reference/products/matcher/retrieve-exception-history.md)
> * [Selecionar IDs de exceção](https://docs.lerian.studio/pt/reference/products/matcher/select-exception-ids.md)

#### Exemplo de atribuição

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/assign" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "assignee": "john.doe@company.com" }'
```

#### Exemplo de resolução

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/resolve" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "resolution": "ACCEPTED", "reason": "Variance within tolerance" }'
```

#### Exemplo de ajuste de lançamento

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/adjust-entry" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "amount": "150.50",
   "currency": "BRL",
   "effectiveAt": "2026-02-02T16:40:00Z",
   "direction": "CREDIT",
   "reasonCode": "AMOUNT_CORRECTION",
   "notes": "Correcting processing fee discrepancy"
 }'
```

#### Seleção em lote com `selectExceptionIDs`

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/exceptions/ids?contextId={contextId}&status=OPEN&severity=CRITICAL" \
 -H "Authorization: Bearer $TOKEN"
```

Use os IDs retornados nas [operações em lote](#bulk-operations) abaixo.

## Severidade da exceção

***

O Matcher classifica as exceções por severidade para você trabalhar a fila na ordem certa. O valor é o valor absoluto do valor base da transação ou, quando ela não tem valor base, do valor dela. Para um item em aberto envelhecido, é o valor absoluto do saldo em aberto.

| Severidade | Critério |
| - | - |
| **Crítica** | Valor >= 100.000 OU idade >= 120 horas |
| **Alta** | Valor >= 10.000 OU idade >= 72 horas |
| **Média** | Valor >= 1.000 OU idade >= 24 horas |
| **Baixa** | Todas as outras |

O Matcher limita uma exceção com motivo `FEE_DATA_MISSING` a **Média**, qualquer que seja o valor ou a idade dela.

Esses limiares repriorizam a exceção. Eles não criam um prazo de SLA. Um callback de entrada pode informar `dueAt`, e os agregados do dashboard medem o cumprimento desses prazos fornecidos externamente. Defina a política de tempo de resposta no sistema externo que envia o callback.

### Escalonamento de severidade

Cada vez que uma execução de correspondência em modo `COMMIT` encontra uma transação ainda não conciliada, o Matcher recalcula a severidade da exceção não resolvida dessa transação, exceto quando é uma exceção de transação duplicada. A idade conta a partir da data da transação ou, para um item em aberto envelhecido, da data de negócio da obrigação ou do horário de primeira aparição. A classificação usa lógica OU. Basta o limiar de valor ou o limiar de idade para disparar uma severidade maior. Uma exceção recalculada escala assim:

* Uma exceção abaixo de 1.000 começa como **Baixa**, mas escala para **Média** depois de 24 horas.

## Métodos de resolução

***

O Matcher expõe três ações de resolução de exceção.

### 1. Resolver diretamente

Feche uma exceção com um `resolution` obrigatório e um `reason` opcional quando não é preciso correspondência forçada nem ajuste.

### 2. Correspondência forçada

Marque a transação da exceção como conciliada e resolva a exceção. A correspondência forçada não coloca a transação em nenhum grupo de correspondência e não a junta a nenhum correspondente. Para juntar duas transações, crie uma correspondência manual com `POST /v1/matching/manual`.

**Use a correspondência forçada quando:**

* Você consegue explicar e documentar a justificativa com clareza.
* A variação é esperada (tarifas, tempo, arredondamento).

A correspondência forçada ignora a pontuação e a lógica de regras. Use apenas quando você puder justificar a decisão por escrito.

### 3. Criar ajuste

Crie um lançamento de ajuste para registrar uma variação ou equilibrar um item não conciliado.

**Códigos de motivo do ajuste:**

| Código de motivo | Caso de uso |
| - | - |
| `AMOUNT_CORRECTION` | Corrigir o valor da transação |
| `CURRENCY_CORRECTION` | Corrigir a moeda da transação |
| `DATE_CORRECTION` | Corrigir a data efetiva |
| `OTHER` | Registrar outra correção documentada |

**Regras de validação:**

* Os valores de ajuste devem ser positivos nas duas direções. Uma requisição com valor zero ou negativo retorna um erro `400 Bad Request`.
* `POST /v1/exceptions/{exceptionId}/adjust-entry` exige um código de moeda ISO 4217 válido.
* `direction` é `DEBIT` ou `CREDIT`. Com `CREDIT`, o Matcher lança um crédito. O evento `exception.adjust_entry_resolved` carrega a direção.
* `reasonCode` deve usar `AMOUNT_CORRECTION`, `CURRENCY_CORRECTION`, `DATE_CORRECTION` ou `OTHER`.

## Resolvida por uma correspondência

***

Uma correspondência pode fechar uma exceção. Cada fechamento registra um `resolutionType` na exceção:

| `resolutionType` | Quando o Matcher o define |
| - | - |
| `FORCE_MATCH` | Você resolveu a exceção com uma correspondência forçada. |
| `ADJUST_ENTRY` | Você resolveu a exceção com um lançamento de ajuste. |
| `MANUAL_MATCH` | Uma correspondência manual pareou a transação da exceção. |
| `AUTO_MATCH` | Uma execução conciliou a transação de uma exceção cujo motivo é `UNMATCHED`, `FX_RATE_UNAVAILABLE`, `MISSING_BASE_AMOUNT`, `MISSING_BASE_CURRENCY` ou `SPLIT_INCOMPLETE`. Qualquer outro motivo continua aberto. |
| `AUTO_CONSUME` | Uma execução liquidou a transação contra um item em aberto carregado. |
| `UNMATCH_WITHDRAWN` | Um unmatch desfez a correspondência que levantou ou resolveu a exceção. |

Para resolver uma exceção com uma correspondência manual, envie o `exceptionId` dela no corpo de `POST /v1/matching/manual`. A transação da exceção deve ser uma das `transactionIds`, ou a requisição retorna `422`. O Matcher resolve a exceção na mesma gravação da correspondência, com `MANUAL_MATCH`. Ele deixa a exceção como está quando ela não está mais aberta ou tem uma disputa ativa. Suas `notes` viram a nota de resolução. Sem `exceptionId`, o Matcher não resolve nenhuma exceção.

Os fechamentos `AUTO_MATCH` e `AUTO_CONSUME`, e o fechamento `MANUAL_MATCH`, emitem `exception.resolved`. Quando você desfaz uma correspondência que fechou uma exceção com `MANUAL_MATCH` ou `AUTO_MATCH`, o Matcher a remarca como `UNMATCH_WITHDRAWN`. A próxima exceção que o Matcher levantar na transação a reabre. Veja [Eventos do Matcher](https://docs.lerian.studio/pt/reference/events/matcher.md).

> [!NOTE]
>
> O Lerian Console não envia `exceptionId`. Uma correspondência manual que você cria no Console não resolve a exceção.

## Registros de resolução

***

O Matcher registra no histórico da exceção e no stream de auditoria as ações de resolução que têm suporte.

| Resolução | Campos da requisição |
| - | - |
| Resolução direta | `resolution` (obrigatório), `reason` (opcional) |
| Correspondência forçada | `overrideReason`, `notes` |
| Ajuste de lançamento | `reasonCode`, `amount`, `currency`, `effectiveAt`, `notes`, `direction` (opcional) |

O Matcher não expõe contratos de resolução para divisão de exceção nem para baixa independente, e não aplica limiares de aprovação por valor nessas ações. Aplique qualquer exigência adicional de aprovação pelos controles da sua organização.

## Operações em lote

***

Ao lidar com grandes volumes de exceções, os endpoints em lote permitem processar até 100 exceções em uma única requisição.

### Atribuição em lote

Atribua várias exceções a um membro do time de uma vez:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/assign" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
   "assignee": "john.doe@company.com"
 }'
```

> [!TIP]
>
> Referência da API:
>
> * [Atribuição em lote](https://docs.lerian.studio/pt/reference/products/matcher/bulk-assign-exceptions.md)
> * [Resolução em lote](https://docs.lerian.studio/pt/reference/products/matcher/bulk-resolve-exceptions.md)
> * [Despacho em lote](https://docs.lerian.studio/pt/reference/products/matcher/bulk-dispatch-exceptions.md)

### Resolução em lote

Resolva várias exceções com uma resolução compartilhada:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/resolve" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
   "resolution": "ACCEPTED",
   "reason": "Verified as valid bank fees"
 }'
```

A resposta inclui os arrays `succeeded` e `failed`, então você pode tratar falhas parciais de forma controlada.

### Despacho em lote

Despache várias exceções:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/dispatch" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f"],
   "targetSystem": "MANUAL",
   "queue": "RECON-TEAM"
 }'
```

## Comentários da exceção

***

Os comentários dão a cada exceção uma trilha de auditoria com notas de investigação e discussão do time. Adicione um comentário conforme o analista trabalha um item:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/comments" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "content": "Contacted bank to verify wire transfer fee. Awaiting confirmation."
 }'
```

A listagem (`GET`) retorna a thread completa, do mais antigo para o mais novo. Você não pode adicionar comentários depois que uma exceção é resolvida. Apenas o autor do comentário pode excluí-lo, e o comentário deve pertencer à exceção identificada na URL.

| Ação | Método e caminho | Campos principais |
| - | - | - |
| Adicionar comentário | `POST /v1/exceptions/{exceptionId}/comments` | `content` (corpo do comentário) |
| Listar comentários | `GET /v1/exceptions/{exceptionId}/comments` | Nenhum (retorna a thread completa, do mais antigo primeiro) |
| Excluir comentário | `DELETE /v1/exceptions/{exceptionId}/comments/{commentId}` | `commentId` no caminho |

> [!TIP]
>
> Referência da API:
>
> * [Listar comentários](https://docs.lerian.studio/pt/reference/products/matcher/list-exception-comments.md)
> * [Adicionar comentário](https://docs.lerian.studio/pt/reference/products/matcher/add-exception-comment.md)
> * [Excluir comentário](https://docs.lerian.studio/pt/reference/products/matcher/delete-exception-comment.md)

## Disputas

***

Quando uma exceção precisa de investigação formal ou envolve uma parte externa (um chargeback, uma consulta ao banco), escale-a para uma **disputa**. As disputas acompanham evidências, mudanças de estado e o resultado final. Liste as disputas com `GET /v1/disputes` (filtre por `state`, por exemplo `OPEN`) ou obtenha uma pelo `disputeId` dela.

> [!TIP]
>
> Referência da API:
>
> * [Listar disputas](https://docs.lerian.studio/pt/reference/products/matcher/list-disputes.md)
> * [Obter disputa](https://docs.lerian.studio/pt/reference/products/matcher/retrieve-dispute.md)
> * [Abrir disputa](https://docs.lerian.studio/pt/reference/products/matcher/open-dispute.md)
> * [Fechar disputa](https://docs.lerian.studio/pt/reference/products/matcher/close-dispute.md)

### Estados e transições de disputa

Uma disputa nova fica `OPEN`. Fechá-la define `WON` ou `LOST`, e os dois resultados são terminais.

## Workflow de resolução de exceções

***

Use este fluxo para manter as revisões consistentes e auditáveis.

**1. Triagem**

Revise a fila por severidade e SLA. Comece pelas Críticas e Altas.

**2. Investigar**

Use o payload da exceção para entender o que falhou e quais candidatos existem.

* Leia `reason` para ver por que a correspondência falhou.
* Chame `GET /v1/matching/candidates` com o `contextId` do contexto de conciliação e o `transactionId` da exceção para revisar correspondências próximas abaixo do limiar. Uma transação que não está `UNMATCHED`, por exemplo uma exceção levantada em um lado já conciliado, retorna uma lista vazia.
* Procure padrões (mesma contraparte, formatos de referência recorrentes).

**3. Resolver**

Escolha a resolução que melhor reflete a realidade e a política.

* **Resolver diretamente**: você pode fechar a exceção sem correspondência forçada nem ajuste.
* **Correspondência forçada**: você aceita a transação como conciliada sem um correspondente.
* **Ajustar**: você precisa de um lançamento de ajuste para a variação.

**4. Documentar**

Registre detalhe suficiente para outra pessoa refazer a sua decisão depois:

* O que você verificou
* O que você concluiu
* Links ou IDs das evidências de apoio

**5. Despachar se necessário**

Se a exceção exige tratamento externo, despache-a. O despacho registra a ação, mas não muda o status da exceção.

## Boas práticas

***

> [accordion] Trabalhe por severidade e SLA
>
> Comece pelos itens Críticos e Altos. Eles carregam o maior risco e os prazos mais apertados.

> [accordion] Torne as decisões auditáveis
>
> As notas não são opcionais. Trate-as como parte da resolução:
>
> * O que você verificou
> * Por que essa resolução está correta
> * Quaisquer IDs de ticket, extratos ou confirmações

> [accordion] Corrija padrões na origem
>
> Exceções que se repetem costumam apontar problemas de configuração:
>
> * Mesma contraparte → Normalize nomes ou mapeamento
> * Mesma janela de datas → Valide se a ingestão está completa
> * Mesma fonte → Revise o mapeamento de campos e as convenções de sinal

> [accordion] Trate as correspondências forçadas como exceções à regra
>
> Se você usa correspondência forçada com frequência, as suas regras ou tolerâncias precisam de atenção.

> [accordion] Atribua o trabalho explicitamente
>
> Atribua as exceções pelos endpoints de atribuição. O Matcher não aplica regras de atribuição automaticamente.

## Próximos passos

***

> [card] [Geração de relatórios](https://docs.lerian.studio/pt/products/matcher/daily-reconciliation/matcher-generating-reports.md)
>
> Crie relatórios de conciliação, exporte resultados e apoie auditorias.

> [card] [Roteamento de exceções](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-exception-routing.md)
>
> Revise os conceitos de severidade, SLA e roteamento de exceções.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.