Advertències i codis de risc de la verificació de telèfon

La funcionalitat de Verificació de telèfon emet advertències quan s’activa un senyal de risc en el flux d’OTP o en el mateix número: un número problemàtic conegut, una línia VoIP o d’un sol ús, un límit d’intents d’OTP o una coincidència amb la sessió d’un altre usuari. Aquesta pàgina enumera tots els codis, què els activa i com configurar la resposta del flux de treball.

Visió general

Les advertències estan etiquetades amb la funcionalitat PHONE. Apareixen a phone_verifications[].warnings[] a GET /v3/session/{sessionId}/decision/ i segueixen l’estructura estàndard de l’objecte d’advertència (feature, risk, additional_data, log_type, short_description, long_description, node_id). Cada advertència també s’encamina al registre per sessió perquè es mostri a la Business Console a la secció de Telèfon. Algunes advertències són activadors de rebuig automàtic estricte: sempre estableixen l’estat de la funcionalitat a Declined. D’altres s’associen a una acció configurable (DECLINE, REVIEW o NO_ACTION, segons la configuració) definida a la configuració del teu flux de treball, de manera que el mateix codi de risc pot rebutjar un flux de treball mentre que en un altre només genera una advertència.

Condicions de rebuig automàtic

Les advertències següents sempre rebutgen el pas de Verificació de telèfon independentment de la configuració, i sempre porten log_type: "error":

VERIFICATION_CODE_ATTEMPTS_EXCEEDED — l’usuari ha esgotat el límit d’intents d’OTP: per defecte 2 intents de presentar un codi incorrecte (phone_max_check_attempts) o més de 2 enviaments d’OTP (phone_max_retries), tots dos configurables per node del flux de treball. L’API de telèfon independent permet 3 intents de codi.
PHONE_NUMBER_IN_BLOCKLIST — el número és a la teva llista de bloqueig gestionada mitjançant la Lists API, o coincideix amb una sessió inclosa a la llista de bloqueig.

HIGH_RISK_PHONE_NUMBER — la capa antifrau del proveïdor de lliurament es nega a enviar l’OTP (enviament Blocked) — es rebutja per defecte, però ja no és incondicional: consulta high_risk_phone_action més avall.

Riscos configurables

Cada un dels riscos següents s’associa a una configuració del flux de treball que pots configurar a DECLINE, REVIEW o NO_ACTION (el valor per defecte; l’advertència es registra sense afectar l’estat). L’acció configurada també defineix el log_type de l’advertència: DECLINE → error, REVIEW → warning, NO_ACTION → information.

Configuració	Codi de risc	S’activa quan
`voip_number_action`	`VOIP_NUMBER_DETECTED`	L’operador classifica el número com una línia de tipus `voip`, `isp` o `vpn`.
`disposable_number_action`	`DISPOSABLE_NUMBER_DETECTED`	La cerca marca el número com a proveïdor temporal o d’un sol ús.
`duplicated_phone_number_action`	`DUPLICATED_PHONE_NUMBER`	El número coincideix amb una altra sessió de qualsevol estat que pertany a un usuari final diferent. S’omet quan el número és a la llista d’admesos.

La detecció de duplicats s’executa dins de la teva aplicació a través de verificacions de telèfon de KYC, KYB i de l’API independent, i agrupa les sessions per vendor_data: les sessions que comparteixen el mateix vendor_data es tracten com un únic usuari final i s’exclouen dels resultats de coincidència. Si deixes vendor_data buit, cada sessió es tracta com un usuari diferent.

Enviaments bloquejats

HIGH_RISK_PHONE_NUMBER segueix el mateix patró amb un conjunt d’opcions més reduït, ja que un enviament que el proveïdor ha rebutjat no es pot aprovar:

Configuració	Codi de risc	S’activa quan
`high_risk_phone_action`	`HIGH_RISK_PHONE_NUMBER`	La capa antifrau del proveïdor de lliurament s’ha negat a enviar l’OTP (enviament `Blocked`). Només accepta `DECLINE` o `REVIEW`, i el valor per defecte és `DECLINE`.

Aquesta configuració s’aplica només quan cada bloqueig d’alt risc del pas porta additional_data.risk_factors amb el valor exacte ["device_attribute"]; el senyal del proveïdor de “aquest dispositiu sembla sospitós”, que és el que s’activa en línies mòbils ordinàries. Qualsevol altre factor de risc, qualsevol combinació que inclogui device_attribute juntament amb altres factors de risc o un bloqueig sense cap factor de risc es rebutja independentment de la configuració. El motiu del bloqueig (repeated_attempts, suspicious o spam) és un camp independent, retornat a additional_data.blocked_reason. Independentment de la configuració, un número que es trobi en una llista d’admesos de telèfons creada mitjançant la Lists API mai no es rebutja automàticament per un enviament bloquejat: el pas passa a En revisió, l’advertència porta log_type: "warning" i additional_data.phone_number_in_allowlist és true.

Límits d’intents de verificació

La funcionalitat de Verificació de telèfon aplica un límit estricte als intents d’OTP per evitar abusos:

Intents d’introducció del codi — Per defecte, 2 intents d’introducció incorrectes (phone_max_check_attempts) abans que el pas finalitzi com a Declined amb VERIFICATION_CODE_ATTEMPTS_EXCEEDED. L’API de telèfon independent permet 3 intents de codi per verificació.
Intents d’enviament — Per defecte, 2 enviaments en total (phone_max_retries): l’enviament inicial més un reenviament. Una sol·licitud d’enviament addicional finalitza el pas i genera VERIFICATION_CODE_ATTEMPTS_EXCEEDED.
Validesa de l’OTP — Un OTP pendent és vàlid durant 5 minuts des del primer enviament; els reintents no amplien aquest termini.

Tots dos límits es poden configurar per node del flux de treball. Independentment d’aquests límits, la capa antifrau del proveïdor de lliurament pot bloquejar un enviament directament (motiu repeated_attempts, suspicious o spam), la qual cosa genera HIGH_RISK_PHONE_NUMBER en lloc de l’advertència d’intents.

Advertències generades

Etiqueta	`log_type`	Descripció
`VERIFICATION_CODE_ATTEMPTS_EXCEEDED`	`error` (sempre)	L’usuari ha superat el límit d’introducció del codi OTP o d’enviament. Es rebutja automàticament.
`HIGH_RISK_PHONE_NUMBER`	Segueix `high_risk_phone_action`, o `warning` si està a la llista d’admesos	El proveïdor de lliurament ha bloquejat l’enviament de l’OTP. Es rebutja per defecte; defineix `high_risk_phone_action` com a `REVIEW` per desviar a en revisió un bloqueig basat només en senyals del dispositiu (consulta Enviaments bloquejats). Un número en una llista d’admesos de telèfons també passa a en revisió. `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`.
`PHONE_NUMBER_IN_BLOCKLIST`	`error` (sempre)	El número es troba en una llista de bloqueig creada mitjançant l’API de llistes, o coincideix amb una sessió a la llista de bloqueig. Es rebutja automàticament. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (tots `null` en cas de coincidència exclusiva amb la llista).
`PHONE_NUMBER_IN_ALLOWLIST`	`information`	El número ha coincidit amb altres sessions però es troba en una llista d’admesos creada mitjançant l’API de llistes, de manera que s’ometen les accions per a números de telèfon duplicats. `additional_data`: `{ phone_number }`.
`DISPOSABLE_NUMBER_DETECTED`	Segueix `disposable_number_action`	El número pertany a un proveïdor temporal o d’un sol ús que s’utilitza sovint per eludir la traçabilitat.
`VOIP_NUMBER_DETECTED`	Segueix `voip_number_action`	El número correspon a una línia `voip`, `isp` o `vpn` en lloc d’una línia mòbil o fixa estàndard.
`DUPLICATED_PHONE_NUMBER`	Segueix `duplicated_phone_number_action`	El número coincideix amb una altra sessió —amb qualsevol estat— que pertany a un usuari final diferent (amb l’agrupació feta per `vendor_data`). `additional_data`: `{ duplicated_session_id, duplicated_session_number, api_service }`.

Coincidències entre sessions

Quan es detecta un número en altres sessions o a la teva llista de bloqueig, aquestes coincidències també apareixen sota phone_verifications[].matches[] (limitat a 5 entrades). Cada coincidència inclou session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service i un camp source amb el valor session (una altra sessió amb el mateix número, amb qualsevol estat) o list_entry (una coincidència sintètica de la llista de bloqueig afegida a l’inici de la matriu). Si el número actual es troba a la teva llista d’admesos de telèfons, Didit conserva les proves de la coincidència però emet PHONE_NUMBER_IN_ALLOWLIST en lloc d’aplicar l’acció per a números de telèfon duplicats. Consulta l’informe de Verificació de telèfon per veure l’esquema complet de coincidències.

Exemple

Un enviament bloquejat (HIGH_RISK_PHONE_NUMBER) en un número VoIP, amb voip_number_action configurat a REVIEW:

{
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "HIGH_RISK_PHONE_NUMBER",
      "additional_data": { "blocked_reason": "suspicious" },
      "log_type": "error",
      "short_description": "High risk phone number",
      "long_description": "The system detected that the phone number is a high risk phone number, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ]
}

Tipus d’advertències

A cada risc se li assigna una gravetat basada en la configuració de la teva aplicació. Les gravetats es divideixen en tres categories:

Relacionat

Visió general de la Verificació de telèfon — comportament de la funcionalitat, preus, canals admesos.
Informe de Verificació de telèfon — estructura completa de la resposta, incloent-hi lifecycle[] i matches[].
Models de dades — verificació de telèfon — esquema canònic camp per camp.
API de gestió — Llistes — gestiona la llista de bloqueig de telèfons que utilitza PHONE_NUMBER_IN_BLOCKLIST.

Autenticació

Verificació

Monitoratge

Plataforma

Advertències i codis de risc de la verificació de telèfon

Visió general

Condicions de rebuig automàtic

Riscos configurables

Enviaments bloquejats

Límits d’intents de verificació

Advertències generades

Coincidències entre sessions

Exemple

Tipus d’advertències

Relacionat

​Visió general

​Condicions de rebuig automàtic

​Riscos configurables

​Enviaments bloquejats

​Límits d’intents de verificació

​Advertències generades

​Coincidències entre sessions

​Exemple

​Tipus d’advertències

​Relacionat

Visió general

Condicions de rebuig automàtic

Riscos configurables

Enviaments bloquejats

Límits d’intents de verificació

Advertències generades

Coincidències entre sessions

Exemple

Tipus d’advertències

Relacionat