> ## 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. Exceções são transações que o Matcher não consegue conciliar automaticamente. 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 é criada quando uma transação de uma fonte não tem correspondente válido em outra fonte. As causas comuns incluem: * **Nenhum candidato encontrado**: nenhuma transação na outra fonte atende aos critérios da regra ativa. * **Abaixo do limiar de confiança**: existem candidatos, mas eles pontuam abaixo da confiança mínima (padrão: 60). * **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 faltam 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`. 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 mantêm `PENDING_RESOLUTION` apenas enquanto a operação está em andamento. Em caso de sucesso, a exceção vai para `RESOLVED`. Em caso de falha, ela volta ao status `OPEN` ou `ASSIGNED` anterior. * A resolução direta move uma exceção `OPEN` ou `ASSIGNED` para `RESOLVED`. * O despacho envia a requisição ao conector, 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 ### 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`) | | Despachar exceção | `POST /v1/exceptions/{exceptionId}/dispatch` | Envia a exceção pelo conector configurado. 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` | Resolve uma exceção com `overrideReason` e `notes`. Usa `PENDING_RESOLUTION` enquanto a operação está em andamento, depois resolve ou volta ao status anterior em caso de falha. | | 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). Usa `PENDING_RESOLUTION` enquanto a operação está em andamento, depois resolve ou volta ao status anterior em caso de falha. | | 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 o conjunto completo de IDs de exceção que atendem aos filtros atuais (`contextId`, `status`, `severity`, `reason`, …). Use para montar uma seleção em lote antes de chamar os endpoints em lote. *(somente leitura)* | O Matcher aceita despacho `WEBHOOK`, `JIRA`, `SERVICENOW` e `MANUAL`. `WEBHOOK` exige uma URL fornecida pelo deploy e, quando payloads assinados são obrigatórios, um segredo compartilhado. JIRA e ServiceNow exigem a configuração do conector deles. `MANUAL` confirma o despacho localmente sem chamar um sistema externo. Um conector ausente retorna `MTCH-0509`. Um despacho não confirmado retorna `MTCH-0514`, então verifique o destino antes de tentar de novo, porque um registro de destino pode já existir. Veja [Roteamento de exceções](/pt/products/matcher/configuration/matcher-exception-routing) para o contrato completo de despacho. Referência da API: * [Atribuir exceção](/pt/reference/products/matcher/assign-exception) * [Despachar exceção](/pt/reference/products/matcher/dispatch-exception) * [Resolver exceção](/pt/reference/products/matcher/resolve-exception) * [Correspondência forçada](/pt/reference/products/matcher/force-match-exception) * [Ajustar lançamento](/pt/reference/products/matcher/adjust-entry-exception) * [Obter histórico da exceção](/pt/reference/products/matcher/retrieve-exception-history) * [Selecionar IDs de exceção](/pt/reference/products/matcher/select-exception-ids) #### 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", "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. | 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 | 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 A severidade é reavaliada conforme a exceção envelhece. 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 abaixo de 1.000 começa como **Baixa**, mas escala para **Média** depois de 24 horas. * Uma exceção abaixo de 10.000 escala para **Alta** depois de 72 horas. * Qualquer exceção não resolvida escala para **Crítica** depois de 120 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 Vincule transações manualmente quando você confirmou que elas formam um par, mas o sistema não conseguiu fazer a correspondência. **Use a correspondência forçada quando:** * O correspondente correto existe, mas variações bloquearam a correspondência automática. * 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. 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. `POST /v1/matching/adjustments` aceita qualquer string de moeda não vazia e não valida se ela pertence à ISO 4217. * `reasonCode` deve usar `AMOUNT_CORRECTION`, `CURRENCY_CORRECTION`, `DATE_CORRECTION` ou `OTHER`. ## 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` | 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" }' ``` Referência da API: * [Atribuição em lote](/pt/reference/products/matcher/bulk-assign-exceptions) * [Resolução em lote](/pt/reference/products/matcher/bulk-resolve-exceptions) * [Despacho em lote](/pt/reference/products/matcher/bulk-dispatch-exceptions) ### 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 para um sistema externo: ```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": "WEBHOOK", "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` | — (retorna a thread completa, do mais antigo primeiro) | | Excluir comentário | `DELETE /v1/exceptions/{exceptionId}/comments/{commentId}` | `commentId` no caminho | Referência da API: * [Listar comentários](/pt/reference/products/matcher/list-exception-comments) * [Adicionar comentário](/pt/reference/products/matcher/add-exception-comment) * [Excluir comentário](/pt/reference/products/matcher/delete-exception-comment) ## 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. Referência da API: * [Listar disputas](/pt/reference/products/matcher/list-disputes) * [Obter disputa](/pt/reference/products/matcher/retrieve-dispute) * [Abrir disputa](/pt/reference/products/matcher/open-dispute) * [Fechar disputa](/pt/reference/products/matcher/close-dispute) ### Estados e transições de disputa Uma disputa tem cinco estados: `DRAFT`, `OPEN`, `PENDING_EVIDENCE`, `WON` e `LOST`. O fluxo **não** é estritamente linear: * `PENDING_EVIDENCE` é **opcional**. Uma disputa `OPEN` pode ir direto para `WON` ou `LOST` sem nunca coletar evidências. * Uma disputa `LOST` pode ser **reaberta** para `OPEN`. * `WON` é terminal. O conjunto completo de transições válidas: | Estado de origem | Próximos estados permitidos | Notas | | ------------------ | --------------------------------- | --------------------------------------------------------------- | | `DRAFT` | `OPEN` | A disputa é aberta para investigação | | `OPEN` | `PENDING_EVIDENCE`, `WON`, `LOST` | Pode resolver direto ou pedir evidências antes | | `PENDING_EVIDENCE` | `OPEN`, `WON`, `LOST` | Volta para `OPEN` ou resolve quando as evidências são revisadas | | `WON` | *(nenhum)* | Estado terminal | | `LOST` | `OPEN` | Uma disputa perdida pode ser reaberta | ## Workflow de resolução de exceções *** Use este fluxo para manter as revisões consistentes e auditáveis. Revise a fila por severidade e SLA. Comece pelas Críticas e Altas. Use o payload da exceção para entender o que falhou e quais candidatos existem. * Leia `reason_details` para ver por que a correspondência falhou. * Revise `candidates` em busca de correspondências próximas abaixo do limiar. * Procure padrões (mesma contraparte, formatos de referência recorrentes). 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ê encontrou o correspondente correto. * **Ajustar**: você precisa de um lançamento de ajuste para a variação. 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 Se a exceção exige tratamento externo, despache-a por um conector configurado. O despacho registra a ação, mas não muda o status da exceção. `WEBHOOK` exige uma URL fornecida pelo deploy. JIRA e ServiceNow exigem a configuração do conector deles. Se um conector retorna `MTCH-0514`, verifique o destino antes de tentar de novo, porque um registro de destino pode já existir. ## Boas práticas *** Comece pelos itens Críticos e Altos. Eles carregam o maior risco e os prazos mais apertados. 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 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 Se você usa correspondência forçada com frequência, as suas regras ou tolerâncias precisam de atenção. Atribua as exceções pelos endpoints de atribuição. O Matcher não aplica regras de atribuição automaticamente. ## Próximos passos *** Crie relatórios de conciliação, exporte resultados e apoie auditorias. Revise os conceitos de severidade, SLA e roteamento de exceções.