Problemas comuns na monitorização de transações (KYT)

Uma referência dos problemas mais comuns da Monitorização de transações, com sintoma, causa e solução.

​

Erro de txn_id duplicado

Sintoma. Ao submeter uma transação, a resposta é 400 com A transaction with this transaction_id already exists. no campo transaction_id, ou 409 quando dois pedidos idênticos chegam em simultâneo. Causa. O txn_id (o transaction_id que envia) é único por aplicação. A Didit rejeita uma segunda transação com o mesmo transaction_id e não devolve o registo existente. Solução.

• Gere o txn_id de forma determinística do seu lado (por exemplo, use o ID da sua própria base de dados de transações).
• Em caso de 400 ou 409 por transaction_id duplicado durante uma nova tentativa, consulte a transação existente em vez de a reenviar: leia-a com GET /v3/transactions/{uuid}/ usando o uuid da primeira resposta, ou use o transaction_id (o uuid da Didit) que o webhook transaction.created traz junto do seu txn_id.
• Se o pedido não for uma nova tentativa, atribua à nova transação um transaction_id próprio.

​

A regra não dispara

Sintoma. Criou uma regra que deveria corresponder, mas nenhuma transação aparece em rule_runs[] com matched: true. Causas e soluções.

• A aplicação está em modo sandbox: uma aplicação sandbox não executa a avaliação de regras, a Triagem AML, a faturação nem os webhooks transaction.created e transaction.status.updated. As trocas da Travel Rule continuam a ser executadas quando estão ativadas, contra a Didit Test VASP, e enviam webhooks travel_rule.status.updated marcados com environment: sandbox. rule_runs volta vazio e a pontuação fica em 0, independentemente do modo das suas regras, e a transação permanece APPROVED, a menos que uma transferência Travel Rule com expiração aplique o seu timeout_outcome. Verifique environment na resposta da transação: "sandbox" significa que nunca foi avaliada. Consulte Monitorização de transações em sandbox para saber como validar uma regra antes de a colocar em produção.
• O modo da regra é DISABLED ou TEST: verifique em Rules → [rule] → Mode. Apenas as regras ACTIVE contribuem para a pontuação. As regras TEST são avaliadas, mas não afetam o estado.
• O filtro de âmbito exclui a transação: por exemplo, se o âmbito estiver definido como transaction_type = finance, não corresponde a transações travelRule.
• A janela de agregação é mais curta do que o necessário: uma regra de “20 transações em 30 dias” não dispara após apenas 15 transações.
• O campo da condição é nulo: por exemplo, a sua regra verifica counterparty.country_code, mas não enviou uma contraparte.
• Conversão de moeda: a regra aplica limites sobre amount_in_default_currency. Se a moeda predefinida da sua aplicação for diferente da moeda da transação, o montante convertido pode ficar abaixo do limite.

Use a funcionalidade Rules → [rule] → Backtest para reproduzir uma transação passada e ver por que é que a regra disparou ou não.

​

A regra dispara em tudo

Sintoma. Uma regra dispara em 90%+ das transações: a sua fila de revisão fica inundada. Causa. As condições são demasiado amplas ou os limiares são demasiado baixos. Solução.

• Adicione filtros de scope para restringir a aplicabilidade (por exemplo, apenas saídas ou apenas determinados tipos de transação).
• Aumente os limiares (montantes e contagens de transações).
• Coloque a regra em modo TEST durante uma semana: analise os rule_runs para ver a taxa de correspondência e restrinja as condições antes de a reativar.

​

Expirou o tempo limite da triagem de criptoativos

Sintoma. A transação foi concluída com status: APPROVED, mas o array provider_results[] mostra status: FAILED para uma carteira, um hash de transação ou um fornecedor de triagem de criptoativos. Causas.

• A API do fornecedor esteve brevemente indisponível.
• A consulta excedeu o tempo limite (normalmente ~10s).

Solução.

• As transações nunca falham por causa de problemas dos fornecedores: o enriquecimento é realizado tanto quanto possível.
• Se um fornecedor específico falhar repetidamente, consulte a respetiva página de estado ou abra um pedido de suporte.
• Considere configurar as preferências de fornecedores em Settings → Transaction Monitoring → Providers para encaminhar para fornecedores alternativos.

​

Enriquecimento de IP em falta

Sintoma. O applicant.ip_enrichment de uma transação está ausente ou incompleto. Causas.

• Não existe applicant.device.ip no envio.
• O IP é privado ou reservado (não é encaminhável na internet pública).
• Todos os fornecedores de enriquecimento estiveram temporariamente indisponíveis.

Solução.

• Capture o IP do utilizador que submete o pedido no seu cliente ou servidor e envie-o em todas as transações.
• Use apenas IPs públicos: a Didit ignora silenciosamente os intervalos privados.
• Verifique a saúde dos fornecedores em Settings → Status na consola.

​

A assinatura do webhook não corresponde

Sintoma. O seu endpoint rejeita os eventos porque a assinatura não corresponde. Causas.

• O corpo bruto foi alterado (JSON reserializado com espaços diferentes).
• Segredo errado.
• Vários destinos com o mesmo URL: as assinaturas diferem por destino.

Solução.

• Assine o corpo bruto do pedido, e não o JSON analisado. Muitas frameworks disponibilizam um middleware de corpo bruto.
• Renove o segredo se tiver sido comprometido: Webhook destinations → [destination] → Rotate secret.
• Mantenha um único destino por URL para evitar confusão com os segredos.

​

O webhook não chega

Sintoma. As transações são criadas, mas os webhooks nunca chegam. Causas.

• O enabled do destino está false.
• O URL não está acessível publicamente.
• O destino foi desativado automaticamente após falhas repetidas.
• O evento não está em subscribed_events.

Solução.

• Envie um evento de teste: Webhook destinations → [destination] → Send test.
• Verifique as entregas recentes: Webhooks → [destination] → Deliveries. Consulte as respostas 4xx/5xx, com o corpo e os cabeçalhos.
• Reative os destinos desativados.

​

A conversão de moeda parece incorreta

Sintoma. O amount_in_default_currency não corresponde à taxa que esperava. Causas.

• A taxa de câmbio é a taxa intermédia de mercado em txn_date.
• As transações retroativas usam a taxa histórica dessa data.
• Algumas moedas (câmbio de moedas exóticas) têm intervalos de atualização mais espaçados.

Solução.

• Use amount e currency (moeda original) para apresentação.
• Use amount_in_default_currency apenas para a aplicação de limiares de regras internas.
• Para auditoria, o registo da transação fixa a taxa de conversão usada no momento da avaliação.

​

A contraparte não corresponde à minha lista de bloqueio

Sintoma. Colocou na lista de bloqueio uma empresa pelo vendor_data, mas uma transação com essa contraparte foi, ainda assim, aceite. Causas.

• A contraparte no payload da transação não tem vendor_data — está guardada como snapshot externo.
• O vendor_data tem maiúsculas e minúsculas diferentes.

Correção.

• Passe sempre counterparty.vendor_data quando a contraparte for uma entidade na sua plataforma.
• Use as mesmas maiúsculas e minúsculas em todo o lado — vendor_data diferencia maiúsculas de minúsculas.

​

Transações em AWAITING_USER presas

Sintoma. As transações ficam presas em AWAITING_USER porque o utilizador nunca conclui a sessão de remediação. Causas.

• O utilizador não abriu o URL da sessão de remediação.
• A sessão de remediação expirou.
• A transação é uma transferência Travel Rule que uma regra da biblioteca, como travel-rule-pending-action, moveu para AWAITING_USER: a Didit não cria a sessão de remediação predefinida para uma transação Travel Rule, pelo que, a menos que a regra indique o seu próprio fluxo de remediação, não existe nenhuma ligação para enviar.

Correção.

• O remediation_session_url da resposta da transação é a ligação a enviar. Reenvie-a ao utilizador.
• Para uma transação Travel Rule, resolva a transferência no separador Travel Rule e, depois, altere manualmente o estado da transação, porque resolver a transferência não move, por si só, a transação para fora de AWAITING_USER.
• As sessões de remediação seguem o mesmo padrão do guia de início rápido do KYC — subscreva os webhooks de conclusão.
• Defina um tempo limite no seu sistema para expirar transações inativas caso a remediação nunca seja concluída.

​

Limite de pedidos ao criar

Sintoma. 429 Too Many Requests durante picos de volume elevado. Correção.

• Respeite o cabeçalho Retry-After.
• Limite a taxa de pedidos do lado do cliente em caso de tráfego em picos.
• Contacte o suporte para limites mais altos com base num volume de produção comprovado.

Consulte a limitação de pedidos.

​

Próximos passos