Informe de verificació de telèfon: JSON d'OTP i 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

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).
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/ per lliurar el codi i POST /v3/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.

{
  "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.

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. É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ó. 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).

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

{
  "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.

{
  "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 — comportament de la funcionalitat, preus, canals admesos.
Advertències de Verificació de telèfon — tots els codis de risc, activadors de rebuig i accions configurables.
Models de dades — verificació de telèfon — esquema canònic camp per camp.
API de telèfon independent — endpoints POST /v3/phone/send/ i POST /v3/phone/check/.
Management API — Llistes — gestiona la llista de bloqueig de telèfons que alimenta matches[] amb source: list_entry.

Autenticació

Verificació

Monitoratge

Plataforma

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

Visió general

On apareix a les respostes de l’API

Esquema

Valors d’estat

Tipus d’esdeveniments del cicle de vida

Coincidències entre sessions

Exemples

Aprovada — OTP de WhatsApp, operador mòbil

Rebutjada — número VoIP a la llista de bloqueig

Relacionat

​Visió general

​On apareix a les respostes de l’API

​Esquema

​Valors d’estat

​Tipus d’esdeveniments del cicle de vida

​Coincidències entre sessions

​Exemples

​Aprovada — OTP de WhatsApp, operador mòbil

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

​Relacionat

Visió general

On apareix a les respostes de l’API

Esquema

Valors d’estat

Tipus d’esdeveniments del cicle de vida

Coincidències entre sessions

Exemples

Aprovada — OTP de WhatsApp, operador mòbil

Rebutjada — número VoIP a la llista de bloqueig

Relacionat