> ## 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. # API de envío de OTP por teléfono: código por SMS > POST /v3/phone/send/ de Didit envía un código de un solo uso por SMS. Reintento ante números bloqueados, validez de 5 min, pago por uso, sin mínimos. ## Muestra el nombre de tu marca en el SMS Los códigos por SMS llevan el nombre del remitente de SMS de tu aplicación, que se configura en la Business Console, sin coste adicional: > 123456 es tu código de verificación para **Acme Bank** Para firmar un código concreto con otro nombre, envía `options.sms_sender_name` (de 1 a 30 caracteres: solo letras, dígitos, espacios y ' & - !, y no puede estar formado solo por dígitos): ```json theme={null} { "phone_number": "+14155552671", "options": { "preferred_channel": "sms", "sms_sender_name": "Acme Bank" } } ``` Un nombre que no cumpla estas reglas devuelve `400` y no se envía ningún código. Los códigos por WhatsApp usan un mensaje fijo y no llevan tu marca; conecta tu propio número de WhatsApp Business en la Business Console para enviarlos con el nombre de tu empresa. Consulta [Envía códigos por WhatsApp desde tu propio número](https://docs.didit.me/es/core-technology/phone-verification/overview.md#envía-los-códigos-de-whatsapp-desde-tu-propio-número). Consulta [Mensajes de verificación con tu marca](https://docs.didit.me/es/core-technology/phone-verification/overview.md#mensajes-de-verificación-con-tu-marca) para saber qué nombre lleva un código y cuál es el límite diario de nombres nuevos. ## Gestiona las caídas del proveedor Si el proveedor de telefonía no está disponible temporalmente, este endpoint devuelve `502` con un código estable y legible por máquina: ```json theme={null} { "detail": "The phone verification provider is temporarily unavailable.", "code": "phone_provider_unavailable" } ``` Considera que puedes reintentar la solicitud. Usa un backoff corto y muestra al usuario un mensaje de indisponibilidad temporal del servicio en lugar de pedirle que cambie un número de teléfono o un código válidos. ## OpenAPI ````yaml es/openapi-25.json POST /v3/phone/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificación de identidad. Autentícate con el encabezado x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/phone/send/: post: tags: - Standalone APIs summary: Enviar código por teléfono description: >- Envía un código de un solo uso (OTP) a un número de teléfono por WhatsApp, SMS u otro canal compatible y, después, verifícalo con [`POST /v3/phone/check/`](/es/standalone-apis/phone-check). **Cómo se relacionan el envío y la comprobación.** El estado de la verificación se identifica por tu aplicación y el `phone_number` en formato E.164: la llamada de comprobación no recibe `request_id`. Cada nuevo envío crea una verificación pendiente que dura **5 minutos**: llama a la comprobación con el mismo número y el código que recibió el usuario antes de que se cierre ese plazo. Si vuelves a llamar al envío para el mismo número mientras hay una verificación pendiente, se reenvía un código para esa misma verificación (`status: "Retry"`, mismo `request_id`). Solo se asocia un reintento de esta forma (dos envíos en total); un envío adicional inicia una verificación nueva con un `request_id` nuevo. El plazo de 5 minutos se cuenta desde el primer envío y los reintentos no lo amplían. **Canales de entrega.** `options.preferred_channel` selecciona el canal (`whatsapp` por defecto; también se admiten `sms`, `telegram`, `voice`, `rcs`, `viber` y `zalo`). Cuando el canal preferido no está disponible para el país o el número de destino, la entrega recurre automáticamente a SMS: el envío sigue devolviendo `Success` y el canal realmente utilizado aparece en la respuesta de la comprobación (`phone.verification_method` y los eventos de `lifecycle`). **Marca.** Los códigos por SMS llevan el nombre de remitente SMS de tu aplicación, configurado en la Business Console, sin coste adicional. Pasa `options.sms_sender_name` para firmar un código con otro nombre, u `options.use_white_label_customization: true` para usar tu nombre público de marca blanca cuando no haya ningún nombre de remitente configurado. Los códigos por WhatsApp usan un mensaje fijo; conecta tu propio número de WhatsApp Business en la Business Console para enviarlos con el nombre y el número de tu empresa, y solo se factura la tarifa de Didit. **Estados del envío.** `Success`: OTP enviado para una verificación nueva; `Retry`: OTP reenviado para la verificación pendiente; `Blocked`: la capa antifraude se negó a enviarlo (consulta `reason`, por ejemplo `repeated_attempts`, `suspicious`, `spam`). Un envío `Blocked` finaliza de inmediato la verificación como `Declined` con una advertencia de riesgo alto, por lo que una comprobación posterior devuelve `Expired or Not Found`. **Facturación.** El precio depende del país de destino y del canal que realmente entrega el mensaje; consulta [Precios de la verificación de teléfono](/es/getting-started/phone-verification-pricing). Solo los envíos `Blocked` son siempre gratuitos: cualquier otro intento de envío no facturado se cobra al finalizar o expirar la verificación, aunque nunca se haya confirmado la entrega o el proveedor de entrega haya informado de que el mensaje no se pudo entregar. Las comprobaciones son siempre gratuitas. Como medida contra el abuso, la verificación de teléfono está desactivada hasta la primera recarga de tu organización (`403`). **Persistencia de la sesión.** Cada verificación nueva se guarda como una sesión de tipo API: `request_id` es un id de sesión real que puedes pasar a `GET /v3/session/{sessionId}/decision/`, la verificación aparece en la Business Console y se disparan webhooks `status.updated` a medida que avanza. **Sandbox.** Las claves de API de sandbox omiten la entrega y la facturación: tras validar la solicitud (una entrada mal formada sigue devolviendo `400`), el endpoint devuelve un payload estático `Success` con un `request_id` aleatorio; no se envía ningún mensaje y no se guarda nada. Usa el código `123456` en la comprobación de sandbox. **Autenticación.** Envía la clave de API de tu aplicación en el encabezado `x-api-key`. Si faltan las credenciales o no son válidas, se devuelve `403` (`{"detail": "You do not have permission to perform this action."}`): esta API nunca devuelve `401`. **Límites de solicitudes.** Presupuesto de escritura compartido de 300 solicitudes/min por clave de API entre todos los endpoints POST/PATCH/DELETE, más un límite contra el abuso de 4 intentos de envío por número de teléfono y hora; si se supera cualquiera de los dos, se devuelve `429`. operationId: post_v3phone_send requestBody: required: true content: application/json: schema: type: object properties: phone_number: type: string maxLength: 20 description: >- Número de teléfono del destinatario en formato E.164: `+` inicial y código de país (p. ej., `+14155552671`). Los números se validan y se normalizan a E.164; los números que no se pueden analizar o que no son válidos devuelven `400` con un error en el campo `phone_number`. example: '+14155552671' options: type: object description: >- Opciones de entrega del OTP. Todos los campos son opcionales. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: Número de dígitos del OTP. locale: type: string maxLength: 5 pattern: ^[a-z]{2,3}(-[A-Z]{2,3})?$ description: >- Configuración regional BCP-47 que se usa para localizar el mensaje de verificación (p. ej., `en-US`, `fr`, `es`). Los formatos no válidos devuelven `400`. example: en-US preferred_channel: type: string enum: - whatsapp - sms - telegram - voice - rcs - viber - zalo default: whatsapp description: >- Canal de entrega preferido. Si el canal no está disponible para el país o el número de destino, el mensaje recurre automáticamente a SMS y el envío sigue informando `Success`. use_white_label_customization: type: boolean default: false description: >- Si es `true`, el envío es de marca blanca: si tu aplicación no tiene nombre de remitente de SMS, el SMS menciona en su lugar tu nombre público de marca blanca ("123456 es tu código de verificación para Acme Bank"). Tu nombre de remitente de SMS, si está configurado, se usa con o sin este indicador. Se aplica a los mensajes SMS, incluido un SMS de respaldo desde otro canal; los códigos de WhatsApp se envían con un mensaje fijo y no llevan marca. El valor predeterminado es `false`. sms_sender_name: type: string nullable: true maxLength: 30 example: Acme Bank description: >- El nombre que lleva el SMS de este código ("123456 is your verification code for Acme Bank"), en lugar del nombre de remitente de SMS de tu aplicación. Gratis. De 1 a 30 caracteres: solo letras, dígitos, espacios y ' & - !, no solo dígitos, con un único espacio entre palabras; cualquier otro valor devuelve `400` y no se envía ningún código. Si se omite o es `null` o está vacío, se usa el nombre de remitente de SMS de tu aplicación. Cada aplicación puede empezar a usar hasta dos nombres nuevos por día (UTC); a partir de ese límite, el código se envía con el nombre de tu aplicación. Se aplica a los mensajes SMS, incluido un SMS de respaldo desde otro canal; los códigos por WhatsApp no llevan marca. pattern: ^$|^(?![\d ]+$)[\p{L}\p{N}'&!-]+( [\p{L}\p{N}'&!-]+)*$ signals: type: object description: >- Señales opcionales de dispositivo y red sobre el usuario final, que se envían a la capa antifraude para mejorar la detección de tráfico abusivo o automatizado. Todos los campos son opcionales. properties: ip: type: string description: >- Dirección IP del dispositivo del usuario final. IPv4 o IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identificador único del dispositivo del usuario final. Android: `ANDROID_ID`; iOS: `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Plataforma del dispositivo del usuario final. device_model: type: string maxLength: 255 description: Modelo del dispositivo del usuario final. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Versión del sistema operativo del dispositivo del usuario final. example: 18.0.1 app_version: type: string maxLength: 64 description: Versión de tu aplicación. example: 1.2.34 user_agent: type: string maxLength: 512 description: >- User agent del navegador o la aplicación del usuario final. example: >- Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1 vendor_data: type: string description: >- Identificador opcional controlado por quien llama (tu id interno de usuario, un correo electrónico, un UUID, etc.) que se guarda en la sesión y se devuelve en la respuesta del envío, en la respuesta de la comprobación correspondiente, en los webhooks y en la Business Console. Úsalo para relacionar el `request_id` de Didit con tu registro de usuario. metadata: type: object nullable: true description: >- Objeto JSON opcional de formato libre que se guarda en la sesión y se devuelve en la respuesta del envío, en la respuesta de la comprobación correspondiente, en los webhooks y en la Business Console. required: - phone_number examples: WhatsApp (default): summary: >- OTP de 6 dígitos por WhatsApp, con paso automático a SMS como alternativa value: phone_number: '+14155552671' options: preferred_channel: whatsapp locale: en-US vendor_data: user-1234 SMS with custom code length: summary: Forzar la entrega por SMS con un código de 4 dígitos value: phone_number: '+34699999999' options: preferred_channel: sms code_size: 4 locale: es With fraud signals: summary: >- Envía señales del dispositivo para reforzar el análisis antifraude value: phone_number: '+14155552671' signals: ip: 192.0.2.1 device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: ios device_model: iPhone17,2 os_version: 18.0.1 app_version: 1.2.34 vendor_data: user-1234 responses: '200': description: >- Envío confirmado. Revisa `status`: `Success` y `Retry` significan que hay un código en camino; `Blocked` significa que la capa antifraude lo rechazó y la verificación ya se ha finalizado como `Declined`. `request_id` es el id de sesión persistido (el mismo id en un `Retry`). content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationSendResponse' examples: Success: summary: OTP enviado para una nueva verificación value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Segundo envío al mismo número dentro de la ventana de 5 minutos: mismo request_id value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Blocked: summary: >- Rechazo antifraude: la verificación se finaliza como Declined y no se factura nada value: request_id: 0d8af1f4-0c43-46d7-b75c-6e4e22c0a7b3 status: Blocked reason: repeated_attempts vendor_data: user-1234 metadata: null '400': description: >- Error de validación. Una entrada mal formada devuelve el envoltorio de errores de campo de DRF (un array de mensajes por cada campo incorrecto, anidado bajo `options` para los errores de opciones). Un número que se analiza correctamente pero se rechaza en el momento del envío (inalcanzable, o un tipo de línea no apto, como un código corto) devuelve en su lugar un envoltorio `{"detail": ...}`. content: application/json: examples: Invalid phone number (field error): summary: El número no es un E.164 válido value: phone_number: - Invalid phone number provided. Missing phone number: summary: '`phone_number` no está incluido en el cuerpo' value: phone_number: - This field is required. Invalid options: summary: >- `code_size` fuera de rango, `locale` mal formado, `preferred_channel` desconocido value: options: code_size: - Ensure this value is less than or equal to 8. locale: - Ensure this field has no more than 5 characters. preferred_channel: - '"carrier_pigeon" is not a valid choice.' Number rejected at send time: summary: Formato E.164 válido, pero el número no puede recibir un OTP value: detail: Invalid phone number provided. Ineligible line type: summary: >- El tipo de línea no puede recibir un OTP (p. ej., un código corto) value: detail: Invalid phone line type provided. '403': description: >- Permiso denegado. Se devuelve cuando falta el encabezado `x-api-key` (`{"detail": ...}`); una clave incorrecta, revocada o expirada devuelve `401`. También se devuelve antes de cualquier envío cuando la organización nunca ha recargado saldo (medida antiabuso) o cuando su saldo no cubre el precio de envío al destino (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: >- Falta el encabezado `x-api-key`, o la clave no es válida o está revocada value: detail: You do not have permission to perform this action. Top-up required: summary: >- La verificación de teléfono permanece desactivada hasta la primera recarga de la organización value: detail: >- To protect against abuse, phone verification is disabled until your first top-up. Not enough credits: summary: El saldo de la organización no cubre el precio del envío value: error: You don't have enough credits to perform this request. '429': description: >- Límite de solicitudes superado. Todos los endpoints POST/PATCH/DELETE comparten un presupuesto de 300 solicitudes de escritura por minuto por clave de API. Además, se aplica previamente un tope antiabuso de 4 intentos de verificación por número de teléfono por hora. La respuesta incluye los encabezados `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` y `Retry-After`. Nota: los encabezados `X-RateLimit-*`/`Retry-After` acompañan solo al 429 del límite de escritura de 300 por minuto; el 429 del tope por número no incluye encabezados de límite de solicitudes. content: application/json: examples: Per-number cap: summary: >- Más de 4 intentos de verificación para el mismo número en la última hora value: detail: >- Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number. Write rate limit exceeded: summary: Más de 300 solicitudes de escritura en el minuto actual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '500': description: >- Error inesperado al crear la verificación que no corresponde a una caída conocida del proveedor. Se puede reintentar sin riesgo. content: application/json: examples: Provider error: summary: No se pudo iniciar la entrega del OTP value: detail: Error creating phone verification schema: type: object properties: detail: type: string '502': description: >- El proveedor de verificación de teléfono no está disponible temporalmente: una respuesta 5xx, un tiempo de espera agotado o un fallo de conexión que persistió tras los reintentos integrados. Puedes reintentar sin riesgo; no se factura nada ni se consume ningún intento. content: application/json: examples: Provider outage: summary: El proveedor no respondió a la solicitud de envío value: detail: >- Phone verification is temporarily unavailable. Please try again shortly. code: phone_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/phone/send/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "phone_number": "+14155552671", "options": { "code_size": 6, "preferred_channel": "whatsapp", "locale": "en-US" }, "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.phone.send_code( phone_number="+14155552671", options={ "locale": "en-US", "preferred_channel": "whatsapp", }, vendor_data="user-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.phone.sendCode({ phone_number: "+14155552671", options: { locale: "en-US", preferred_channel: "whatsapp", }, vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.SendCode(ctx, didit.PhoneSendCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tOptions: didit.Some(didit.PhoneSendCodeParamsOptions{\n\t\tLocale: didit.String(\"en-US\"),\n\t\tPreferredChannel: didit.Some(didit.PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.PhoneSendCodeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.phone().sendCode(PhoneSendCodeParams.builder() .phoneNumber("+14155552671") .options(PhoneSendCodeParams.Options.builder() .locale("en-US") .preferredChannel(PhoneSendCodeParams.Options.PreferredChannel.of("whatsapp")) .build()) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- phone->sendCode([ 'phone_number' => '+14155552671', 'options' => [ 'locale' => 'en-US', 'preferred_channel' => 'whatsapp', ], 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.phone.send_code( phone_number: "+14155552671", options: { locale: "en-US", preferred_channel: "whatsapp", }, vendor_data: "user-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Phone.SendCodeAsync(new PhoneSendCodeParams { PhoneNumber = "+14155552671", Options = new PhoneSendCodeParamsOptions { Locale = "en-US", PreferredChannel = new PhoneSendCodeParamsOptionsPreferredChannel("whatsapp"), }, VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: PhoneVerificationSendResponse: type: object properties: request_id: type: string format: uuid description: >- ID de sesión de la verificación. Un envío `Retry` devuelve el mismo `request_id` que el envío original. Este ID aparece en la Business Console, lo vuelve a devolver un `POST /v3/phone/check/` finalizado y se puede pasar a `GET /v3/session/{sessionId}/decision/`. status: type: string enum: - Success - Retry - Blocked description: >- `Success`: OTP enviado a una nueva verificación. `Retry`: OTP reenviado para la verificación pendiente creada por un envío anterior. `Blocked`: la capa antifraude se negó a enviarlo; la verificación se finaliza de inmediato como `Declined` y no se factura nada. reason: type: string nullable: true description: >- Por qué un envío quedó en `Blocked` (por ejemplo, `repeated_attempts`, `suspicious`, `spam`). `null` en `Success` y `Retry`. vendor_data: type: string nullable: true description: >- Devuelve el `vendor_data` almacenado en la sesión (del primer envío). metadata: type: object nullable: true description: Devuelve el `metadata` almacenado en la sesión (del primer envío). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.