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

# Informe de verificació de telèfon: JSON d'OTP i operador

> Analitza les respostes de verificació de telèfon a Didit: dades d'operador, tipus de línia i OTP. Pagament per OTP des de $0.02 + tarifes d'operador.

L'informe de Verificació de telèfon recull el resultat complet d'un desafiament OTP telefònic: a qui hem enviat el codi, quin operador i canal l'han gestionat, quants intents han calgut, si el número és d'un sol ús o VoIP, i qualsevol coincidència entre sessions amb la teva llista de bloqueig o amb les sessions d'altres usuaris.

Aquesta pàgina documenta l'estructura JSON que retorna l'endpoint de decisió perquè puguis analitzar els resultats de l'OTP, les metadades de l'operador i els indicadors de risc de cada número verificat.

![Informe de verificació de telèfon de Didit que mostra el resultat de l'OTP, les metadades de l'operador i els indicadors de risc](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/phone-verification-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=9b5c6c6112303ebc60c0f287aafdb996)

## Visió general

Es genera un informe de telèfon cada vegada que un node del flux de treball executa la funcionalitat de Verificació de telèfon. Cada informe representa un desafiament OTP per a un número de telèfon i conté:

* El número de telèfon desglossat en prefix, número nacional i format E.164 complet, a més del codi de país ISO i el nom del país.
* Metadades de l'operador (`name`, `type`) obtingudes a partir de la xarxa de destinació.
* Indicadors booleans de risc (`is_disposable`, `is_virtual`) derivats de l'anàlisi del tipus de línia.
* El canal de lliurament real utilitzat (`verification_method`) i el nombre d'intents d'enviament de l'OTP.
* Un registre cronològic `lifecycle[]` de cada enviament, reintent, esdeveniment de lliurament i intent de comprovació del codi.
* Una matriu `matches[]` que mostra el mateix número en altres sessions —de qualsevol estat, tant en verificacions KYC i KYB com en verificacions independents mitjançant l'API— o a la teva llista de bloqueig.
* Una matriu `warnings[]`: esdeveniments de risc emesos durant la verificació (consulta [Advertències de Verificació de telèfon](https://docs.didit.me/ca/core-technology/phone-verification/warnings-phone-verification.md)).
* Un `node_id` que identifica quin node del graf del flux de treball ha generat l'informe (només sessions V3).

En els fluxos de verificació allotjats, Didit gestiona l'intercanvi d'OTP per tu. Per a les integracions directes de l'API, el mateix flux consisteix en dues crides: [`POST /v3/phone/send/`](https://docs.didit.me/ca/standalone-apis/phone-send) per lliurar el codi i [`POST /v3/phone/check/`](https://docs.didit.me/ca/standalone-apis/phone-check) per validar l'entrada de l'usuari. Un OTP pendent és vàlid durant **5 minuts des del primer enviament** (els reintents no amplien aquest període). En les sessions de flux de treball, els usuaris tenen per defecte 2 intents d'enviament d'OTP (`phone_max_retries`) i 2 intents d'introducció del codi (`phone_max_check_attempts`), ambdós configurables per node del flux de treball; esgotar qualsevol d'aquests límits finalitza el pas com a `Declined` amb `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`. L'API de telèfon independent permet 3 intents d'introducció del codi per verificació.

## On apareix a les respostes de l'API

L'endpoint de decisió (`GET /v3/session/{sessionId}/decision/`) retorna els informes de telèfon sota la clau d'array en plural **`phone_verifications`**. L'array conté una entrada per cada node de Verificació de telèfon al graf del flux de treball —normalment una, però els fluxos d'escalada en poden generar diverses.

```json theme={null}
{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "phone_verifications": [
    { "status": "Approved", "node_id": "feature_phone_1", "...": "..." }
  ]
}
```

Un valor `null` significa que encara no s'ha executat cap pas de Verificació de telèfon. Itera sobre l'array (en lloc de llegir directament `phone_verifications[0]`) quan el teu flux de treball pugui recollir més d'un número de telèfon.

## Esquema

L'esquema canònic camp per camp es troba a la pàgina [Models de dades](https://docs.didit.me/ca/reference/data-models.md#verificació-de-telèfon).

```typescript theme={null}
interface PhoneVerification {
  status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired";
  phone_number_prefix: string;       // E.g. "+34"
  phone_number: string;              // National number, no prefix
  full_number: string;               // Full E.164, e.g. "+34600600600"
  country_code: string;              // ISO 3166-1 alpha-2, e.g. "ES"
  country_name: string;
  carrier: {
    name: string;
    type:                              // From LineTypeChoices
      | "mobile" | "fixed_line" | "voip" | "isp" | "vpn"
      | "toll_free" | "premium_rate" | "shared_cost" | "local_rate"
      | "satellite" | "pager" | "payphone" | "voice_mail"
      | "calling_cards" | "service" | "short_codes_commercial"
      | "universal_access" | "other" | "unknown";
  };
  is_disposable: boolean;            // Temporary / burner number
  is_virtual: boolean;               // true when carrier.type is voip, isp or vpn
  verification_method:               // Actual channel that delivered the OTP
    | "sms" | "whatsapp" | "telegram" | "voice" | "rcs" | "viber" | "zalo";
  verification_attempts: number;     // OTP send attempts (initial send + resends)
  verified_at: string | null;        // ISO 8601, set when a valid OTP was entered
  warnings: Warning[];               // Risk events emitted during verification
  lifecycle: PhoneLifecycleEvent[];  // OTP send/retry/delivery/check timeline
  matches: PhoneMatch[];             // Cross-session / blocklist matches (max 5)
  node_id: string;                   // Workflow graph node that produced this report
}
```

### Valors d'estat

| Estat | Significat |
| - | - |
| `Not Finished` | S'ha iniciat l'enviament de l'OTP però la verificació encara no s'ha finalitzat. |
| `Approved` | L'usuari ha introduït un OTP vàlid i no s'ha activat cap risc que impliqui rebuig. |
| `Declined` | S'ha disparat una advertència de rebuig automàtic (llista de bloqueig, alt risc, intents superats) o ha coincidit una acció de risc configurada com a `DECLINE`. |
| `In Review` | Una acció de risc configurada com a `REVIEW` ha derivat el pas a revisió manual. |
| `Expired` | La finestra de 5 minuts de l'OTP ha vençut sense cap codi vàlid — s'aplica a verificacions creades mitjançant l'API de telèfon independent. |

### Tipus d'esdeveniments del cicle de vida

`lifecycle[]` està ordenat cronològicament. Cada esdeveniment té `type`, `timestamp`, `details` i una tarifa (`fee`) facturable (quan correspongui):

| Tipus d'esdeveniment | S'emet quan |
| - | - |
| `PHONE_VERIFICATION_MESSAGE_SENT` | Primer intent d'enviament de l'OTP pel canal sol·licitat. |
| `PHONE_VERIFICATION_RETRY_MESSAGE_SENT` | Enviament posterior de l'OTP després que l'usuari hagi demanat un reenviament. |
| `PHONE_VERIFICATION_BLOCKED` | L'enviament s'ha bloquejat (correu brossa, activitat sospitosa, intents repetits, número no vàlid). |
| `PHONE_DELIVERY_DELIVERED` | L'operador ha confirmat el lliurament al canal realment utilitzat. |
| `PHONE_DELIVERY_UNDELIVERABLE` | L'operador ha informat que el missatge no s'ha pogut lliurar. |
| `VALID_CODE_ENTERED` | L'usuari ha enviat el codi OTP correcte. |
| `INVALID_CODE_ENTERED` | L'usuari ha enviat un codi OTP incorrecte (compta per al límit d'introducció de codis). |
| `PHONE_VERIFICATION_APPROVED` | L'estat de la funcionalitat s'ha establert com a `Approved`. |
| `PHONE_VERIFICATION_DECLINED` | L'estat de la funcionalitat s'ha establert com a `Declined`. |
| `PHONE_VERIFICATION_IN_REVIEW` | L'estat de la funcionalitat s'ha establert com a `In Review`. |
| `PHONE_VERIFICATION_EXPIRED` | La finestra de l'OTP ha vençut sense un codi vàlid. |

El payload de `details` depèn de la família d'esdeveniments:

* **Esdeveniments d'enviament** (`PHONE_VERIFICATION_MESSAGE_SENT`, `PHONE_VERIFICATION_RETRY_MESSAGE_SENT`, `PHONE_VERIFICATION_BLOCKED`) — `{ status, reason, channel, actual_channel }`. `status` és `Success`, `Retry` o `Blocked`; `reason` és `null` tret que l'enviament s'hagi bloquejat (`invalid_phone_number`, `repeated_attempts`, `suspicious`, `spam`, `unknown`); `channel` és el canal sol·licitat i `actual_channel` el canal que realment l'ha lliurat (per exemple, un enviament per WhatsApp que ha passat a SMS).
* **Esdeveniments de lliurament** (`PHONE_DELIVERY_DELIVERED`, `PHONE_DELIVERY_UNDELIVERABLE`) — `{ channel, status }` amb `status` `delivered` o `undeliverable`.
* **Esdeveniments de comprovació** (`VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`) — `{ code_tried, status }` amb `status` `Approved`, `Declined`, `Failed` o `Expired or Not Found`.
* **Esdeveniments d'estat final** — `null`, excepte `PHONE_VERIFICATION_DECLINED` / `PHONE_VERIFICATION_IN_REVIEW`, que porten `{ "reason": "<risk code>" }` (per exemple, `PHONE_NUMBER_IN_BLOCKLIST`).

El `fee` d'un esdeveniment d'enviament és el preu total d'aquest enviament: el preu de l'operador o de WhatsApp més la tarifa de $0.02 de Didit, o només la tarifa de $0.02 de Didit per a un codi de WhatsApp enviat des del [teu propi número de WhatsApp Business](https://docs.didit.me/ca/core-technology/phone-verification/overview.md#enviar-codis-de-whatsapp-des-del-teu-propi-número). És el preu estimat fins que es confirma el lliurament, i després l'import realment facturat. Només els enviaments `Blocked` són garantits com a gratuïts: qualsevol altre enviament es cobra quan la verificació finalitza o caduca, fins i tot si el lliurament no s'ha confirmat mai o el missatge no s'ha pogut lliurar. Els esdeveniments de lliurament, comprovació i estat sempre porten `fee: 0`.

### Coincidències entre sessions

`matches[]` registra altres sessions a la mateixa aplicació on s'ha vist el mateix número —entre verificacions de KYC, KYB i API independent, independentment del seu estat— a més de coincidències amb les llistes de bloqueig configurades a les [llistes de l'API de gestió](https://docs.didit.me/ca/management-api/lists/overview.md). Les sessions que comparteixen el `vendor_data` de la sessió actual s'exclouen (el mateix usuari final no es fa coincidir amb ell mateix), i la llista està limitada a un màxim de **5** entrades. Quan el número és a la teva llista de bloqueig però cap de les sessions coincidents està a la llista de bloqueig, s'afegeix al principi de la llista una entrada sintètica amb `source: "list_entry"` (amb tots els camps de la sessió a `null`).

```typescript theme={null}
interface PhoneMatch {
  session_id: string | null;         // null when source = "list_entry"
  session_number: number | null;
  vendor_data: string | null;
  verification_date: string | null;  // ISO 8601, creation date of the matched session
  phone_number: string;
  status: string | null;             // Status of the matched session
  is_blocklisted: boolean;
  api_service: string | null;        // Set when the matched session came from a standalone API
  source: "session" | "list_entry";  // "list_entry" = manual blocklist hit
}
```

## Exemples

### Aprovada — OTP de WhatsApp, operador mòbil

```json theme={null}
{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "600600600",
  "full_number": "+34600600600",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Orange", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:12:39.684292Z",
  "warnings": [],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:12:30.580554Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
      "fee": 0.0509
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2025-08-24T09:12:31.000000Z",
      "details": { "channel": "whatsapp", "status": "delivered" },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:12:39.662157Z",
      "details": { "code_tried": "123456", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2025-08-24T09:12:39.684292Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "feature_phone_1"
}
```

### Rebutjada — número VoIP a la llista de bloqueig

L'usuari ha introduït un OTP vàlid, però la finalització ha detectat que el número es troba a la llista de bloqueig de l'aplicació (rebuig automàtic) i ha marcat el seu tipus de línia VoIP (`voip_number_action` s'ha mantingut a `NO_ACTION`, per la qual cosa es registra com a `information`). Com que cap sessió coincident està a la llista de bloqueig, la coincidència amb la llista de bloqueig apareix com una coincidència sintètica `list_entry`.

```json theme={null}
{
  "status": "Declined",
  "phone_number_prefix": "+1",
  "phone_number": "5551234567",
  "full_number": "+15551234567",
  "country_code": "US",
  "country_name": "United States",
  "carrier": { "name": "VoIP Carrier", "type": "voip" },
  "is_disposable": false,
  "is_virtual": true,
  "verification_method": "sms",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:11:10.221340Z",
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "PHONE_NUMBER_IN_BLOCKLIST",
      "additional_data": { "blocklisted_session_id": null, "blocklisted_session_number": null, "api_service": null },
      "log_type": "error",
      "short_description": "Phone number in blocklist",
      "long_description": "The system detected that the phone number is in the blocklist, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "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"
    }
  ],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:11:00.000000Z",
      "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms" },
      "fee": 0.0509
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:11:10.221340Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_DECLINED",
      "timestamp": "2025-08-24T09:11:10.350000Z",
      "details": { "reason": "PHONE_NUMBER_IN_BLOCKLIST" },
      "fee": 0
    }
  ],
  "matches": [
    {
      "session_id": null,
      "session_number": null,
      "vendor_data": null,
      "verification_date": null,
      "phone_number": "+15551234567",
      "status": null,
      "is_blocklisted": true,
      "api_service": null,
      "source": "list_entry"
    }
  ],
  "node_id": "feature_phone_1"
}
```

## Relacionat

* [Visió general de Verificació de telèfon](https://docs.didit.me/ca/core-technology/phone-verification/overview.md) — comportament de la funcionalitat, preus, canals admesos.
* [Advertències de Verificació de telèfon](https://docs.didit.me/ca/core-technology/phone-verification/warnings-phone-verification.md) — tots els codis de risc, activadors de rebuig i accions configurables.
* [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 telèfon independent](https://docs.didit.me/ca/standalone-apis/phone-send.md) — endpoints `POST /v3/phone/send/` i [`POST /v3/phone/check/`](https://docs.didit.me/ca/standalone-apis/phone-check).
* [Management API — Llistes](https://docs.didit.me/ca/management-api/lists/overview.md) — gestiona la llista de bloqueig de telèfons que alimenta `matches[]` amb `source: list_entry`.


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