Resolução de exceções

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 — 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`	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 para o contrato completo de despacho.

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.

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

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:

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 para um sistema externo:

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

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

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

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ê encontrou o correspondente correto.
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 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

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

Matcher UI

Servidor MCP

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