> ## 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. # Resolvendo 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 rastreáveis em auditoria. Exceções são transações que o Matcher não consegue reconciliar automaticamente. Este guia mostra como revisar exceções, priorizar o trabalho com base na severidade e resolver itens com o nível adequado de documentação. ## O que é uma exceção? *** Uma exceção é criada quando uma transação de uma fonte não possui uma contrapartida válida em outra fonte. Causas comuns incluem: * **Nenhum candidato encontrado**: Nenhuma transação na outra fonte atende aos critérios da regra ativa. * **Abaixo do limite de confiança**: Candidatos existem, mas pontuam abaixo da confiança mínima (padrão: 60). * **Rejeição por duplicidade**: Uma correspondência anterior foi rejeitada e nenhum candidato alternativo permanece. * **Desbalanceamento de fonte**: Uma fonte contém transações que estão ausentes na outra. ## Ciclo de vida da exceção *** Exceções passam por um fluxo de trabalho simples: * Quando o Matcher não consegue reconciliar uma transação, ele cria uma exceção com status `OPEN`. * A partir daí, a exceção é atribuída a um analista para investigação (`ASSIGNED`). * Se a resolução depende de um sistema externo — como um chamado JIRA despachado ou callback de webhook — a exceção passa para `PENDING_RESOLUTION` até que a resposta externa chegue. * Quando o analista resolve a exceção (forçar correspondência, ajuste ou callback externo), ela transiciona para `RESOLVED`. A resolução não depende do despacho: uma exceção pode passar para `RESOLVED` a partir de `OPEN`, `ASSIGNED` ou `PENDING_RESOLUTION`. Ciclo de vida da exceção do Matcher ### Definições de status | Status | Descrição | Quem Pode Transicionar | | -------------------- | ------------------------------------------------------- | ---------------------- | | `OPEN` | Nova exceção aguardando atribuição | Sistema | | `ASSIGNED` | Atribuída a um analista para investigação | Sistema, Analista | | `PENDING_RESOLUTION` | Aguardando resposta externa (JIRA, callback de webhook) | Sistema | | `RESOLVED` | Fechada com uma resolução auditável | Analista, Sistema | ### Endpoints da máquina de estados Os endpoints de exceção individual a seguir conduzem as transições no ciclo de vida acima. Cada um é endereçado pelo `exceptionId` da exceção no caminho. | Endpoint | Método e caminho | Finalidade | | | | ------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------- | | 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` | Despacha a exceção para um sistema externo de tickets (por exemplo, JIRA, ServiceNow). Corpo: `DispatchRequest`. Retorna um `DispatchResponse`. (`ASSIGNED` → `PENDING_RESOLUTION`) | | | | Resolver exceção | `POST /v1/exceptions/{exceptionId}/resolve` | Resolve uma única exceção. Corpo: `resolution` (obrigatório), `reason` (opcional). Espelha a validação de resolução em lote para uma exceção. (`OPEN` | `ASSIGNED` | `PENDING_RESOLUTION` → `RESOLVED`) | | 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). (resolve via ajuste) | | | | Histórico da exceção | `GET /v1/exceptions/{exceptionId}/history` | Retorna o histórico ordenado de transições de estado e ações da exceção (`HistoryResponse`). Suporta 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 correspondem aos filtros atuais (`contextId`, `status`, `severity`, `reason`, …). Use para conduzir uma seleção em lote antes de chamar os endpoints em lote. (somente leitura) | | | Referência da API: [Atribuir exceção](/pt/reference/matcher/assign-exception) | [Despachar exceção](/pt/reference/matcher/dispatch-exception) | [Resolver exceção](/pt/reference/matcher/resolve-exception) | [Ajustar lançamento](/pt/reference/matcher/adjust-entry-exception) | [Obter histórico da exceção](/pt/reference/matcher/retrieve-exception-history) | [Selecionar IDs de exceção](/pt/reference/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": "FEE_ADJUSTMENT", "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" ``` Alimente os IDs retornados nas [operações em lote](#operações-em-lote) abaixo. ## Severidade da exceção *** O Matcher classifica exceções por severidade para que você possa trabalhar na fila na ordem correta. | Severidade | Critérios | SLA | | ----------- | -------------------------------------- | ------------------ | | **Crítica** | Valor >= 100.000 OU idade >= 120 horas | 24 horas | | **Alta** | Valor >= 10.000 OU idade >= 72 horas | 72 horas | | **Média** | Valor >= 1.000 OU idade >= 24 horas | 120 horas (5 dias) | | **Baixa** | Todos os outros | 168 horas (7 dias) | ### Escalação de severidade A severidade é reavaliada conforme a exceção envelhece. A classificação usa lógica OU — o valor ou o tempo decorrido é suficiente para acionar uma severidade mais alta: * Uma exceção abaixo de 1.000 começa como **Baixa**, mas escala para **Média** após 24 horas. * Uma exceção abaixo de 10.000 escala para **Alta** após 72 horas. * Qualquer exceção não resolvida escala para **Crítica** após 120 horas. ## Métodos de resolução *** Você pode resolver uma exceção de quatro maneiras. ### 1. Forçar correspondência Vincule manualmente transações quando você confirmou que elas pertencem juntas, mas o sistema não conseguiu correspondê-las. **Use Forçar correspondência quando:** * A contrapartida correta existe, mas variações bloquearam a correspondência automática. * Você pode explicar e documentar claramente a justificativa. * A variação é esperada (taxas, timing, arredondamento). Forçar correspondência ignora a lógica de pontuação e de regras. Use apenas quando puder justificar a decisão por escrito. ### 2. Criar ajuste Crie um lançamento de ajuste para contabilizar uma variação ou equilibrar um item não correspondido. **Tipos comuns de ajuste:** | Tipo | Caso de Uso | | ------------------- | ---------------------------------------- | | `BANK_FEE` | Taxas bancárias não registradas no razão | | `FX_VARIANCE` | Diferenças de conversão de moeda | | `TIMING_DIFFERENCE` | Ajustes de timing de liquidação | | `ROUNDING` | Pequenas diferenças de arredondamento | | `CORRECTION` | Correções de erros | | `OTHER` | Outras variações documentadas | **Regras de validação:** * Valores de ajuste devem ser positivos. Uma requisição com valor zero ou negativo retorna um erro `400 Bad Request`. * Códigos de moeda devem seguir o formato ISO 4217. * Códigos de motivo devem usar um valor predefinido válido: `AMOUNT_CORRECTION`, `CURRENCY_CORRECTION`, `DATE_CORRECTION` ou `OTHER`. ### 3. Baixa contábil (write-off) Faça a baixa contábil de uma transação que não possui contrapartida válida. Isso deve ser raro e tipicamente requer aprovação. **Motivos de baixa contábil (write-off):** | Motivo | Descrição | | ------------------- | ------------------------------------------- | | `DUPLICATE_ENTRY` | Transação foi lançada duas vezes | | `CANCELLED` | Transação foi revertida ou cancelada | | `NOT_APPLICABLE` | Não pertence ao escopo desta reconciliação | | `BELOW_THRESHOLD` | Valor está abaixo do limite de investigação | | `APPROVED_VARIANCE` | Variação aprovada pela gerência | Baixas contábeis removem itens do resultado da sua reconciliação. Trate-as como uma decisão de política, não uma conveniência. ### 4. Dividir transação Use a divisão quando uma transação deve corresponder a múltiplas contrapartidas. ## Requisitos de auditoria *** Toda resolução cria um registro de auditoria. Alguns tipos de resolução requerem evidências e aprovações mais fortes. ### Documentação necessária por tipo de resolução | Resolução | Campos Necessários | Aprovação Necessária | | -------------------------- | ------------------------------------------ | ------------------------------ | | Forçar correspondência | `reason`, `notes` | Não (exceto se valor > limite) | | Ajuste | `adjustment_type`, `amount`, `description` | Se valor > \$1.000 | | Baixa contábil (write-off) | `reason`, `notes`, `reference_document` | Sempre | | Divisão | `splits[]` com valores e alvos | Nã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 múltiplas exceções a um membro da equipe 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 '{ "exception_ids": ["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/matcher/bulk-assign-exceptions) | [Resolução em lote](/pt/reference/matcher/bulk-resolve-exceptions) | [Despacho em lote](/pt/reference/matcher/bulk-dispatch-exceptions) ### Resolução em lote Resolva múltiplas 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 '{ "exception_ids": ["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`, para que você possa lidar com falhas parciais de forma elegante. ### Despacho em lote Despache múltiplas 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 '{ "exception_ids": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f"], "target_system": "JIRA", "queue": "RECON-TEAM" }' ``` ## Comentários de exceções *** Comentários dão a cada exceção uma trilha de auditoria com notas de investigação e discussão da equipe — algo inestimável quando outra pessoa precisa assumir ou revisar o caso mais tarde. Adicione um comentário conforme um 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 do mais recente para o mais antigo com paginação por `cursor`/`limit`, e um comentário pode ser removido pelo seu `commentId`. | 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` | `cursor`, `limit` (paginação) | | Excluir comentário | `DELETE /v1/exceptions/{exceptionId}/comments/{commentId}` | `commentId` no caminho | Referência da API: [Listar comentários](/pt/reference/matcher/list-exception-comments) | [Adicionar comentário](/pt/reference/matcher/add-exception-comment) | [Excluir comentário](/pt/reference/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**. Disputas rastreiam evidências, mudanças de estado e o resultado final. Liste disputas com `GET /v1/disputes` (filtre por `state`, por exemplo `OPEN`) ou recupere uma pelo seu `disputeId`. Referência da API: [Listar disputas](/pt/reference/matcher/list-disputes) | [Consultar disputa](/pt/reference/matcher/retrieve-dispute) | [Abrir disputa](/pt/reference/matcher/open-dispute) | [Fechar disputa](/pt/reference/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 diretamente para `WON` ou `LOST` sem nunca coletar evidências. * Uma disputa `LOST` pode ser **reaberta** de volta 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 diretamente ou solicitar evidências primeiro | | `PENDING_EVIDENCE` | `OPEN`, `WON`, `LOST` | Retorna para `OPEN` ou resolve assim que as evidências forem revisadas | | `WON` | *(nenhum)* | Estado terminal | | `LOST` | `OPEN` | Uma disputa perdida pode ser reaberta | ## Fluxo de trabalho de resolução de exceções *** Use este fluxo para manter revisões consistentes e amigáveis para auditoria. Revise a fila por severidade e SLA. Comece com Crítica e Alta. 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` para correspondências próximas abaixo do limite. * Procure por padrões (mesma contrapartida, formatos de referência recorrentes). Escolha a resolução que melhor reflete a realidade e a política. * **Forçar correspondência**: Você encontrou a contrapartida correta. * **Ajustar**: Você precisa de um lançamento de ajuste para variação. * **Dividir**: Uma transação mapeia para múltiplas contrapartidas. * **Baixa contábil (write-off)**: Nenhuma contrapartida existe e a política permite (aprovação necessária). Capture detalhes suficientes para que outra pessoa possa reproduzir sua decisão depois: * O que você verificou * O que você concluiu * Links ou IDs para evidências de suporte Se a exceção requer tratamento externo, despache-a para o JIRA ou um endpoint de webhook. A exceção passa para `PENDING_RESOLUTION` até que um callback confirme o resultado. ## Boas práticas *** Comece com itens Crítica e Alta. Eles carregam o maior risco e os prazos mais apertados. Notas não são opcionais. Trate-as como parte da resolução: * O que você verificou * Por que esta resolução está correta * Quaisquer IDs de tickets, extratos ou confirmações Exceções repetidas geralmente apontam para problemas de configuração: * Mesma contrapartida → Normalize nomes ou mapeamento * Mesma janela de datas → Valide completude da ingestão * Mesma fonte → Revise mapeamento de campos e convenções de sinal Se você força correspondências regularmente, suas regras ou tolerâncias precisam de atenção. Use regras de atribuição para reduzir o tempo de triagem e manter a propriedade clara. Se você faz baixa contábil frequentemente, revisite limites, escopo do contexto ou qualidade de dados upstream. ## Próximos passos *** Crie relatórios de reconciliação, exporte resultados e suporte auditorias. Configure regras de severidade, SLAs e atribuição automática.