Resolvendo exceções

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 atribuição move a exceção de OPEN para ASSIGNED. A API não expõe uma operação para remover a atribuição; assignee é obrigatório e não pode estar vazio.
Forçar correspondência e ajustar lançamento mantêm PENDING_RESOLUTION somente enquanto a operação está em andamento. Em caso de sucesso, a exceção passa para RESOLVED; em caso de falha, retorna ao status anterior, OPEN ou ASSIGNED.
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 altera o status da exceção.

Ciclo de vida da exceção do Matcher — O ciclo de vida de uma exceção no 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`	Forçar correspondência ou ajustar lançamento está em andamento	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 alteram o ciclo de vida ou registram ações relacionadas. 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`	Envia a exceção pelo conector configurado. Grava um evento de auditoria `DISPATCH` e emite `exception.dispatched` sem alterar 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 de resolução em lote para uma exceção. (`OPEN` ou `ASSIGNED` → `RESOLVED`)
Forçar correspondência	`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 retorna 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 retorna ao status anterior em caso de falha.
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)

O Matcher oferece despacho por WEBHOOK, JIRA, SERVICENOW e MANUAL. WEBHOOK exige uma URL fornecida pelo deployment e, quando payloads assinados são obrigatórios, um segredo compartilhado. JIRA e ServiceNow exigem a configuração dos respectivos conectores. MANUAL confirma o despacho localmente sem chamar um sistema externo. Um conector não configurado retorna MTCH-0509; um despacho não confirmado retorna MTCH-0514, então verifique o destino antes de tentar novamente porque um registro pode já existir lá. Consulte Roteamento de exceções para o contrato completo de despacho.

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": "Variação dentro da tolerância" }'

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": "Correção da divergência na tarifa de processamento"
 }'

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"

Alimente os IDs retornados nas 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
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	Todos os outros

Esses limites repriorizam a exceção; eles não criam uma data de vencimento de SLA. Um callback recebido pode fornecer dueAt, e os agregados do dashboard medem a conformidade dessas datas de vencimento fornecidas externamente. Defina a política de tempo de resposta no sistema externo que envia o callback.

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

O Matcher expõe três ações para resolver exceções.

1. Resolver diretamente

Feche uma exceção com resolution obrigatório e reason opcional quando não for necessário forçar uma correspondência nem criar um ajuste.

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

3. Criar ajuste

Crie um lançamento de ajuste para contabilizar uma variação ou equilibrar um item não correspondido. Códigos de motivo do ajuste:

Código do 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 de efetivação
`OTHER`	Registrar outra correção documentada

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.
reasonCode deve usar AMOUNT_CORRECTION, CURRENCY_CORRECTION, DATE_CORRECTION ou OTHER.

Registros de resolução

O Matcher registra as ações de resolução aceitas no histórico da exceção e no fluxo de auditoria.

Resolução	Campos da requisição
Resolução direta	`resolution` (obrigatório), `reason` (opcional)
Forçar correspondência	`overrideReason`, `notes`
Ajustar lançamento	`reasonCode`, `amount`, `currency`, `effectiveAt`, `notes`

O Matcher não expõe contratos de resolução para dividir exceções nem para dar baixa de forma independente, e não impõe limites de aprovação baseados em valor para essas ações. Aplique requisitos adicionais 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 múltiplas exceções a um membro da equipe 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: Atribuição em lote | Resolução em lote | Despacho em lote

Resolução em lote

Resolva múltiplas 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": "Verificadas como tarifas bancárias válidas"
 }'

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:

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

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/comments" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "content": "Entrei em contato com o banco para verificar a tarifa da transferência. Aguardo a confirmação."
 }'

A listagem (GET) retorna a discussão completa ordenada do mais antigo para o mais recente. Você não pode adicionar comentários depois que uma exceção é resolvida. Somente o autor pode excluir o comentário, que 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 para o mais recente)
Excluir comentário	`DELETE /v1/exceptions/{exceptionId}/comments/{commentId}`	`commentId` no caminho

Referência da API: Listar comentários | Adicionar comentário | Excluir comentário

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 | Consultar disputa | Abrir disputa | Fechar disputa

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.

Triagem

Revise a fila por severidade e SLA. Comece com Crítica e Alta.

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 para correspondências próximas abaixo do limite.
Procure por padrões (mesma contrapartida, formatos de referência recorrentes).

Resolver

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

Resolver diretamente: Você pode encerrar a exceção sem forçar uma correspondência nem criar um ajuste.
Forçar correspondência: Você encontrou a contrapartida correta.
Ajustar: Você precisa de um lançamento de ajuste para variação.

Documentar

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

Despachar se necessário

Se a exceção exigir tratamento externo, despache-a por um conector configurado. O despacho registra a ação, mas não altera o status da exceção. WEBHOOK exige uma URL fornecida pelo deployment; JIRA e ServiceNow exigem a configuração dos respectivos conectores. Se um conector retornar MTCH-0514, verifique o destino antes de tentar novamente porque um registro pode já existir lá.

Boas práticas

Trabalhe por severidade e SLA

Comece com itens Crítica e Alta. Eles carregam o maior risco e os prazos mais apertados.

Torne as decisões auditáveis

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

Corrija padrões na origem

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

Trate forçar correspondências como exceções à regra

Se você força correspondências regularmente, 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

Resolvendo 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

Escalação de severidade

Métodos de resolução

1. Resolver diretamente

2. Forçar correspondência

3. Criar ajuste

Registros de resolução

Operações em lote

Atribuição em lote

Resolução em lote

Despacho em lote

Comentários de exceções

Disputas

Estados e transições de disputa

Fluxo de trabalho de resolução de exceções

Boas práticas

Próximos passos

Gerando 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

​Escalação de severidade

​Métodos de resolução

​1. Resolver diretamente

​2. Forçar correspondência

​3. Criar ajuste

​Registros de resolução

​Operações em lote

​Atribuição em lote

​Resolução em lote

​Despacho em lote

​Comentários de exceções

​Disputas

​Estados e transições de disputa

​Fluxo de trabalho de resolução de exceções

​Boas práticas

​Próximos passos

Gerando 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

Escalação de severidade

Métodos de resolução

1. Resolver diretamente

2. Forçar correspondência

3. Criar ajuste

Registros de resolução

Operações em lote

Atribuição em lote

Resolução em lote

Despacho em lote

Comentários de exceções

Disputas

Estados e transições de disputa

Fluxo de trabalho de resolução de exceções

Boas práticas

Próximos passos