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

# Vérification du téléphone : avertissements et risques

> Guide des codes de risque de vérification du téléphone Didit : numéros VoIP, jetables, à haut risque, liste de blocage et limites d'OTP.

La fonctionnalité Vérification du téléphone émet des **avertissements** dès qu'un signal de risque se déclenche sur le flux OTP ou sur le numéro lui-même : un numéro frauduleux connu, une ligne VoIP ou jetable, un dépassement de tentatives d'OTP ou une correspondance avec la session d'un autre utilisateur. Cette page répertorie chaque code, ce qui le déclenche et comment configurer la réponse du workflow.

## Vue d'ensemble

Les avertissements sont associés à la fonctionnalité `PHONE`. Ils apparaissent sous `phone_verifications[].warnings[]` dans `GET /v3/session/{sessionId}/decision/` et suivent la structure standard de l'[objet avertissement](https://docs.didit.me/fr/reference/data-models.md#objet-d’avertissement) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). Chaque avertissement est également acheminé dans le journal par session afin d'apparaître dans la Business Console sous la section Téléphone.

Certains avertissements constituent des déclencheurs de **refus automatique strict** — ils définissent systématiquement le statut de la fonctionnalité à `Declined`. D'autres correspondent à une **action configurable** (`DECLINE`, `REVIEW` ou `NO_ACTION`, selon le paramètre) définie dans les paramètres de votre workflow, de sorte qu'un même code de risque peut refuser un workflow tout en signalant simplement un autre.

## Conditions de refus automatique

Les avertissements suivants refusent systématiquement l'étape de vérification du téléphone quelle que soit la configuration, et comportent toujours `log_type: "error"` :

* `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` — l'utilisateur a atteint la limite de tentatives d'OTP : par défaut 2 saisies de code erronées (`phone_max_check_attempts`) ou plus de 2 envois d'OTP (`phone_max_retries`), tous deux configurables par nœud de workflow. L'API autonome de téléphone autorise 3 tentatives de code.
* `PHONE_NUMBER_IN_BLOCKLIST` — le numéro figure dans votre liste de blocage gérée via l'[API Lists](https://docs.didit.me/fr/management-api/lists/overview.md), ou il correspond à une session placée sur liste de blocage.

`HIGH_RISK_PHONE_NUMBER` — la couche antifraude du prestataire de livraison refusant d'envoyer l'OTP (envoi `Blocked`) — refuse par défaut mais n'est **plus inconditionnel** : voir [`high_risk_phone_action`](#envois-bloqués) ci-dessous.

## Risques configurables

Chacun des risques suivants correspond à un paramètre de workflow que vous pouvez configurer sur `DECLINE`, `REVIEW` ou `NO_ACTION` (la valeur par défaut — l'avertissement est consigné sans affecter le statut). L'action configurée définit également le `log_type` de l'avertissement : `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

| Paramètre | Code de risque | Se déclenche lorsque |
| - | - | - |
| `voip_number_action` | `VOIP_NUMBER_DETECTED` | Le type de ligne identifié par l'opérateur est `voip`, `isp` ou `vpn`. |
| `disposable_number_action` | `DISPOSABLE_NUMBER_DETECTED` | La recherche signale le numéro comme appartenant à un fournisseur de numéros temporaires / jetables. |
| `duplicated_phone_number_action` | `DUPLICATED_PHONE_NUMBER` | Le numéro correspond à une autre session, quel que soit son statut, appartenant à un utilisateur final différent. Ignoré lorsque le numéro figure sur liste d'autorisation. |

La détection de doublons s'exécute au sein de votre application sur l'ensemble des vérifications de téléphone KYC, KYB et via l'API autonome, et regroupe les sessions par `vendor_data` — les sessions partageant le même `vendor_data` sont traitées comme un seul et même utilisateur final et sont exclues des résultats de correspondance. Si vous laissez `vendor_data` vide, chaque session est traitée comme un utilisateur distinct.

### Envois bloqués

`HIGH_RISK_PHONE_NUMBER` suit le même modèle avec un ensemble de choix plus restreint, car un envoi refusé par le prestataire ne peut pas être approuvé :

| Paramètre | Code de risque | Se déclenche lorsque |
| - | - | - |
| `high_risk_phone_action` | `HIGH_RISK_PHONE_NUMBER` | La couche antifraude du prestataire de livraison a refusé d'envoyer l'OTP (envoi `Blocked`). Accepte uniquement `DECLINE` ou `REVIEW`, et utilise `DECLINE` par défaut. |

Le paramètre s'applique **uniquement lorsque chaque blocage à haut risque de l'étape comporte des `additional_data.risk_factors` valant exactement `["device_attribute"]`** — le signal du prestataire indiquant « cet appareil semble suspect », qui est celui qui se déclenche sur les lignes mobiles ordinaires. Tout autre facteur de risque, toute combinaison incluant simplement `device_attribute`, ou un blocage sans aucun facteur de risque entraîne un refus indépendamment du paramètre. La raison du blocage (`repeated_attempts`, `suspicious` ou `spam`) est un champ distinct, renvoyé dans `additional_data.blocked_reason`.

Indépendamment du paramètre, un numéro figurant sur une liste d'autorisation de téléphones créée via l'[API Lists](https://docs.didit.me/fr/management-api/lists/overview.md) n'est jamais automatiquement refusé lors d'un envoi bloqué : l'étape passe à **En cours d'examen**, l'avertissement porte `log_type: "warning"` et `additional_data.phone_number_in_allowlist` est `true`.

## Limites des tentatives de vérification

La fonctionnalité Vérification du téléphone applique un plafond strict sur les tentatives d'OTP afin de prévenir les abus :

* **Tentatives de saisie du code** — Par défaut **2** soumissions incorrectes (`phone_max_check_attempts`) avant que l'étape ne se termine par `Declined` avec `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`. L'API autonome de téléphone autorise **3** tentatives de code par vérification.
* **Tentatives d'envoi** — Par défaut **2** envois au total (`phone_max_retries`) : l'envoi initial plus un renvoi. Une requête d'envoi supplémentaire finalise l'étape et déclenche `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`.
* **Validité de l'OTP** — Un OTP en attente est valide pendant **5 minutes à compter du premier envoi** ; les réessais ne prolongent pas cette fenêtre.

Les deux plafonds sont configurables par nœud de workflow. Indépendamment de ces plafonds, la couche antifraude du fournisseur de livraison peut bloquer directement un envoi (motif `repeated_attempts`, `suspicious` ou `spam`) — cela déclenche `HIGH_RISK_PHONE_NUMBER`, et non l'avertissement relatif aux tentatives.

## Avertissements émis

| Tag | `log_type` | Description |
| - | - | - |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `error` (toujours) | L'utilisateur a dépassé le plafond de saisie du code OTP ou d'envoi. Refus automatique. |
| `HIGH_RISK_PHONE_NUMBER` | Suit `high_risk_phone_action`, ou `warning` si sur liste blanche | Le fournisseur de livraison a bloqué l'envoi de l'OTP. Refusé par défaut ; définissez `high_risk_phone_action` sur `REVIEW` pour router plutôt un blocage uniquement basé sur les signaux de l'appareil vers l'état « en cours d'examen » (voir [Envois bloqués](#envois-bloqués)). Un numéro sur une liste blanche de téléphones passe également à l'état « en cours d'examen ». `additional_data` : `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`. |
| `PHONE_NUMBER_IN_BLOCKLIST` | `error` (toujours) | Le numéro figure dans une liste de blocage créée via l'[API des listes](https://docs.didit.me/fr/management-api/lists/overview.md), ou correspond à une session inscrite sur liste de blocage. Refus automatique. `additional_data` : `{ blocklisted_session_id, blocklisted_session_number, api_service }` (tous `null` pour une correspondance directe sur liste). |
| `PHONE_NUMBER_IN_ALLOWLIST` | `information` | Le numéro correspond à d'autres sessions mais figure dans une liste blanche créée via l'[API des listes](https://docs.didit.me/fr/management-api/lists/overview.md), de sorte que les actions pour numéro en double sont ignorées. `additional_data` : `{ phone_number }`. |
| `DISPOSABLE_NUMBER_DETECTED` | Suit `disposable_number_action` | Le numéro provient d'un fournisseur temporaire / jetable souvent utilisé pour échapper à la traçabilité. |
| `VOIP_NUMBER_DETECTED` | Suit `voip_number_action` | Le numéro correspond à une ligne `voip`, `isp` ou `vpn` plutôt qu'à une ligne mobile ou fixe standard. |
| `DUPLICATED_PHONE_NUMBER` | Suit `duplicated_phone_number_action` | Le numéro correspond à une autre session — quel que soit son statut — appartenant à un utilisateur final différent (groupé par `vendor_data`). `additional_data` : `{ duplicated_session_id, duplicated_session_number, api_service }`. |

## Correspondances entre sessions

Lorsqu'un numéro est détecté sur d'autres sessions ou sur votre liste de blocage, ces correspondances apparaissent également sous `phone_verifications[].matches[]` (limité à 5 entrées). Chaque correspondance comporte `session_id`, `session_number`, `vendor_data`, `verification_date`, `phone_number`, `status`, `is_blocklisted`, `api_service`, ainsi qu'une `source` valant `session` (une autre session avec le même numéro, quel que soit son statut) ou `list_entry` (une correspondance synthétique de liste de blocage insérée en tête du tableau). Si le numéro actuel est sur votre liste blanche de téléphones, Didit conserve les éléments de correspondance mais émet `PHONE_NUMBER_IN_ALLOWLIST` au lieu d'appliquer l'action pour numéro de téléphone en double. Consultez le [rapport de vérification du téléphone](https://docs.didit.me/fr/core-technology/phone-verification/report-phone-verification.md#correspondances-inter-sessions) pour obtenir le schéma complet des correspondances.

## Exemple

Un envoi bloqué (`HIGH_RISK_PHONE_NUMBER`) sur un numéro VoIP, avec `voip_number_action` configuré sur `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"
    }
  ]
}
```

## Types d'avertissements

Chaque risque se voit attribuer une sévérité basée sur la configuration de votre application. Les sévérités se répartissent en trois catégories :

## Liens associés

* [Vue d'ensemble de la vérification du téléphone](https://docs.didit.me/fr/core-technology/phone-verification/overview.md) — comportement de la fonctionnalité, tarifs, canaux pris en charge.
* [Rapport de vérification du téléphone](https://docs.didit.me/fr/core-technology/phone-verification/report-phone-verification.md) — structure complète de la réponse, incluant `lifecycle[]` et `matches[]`.
* [Modèles de données — vérification du téléphone](https://docs.didit.me/fr/reference/data-models.md#vérification-du-téléphone) — schéma de référence champ par champ.
* [API de gestion — Listes](https://docs.didit.me/fr/management-api/lists/overview.md) — gérer la liste de blocage des téléphones utilisée par `PHONE_NUMBER_IN_BLOCKLIST`.


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