Resolução de exceções

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. 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.
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 — 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`)
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). 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)

O despacho MANUAL confirma a entrega localmente sem chamar um sistema externo.

Referência da API:

Exemplo de atribuição

cURL

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

cURL

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

cURL

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`

cURL

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

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

cURL

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:

Resolução em lote

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

cURL

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:

cURL

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:

cURL

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

Referência da API:

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:

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.

Triagem

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

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.
Procure padrões (mesma contraparte, formatos de referência recorrentes).

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.

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

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

Trabalhe por severidade e SLA

Comece pelos itens Críticos e Altos. Eles carregam o maior risco e os prazos mais apertados.

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

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

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.

Atribua o trabalho explicitamente

Atribua as exceções pelos endpoints de atribuição. O Matcher não aplica regras de atribuição automaticamente.

Visão geral

Guias

Console

Operações

Resolução de exceções

O que é uma exceção?

Ciclo de vida da exceção

Definições de status

Endpoints da máquina de estados

Exemplo de atribuição

Exemplo de resolução

Exemplo de ajuste de lançamento

Seleção em lote com `selectExceptionIDs`

Severidade da exceção

Escalonamento de severidade

Métodos de resolução

1. Resolver diretamente

2. Correspondência forçada

3. Criar ajuste

Registros de resolução

Operações em lote

Atribuição em lote

Resolução em lote

Despacho em lote

Comentários da exceção

Disputas

Estados e transições de disputa

Workflow de resolução de exceções

Boas práticas

Próximos passos

Geração de relatórios

Roteamento de exceções

​O que é uma exceção?

​Ciclo de vida da exceção

​Definições de status

​Endpoints da máquina de estados

​Exemplo de atribuição

​Exemplo de resolução

​Exemplo de ajuste de lançamento

​Seleção em lote com selectExceptionIDs

​Severidade da exceção

​Escalonamento de severidade

​Métodos de resolução

​1. Resolver diretamente

​2. Correspondência forçada

​3. Criar ajuste

​Registros de resolução

​Operações em lote

​Atribuição em lote

​Resolução em lote

​Despacho em lote

​Comentários da exceção

​Disputas

​Estados e transições de disputa

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

​Boas práticas

​Próximos passos

Geração de relatórios

Roteamento de exceções

O que é uma exceção?

Ciclo de vida da exceção

Definições de status

Endpoints da máquina de estados

Exemplo de atribuição

Exemplo de resolução

Exemplo de ajuste de lançamento

Seleção em lote com `selectExceptionIDs`

Severidade da exceção

Escalonamento de severidade

Métodos de resolução

1. Resolver diretamente

2. Correspondência forçada

3. Criar ajuste

Registros de resolução

Operações em lote

Atribuição em lote

Resolução em lote

Despacho em lote

Comentários da exceção

Disputas

Estados e transições de disputa

Workflow de resolução de exceções

Boas práticas

Próximos passos