KYT: problemes habituals i solucions

A referència dels problemes habituals del Monitoratge de transaccions, amb símptoma, causa i solució.

​

Error de txn_id duplicat

Símptoma. En enviar una transacció es retorna 400 amb A transaction with this transaction_id already exists. al camp transaction_id, o 409 quan dues sol·licituds idèntiques competeixen entre si. Causa. txn_id (el transaction_id que envies) és únic per a cada aplicació. Didit rebutja una segona transacció amb el mateix transaction_id i no retorna el registre existent. Solució.

• Genera txn_id de manera determinista al teu costat (per exemple, usant l’ID de la teva base de dades de transaccions).
• Davant d’un 400 o 409 per un transaction_id duplicat durant un reintent, consulta la transacció existent en lloc de tornar-la a enviar: llegeix-la amb GET /v3/transactions/{uuid}/ usant l’uuid de la primera resposta, o usa el transaction_id (l’uuid de Didit) que el webhook transaction.created porta al costat del teu txn_id.
• Si la sol·licitud no era un reintent, assigna a la nova transacció el seu propi transaction_id.

​

La regla no s’activa

Símptoma. Has creat una regla que hauria de coincidir, però cap transacció apareix a rule_runs[] amb matched: true. Causes i solucions.

• L’aplicació està en mode sandbox: una aplicació sandbox omet l’avaluació de regles, el cribratge AML, la facturació i els webhooks transaction.created i transaction.status.updated. Els intercanvis de Travel Rule continuen executant-se quan estan habilitats, contra el Didit Test VASP, i envien webhooks travel_rule.status.updated marcats amb environment: sandbox. rule_runs torna buit i la puntuació es manté en 0, independentment del mode de les teves regles, i la transacció es manté en APPROVED tret que una transferència de Travel Rule que caduca apliqui el teu timeout_outcome. Comprova environment a la resposta de la transacció: "sandbox" vol dir que mai no s’ha avaluat. Consulta Monitoratge de transaccions en sandbox per saber com validar una regla abans de posar-la en producció.
• El mode de la regla és DISABLED o TEST: revisa Rules → [rule] → Mode. Només les regles ACTIVE contribueixen a la puntuació; les regles TEST s’avaluen però no afecten l’estat.
• El filtre d’àmbit exclou la transacció: per exemple, un àmbit establert a transaction_type = finance no coincidirà amb transaccions travelRule.
• La finestra d’agregació és més curta de la necessària: una regla de «20 transaccions en 30 dies» no coincidirà després de només 15 transaccions.
• El camp de la condició és nul: per exemple, la teva regla comprova counterparty.country_code però no has enviat cap contrapart.
• Conversió de moneda: la regla estableix els llindars sobre amount_in_default_currency; si la moneda per defecte de la teva aplicació és diferent de la de la transacció, l’import convertit pot quedar per sota del llindar.

Fes servir la funcionalitat Rules → [rule] → Backtest per reproduir una transacció passada i veure per què la regla s’ha activat o no.

​

La regla s’activa en tots els casos

Símptoma. Una regla s’activa en més del 90% de les transaccions: la teva cua de revisió està inundada. Causa. Les condicions són massa àmplies o els llindars són massa baixos. Solució.

• Afegeix filtres de scope per restringir l’aplicabilitat (per exemple, només transaccions sortints, o només certs tipus de transacció).
• Augmenta els llindars (imports, comptadors de velocitat).
• Posa la regla en mode TEST durant una setmana: analitza els rule_runs per veure la taxa de coincidència i ajusta les condicions abans de tornar-la a activar.

​

El cribratge de criptoactius ha exhaurit el temps d’espera

Símptoma. La transacció s’ha completat amb status: APPROVED, però la matriu provider_results[] mostra status: FAILED per a una cartera, un hash de transacció o un proveïdor de cribratge de criptoactius. Causes.

• L’API del proveïdor no ha estat disponible durant un moment.
• La consulta ha superat el temps d’espera (normalment ~10s).

Solució.

• Les transaccions mai fallen per problemes dels proveïdors: l’enriquiment es fa tan bé com sigui possible.
• Si un proveïdor específic falla repetidament, consulta la seva pàgina d’estat o obre un tiquet de suport.
• Considera configurar les preferències de proveïdors a Settings → Transaction Monitoring → Providers per encaminar les consultes a proveïdors alternatius.

​

Falta l’enriquiment de la IP

Símptoma. El applicant.ip_enrichment d’una transacció és absent o parcial. Causes.

• No hi ha applicant.device.ip a l’enviament.
• La IP és privada o reservada (no encaminable).
• Cap proveïdor d’enriquiment no ha estat disponible temporalment.

Solució.

• Captura la IP de qui envia la transacció al teu client o servidor i passa-la en cada transacció.
• Usa només IP encaminables: Didit omet silenciosament els rangs privats.
• Revisa Settings → Status a la consola per veure l’estat dels proveïdors.

​

La signatura del webhook no coincideix

Símptoma. El teu endpoint rebutja els esdeveniments perquè la signatura no coincideix. Causes.

• El cos brut de la sol·licitud s’ha modificat (el JSON s’ha tornat a serialitzar amb un espaiat diferent).
• El secret és incorrecte.
• Hi ha diverses destinacions amb la mateixa URL: les signatures són diferents per a cada destinació.

Solució.

• Signa sobre el cos brut de la sol·licitud, no sobre el JSON analitzat. Molts marcs de treball exposen un middleware per al cos en brut.
• Renova el secret si s’ha compromès: Webhook destinations → [destination] → Rotate secret.
• Mantén una sola destinació per URL per evitar confusions amb els secrets.

​

El webhook no arriba

Símptoma. Es creen transaccions però els webhooks no arriben mai. Causes.

• enabled de la destinació és false.
• La URL no és accessible públicament.
• La destinació s’ha desactivat automàticament després de fallades repetides.
• L’esdeveniment no és a subscribed_events.

Solució.

• Envia un esdeveniment de prova: Webhook destinations → [destination] → Send test.
• Revisa els lliuraments recents: Webhooks → [destination] → Deliveries. Consulta les respostes 4xx/5xx amb el cos i les capçaleres.
• Torna a activar les destinacions desactivades.

​

La conversió de moneda sembla incorrecta

Símptoma. amount_in_default_currency no coincideix amb el tipus de canvi que esperes. Causes.

• El tipus de canvi és el tipus de canvi mitjà de mercat a txn_date.
• Les transaccions amb data retroactiva fan servir el tipus històric d’aquella data.
• Algunes monedes (divises exòtiques) tenen intervals d’actualització més espaiats.

Solució.

• Usa amount i currency (la moneda original) per mostrar els imports.
• Usa amount_in_default_currency només per establir internament els llindars de les regles.
• Per a auditoria, el registre de la transacció fixa el tipus de conversió usat en el moment de l’avaluació.

​

Counterparty no coincideix amb la meva llista de bloqueig

Símptoma. Has posat a la llista de bloqueig una empresa pel seu vendor_data, però una transacció amb aquesta contrapart s’ha executat igualment. Causes.

• La contrapart del payload de la transacció no té vendor_data: es guarda com a instantània externa.
• El vendor_data té una capitalització diferent.

Solució.

• Passa sempre counterparty.vendor_data quan la contrapart sigui una entitat de la teva plataforma.
• Fes servir la mateixa capitalització a tot arreu: vendor_data distingeix majúscules i minúscules.

​

Transaccions AWAITING_USER bloquejades

Símptoma. Les transaccions es queden bloquejades a AWAITING_USER perquè l’usuari no completa mai la sessió de resolució. Causes.

• L’usuari no ha obert l’URL de la sessió de resolució.
• La sessió de resolució ha caducat.
• La transacció és una transferència subjecta a la Travel Rule que una regla de la biblioteca, com travel-rule-pending-action, ha mogut a AWAITING_USER: Didit no crea la seva sessió de resolució predeterminada per a una transacció de la Travel Rule, de manera que, tret que la regla indiqui el seu propi flux de treball de resolució, no hi ha cap enllaç per lliurar.

Solució.

• L’enllaç que s’ha de lliurar és el remediation_session_url de la resposta de la transacció. Torna a lliurar-lo a l’usuari.
• Per a una transacció de la Travel Rule, resol la transferència des de la pestanya Travel Rule i després canvia tu mateix l’estat de la transacció, perquè resoldre la transferència no fa que la transacció surti de AWAITING_USER per si sola.
• Les sessions de resolució segueixen el mateix patró de la guia d’inici ràpid de KYC: subscriu-te als webhooks de finalització.
• Estableix un temps límit al teu sistema per caducar les transaccions pendents si la resolució no es completa mai.

​

Límit de freqüència en la creació

Símptoma. 429 Too Many Requests durant ràfegues de gran volum. Solució.

• Respecta la capçalera Retry-After.
• Aplica una limitació de freqüència al client per al trànsit en ràfegues.
• Contacta amb el suport per obtenir límits més alts amb un volum de producció demostrat.

Consulta la limitació de freqüència.

​

Passos següents