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

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

> Coneix amb Didit tots els codis de risc de verificació de telèfon: HIGH_RISK_PHONE_NUMBER, VOIP_NUMBER_DETECTED, llista de bloqueig i límits d'OTP.

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](https://docs.didit.me/ca/reference/data-models.md#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](https://docs.didit.me/ca/management-api/lists/overview.md), 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`](#enviaments-bloquejats) 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](https://docs.didit.me/ca/management-api/lists/overview.md) 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](#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](https://docs.didit.me/ca/management-api/lists/overview.md), 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](https://docs.didit.me/ca/management-api/lists/overview.md), 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](https://docs.didit.me/ca/core-technology/phone-verification/report-phone-verification.md#coincidències-entre-sessions) 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`:

```json theme={null}
{
  "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](https://docs.didit.me/ca/core-technology/phone-verification/overview.md) — comportament de la funcionalitat, preus, canals admesos.
* [Informe de Verificació de telèfon](https://docs.didit.me/ca/core-technology/phone-verification/report-phone-verification.md) — estructura completa de la resposta, incloent-hi `lifecycle[]` i `matches[]`.
* [Models de dades — verificació de telèfon](https://docs.didit.me/ca/reference/data-models.md#verificació-de-telèfon) — esquema canònic camp per camp.
* [API de gestió — Llistes](https://docs.didit.me/ca/management-api/lists/overview.md) — gestiona la llista de bloqueig de telèfons que utilitza `PHONE_NUMBER_IN_BLOCKLIST`.


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