> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Soluções para problemas comuns de KYT no Didit: colisões de txn_id, regras que não disparam, timeouts AML, assinaturas de webhook e moedas.

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}/`](https://docs.didit.me/pt/management-api/transactions/get) 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](https://docs.didit.me/pt/transaction-monitoring/travel-rule-sandbox.md), 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](https://docs.didit.me/pt/integration/sandbox-testing.md#monitorização-de-transações-no-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](https://docs.didit.me/pt/getting-started/quick-start.md) — 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](https://docs.didit.me/pt/integration/rate-limiting.md).

## Próximos passos

> [card] [Guia de integração](https://docs.didit.me/pt/transaction-monitoring/integration-guide.md)
>
> Padrões completos de integração.

> [card] [Regras](https://docs.didit.me/pt/transaction-monitoring/rules.md)
>
> Como funciona a avaliação de regras.

> [card] [Webhooks](https://docs.didit.me/pt/transaction-monitoring/webhooks.md)
>
> Funcionamento dos webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.