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.

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

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
Critical	Valor >= 100.000 OU Idade >= 120 horas	24 horas
High	Valor >= 10.000 OU Idade >= 72 horas	72 horas
Medium	Valor >= 1.000 OU Idade >= 24 horas	120 horas (5 dias)
Low	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 Low, mas escala para Medium após 24 horas.
Uma exceção abaixo de 10.000 escala para High após 72 horas.
Qualquer exceção não resolvida escala para Critical 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

3. Write-off

Faça write-off de uma transação que não possui contrapartida válida. Isso deve ser raro e tipicamente requer aprovação. Motivos de 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 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
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 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 fornecem um registro de auditoria das discussões da equipe e notas de investigação sobre exceções.

Adicionar um comentário

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."
 }'

Listar comentários

cURL

curl -X GET "https://api.matcher.example.com/v1/exceptions/{exceptionId}/comments" \
 -H "Authorization: Bearer $TOKEN"

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

Disputas

Quando uma exceção requer investigação formal ou envolve uma parte externa, escale-a para uma disputa. Disputas rastreiam evidências, mudanças de estado e resultados de resolução.

Listar disputas

cURL

curl -X GET "https://api.matcher.example.com/v1/disputes?state=OPEN" \
 -H "Authorization: Bearer $TOKEN"

Consultar uma disputa

cURL

curl -X GET "https://api.matcher.example.com/v1/disputes/{disputeId}" \
 -H "Authorization: Bearer $TOKEN"

Referência API: Listar disputas | Consultar disputa | Abrir disputa | Fechar disputa

Estados de disputa: DRAFT → OPEN → PENDING_EVIDENCE → WON ou LOST.

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 Critical e High.

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

Melhores práticas

Trabalhe por severidade e SLA

Comece com itens Critical e High. 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.

Write-offs são decisões de política

Se você faz write-off frequentemente, revisite limites, escopo do contexto ou qualidade de dados upstream.

Introdução

Primeiros passos

Configurações

Reconciliação diária

Casos de uso do Matcher

Integrações

Referência

Resolvendo exceções

O que é uma exceção?

Ciclo de vida da exceção

Definições de status

Severidade da exceção

Escalação de severidade

Métodos de resolução

1. Forçar correspondência

2. Criar ajuste

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

Adicionar um comentário

Listar comentários

Disputas

Listar disputas

Consultar uma disputa

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

Melhores práticas

Próximos passos

Gerando Relatórios

Roteamento de Exceções

Introdução

Primeiros passos

Configurações

Reconciliação diária

Casos de uso do Matcher

Integrações

Referência

​O que é uma exceção?

​Ciclo de vida da exceção

​Definições de status

​Severidade da exceção

​Escalação de severidade

​Métodos de resolução

​1. Forçar correspondência

​2. Criar ajuste

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

​Adicionar um comentário

​Listar comentários

​Disputas

​Listar disputas

​Consultar uma disputa

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

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

Severidade da exceção

Escalação de severidade

Métodos de resolução

1. Forçar correspondência

2. Criar ajuste

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

Adicionar um comentário

Listar comentários

Disputas

Listar disputas

Consultar uma disputa

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

Melhores práticas

Próximos passos