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

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)

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

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

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

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:

cURL

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

cURL

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:

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

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

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

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.

Roteie trabalho automaticamente

Use regras de atribuição para reduzir o tempo de triagem e manter a propriedade clara.

Baixas contábeis são decisões de política

Se você faz baixa contábil frequentemente, revisite limites, escopo do contexto ou qualidade de dados upstream.

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. Forçar correspondência

2. Criar ajuste

3. Baixa contábil (write-off)

4. Dividir transação

Requisitos de auditoria

Documentação necessária por tipo 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. Forçar correspondência

​2. Criar ajuste

​3. Baixa contábil (write-off)

​4. Dividir transação

​Requisitos de auditoria

​Documentação necessária por tipo 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. Forçar correspondência

2. Criar ajuste

3. Baixa contábil (write-off)

4. Dividir transação

Requisitos de auditoria

Documentação necessária por tipo 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