es
Vista previa gratis

Integración de la API OTP de WhatsApp: ejemplos en PHP, Node.js y Python

Por: Equipo de WapFlow · 16 de noviembre de 2026 · 7 min de lectura
Editor de código con una llamada a la API OTP de WhatsApp y un código de verificación en un teléfono

Enviar un código de verificación por WhatsApp se reduce a dos llamadas con la API de WapFlow OTP: una envía el código y la otra verifica lo que escribe el usuario. En esta guía reunimos cómo funciona la API, ejemplos en cURL, PHP, Node.js y Python, el manejo de errores y los puntos de seguridad a tener en cuenta. Los ejemplos siguen el formato de la documentación oficial de la API, con pequeñas adiciones para facilitar la lectura. Si todavía no sabe qué es el producto antes de empezar a programar, lea primero Qué es WhatsApp OTP.

Lo básico

  • URL base: https://wapflow.net/api/otp/v1
  • Autenticación: un encabezado Authorization: Bearer <key> en cada solicitud. Las claves de producción empiezan por wfo_live_, y las de prueba por wfo_test_.
  • Formato de respuesta: { "success": true, ... } en caso de éxito, { "success": false, "error": { "code": "...", "message": "..." } } en caso de error.
  • Número de teléfono: con el código de país, por ejemplo 905321234567. La API reduce el número a dígitos (se eliminan +, espacios y guiones) y espera entre 10 y 15 dígitos. Los números de once dígitos que empiezan por 0 se consideran turcos y se les añade 90 delante.

Cree la clave de API en la página de WapFlow OTP del panel de WapFlow. Una clave solo se muestra una vez, en el momento de crearla; guárdela en una variable de entorno de su servidor.

Cuatro endpoints

EndpointFinalidad
POST /sendGenera el código y lo envía por WhatsApp. phone es obligatorio; opcionales: code_length (4-8), ttl (60-900 s), lang, app_name.
POST /verifyComprueba el código que escribió el usuario. phone y code son obligatorios; si envía request_id, se comprueba esa solicitud en concreto.
GET /status/:request_idDevuelve el estado de la solicitud: queued, sent, delivered, read, failed, verified, expired.
GET /meMuestra si la clave es válida, el plan, el número de cuentas conectadas y el uso de la cuota de este mes.

Tras 5 intentos incorrectos, la solicitud se bloquea, y un código ya verificado no puede volver a usarse. Si omite request_id, se comprueba el último código vigente enviado a ese número con esta clave. Como pueden existir varias sesiones, le recomendamos guardar el request_id y enviarlo de vuelta al verificar.

Una primera prueba con cURL

# 1) send the code
curl -X POST https://wapflow.net/api/otp/v1/send \
  -H "Authorization: Bearer wfo_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"phone":"905321234567","app_name":"Acme"}'

# 2) verify the code
curl -X POST https://wapflow.net/api/otp/v1/verify \
  -H "Authorization: Bearer wfo_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"req_...","phone":"905321234567","code":"123456"}'

Haga la primera prueba con una clave wfo_test_: no se envía ningún mensaje de WhatsApp, no se consume cuota y el código aparece en el campo test_code de la respuesta.

Ejemplo en PHP

<?php
function wapflow_otp(string $path, array $body): array {
    $ch = curl_init('https://wapflow.net/api/otp/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('WAPFLOW_OTP_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($body),
    ]);
    $res = json_decode(curl_exec($ch), true) ?: [];
    curl_close($ch);
    return $res;
}

$sent = wapflow_otp('/send', ['phone' => '905321234567', 'app_name' => 'Acme']);
// ... when the user submits the code:
$check = wapflow_otp('/verify', ['request_id' => $sent['request_id'], 'phone' => '905321234567', 'code' => $_POST['code']]);
if (!empty($check['valid'])) { /* signed in */ }

Ejemplo en Node.js

El ejemplo usa el fetch integrado (Node.js 18 o posterior) y debe ejecutarse como módulo ES.

const BASE = 'https://wapflow.net/api/otp/v1';
async function otp(path, body) {
  const res = await fetch(BASE + path, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.WAPFLOW_OTP_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  return res.json();
}
const sent = await otp('/send', { phone: '905321234567', app_name: 'Acme' });
// ... when the user submits the code:
const check = await otp('/verify', { request_id: sent.request_id, phone: '905321234567', code: '123456' });
if (check.valid) { /* signed in */ }

Ejemplo en Python

import os
import requests

BASE = "https://wapflow.net/api/otp/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["WAPFLOW_OTP_KEY"]}

def otp(path, body):
    return requests.post(BASE + path, json=body, headers=HEADERS, timeout=15).json()

sent = otp("/send", {"phone": "905321234567", "app_name": "Acme"})
# ... when the user submits the code:
check = otp("/verify", {"request_id": sent["request_id"], "phone": "905321234567", "code": "123456"})
if check.get("valid"):
    pass  # signed in

Manejo de errores

Trate por separado el envío y la verificación. Si un envío devuelve success: false, actúe según el código de error:

HTTP / códigoQué hacer
401 invalid_keyRevise la clave; puede haber sido revocada o escrita mal.
402 no_subscription, subscription_expiredContrate o renueve la suscripción.
422 invalid_phonePida al usuario que vuelva a introducir el número con el código de país.
429 rate_limitedReintente tras los segundos indicados en retry_after de la respuesta.
429 quota_exceededSe ha agotado la cuota mensual; amplíe el plan o espere al siguiente periodo.
429 daily_limit_reachedLas cuentas conectadas han alcanzado su límite diario; reintente después de retry_after (al día siguiente a las 00:00, hora de Turquía). No se consume cuota.
503 no_account_connected, send_failedAsegúrese de que exista una cuenta de WhatsApp conectada y habilitada; reintente en breve.

En la verificación, un HTTP 200 puede seguir trayendo valid en false. El campo reason le indica el motivo: invalid_code, expired, too_many_attempts, already_verified o not_found. Para un código incorrecto, attempts_left indica cuántos intentos quedan; transmitir ese dato al usuario mejora la experiencia.

Límites de uso y experiencia del usuario

  • Un número puede recibir 1 código cada 60 segundos, 5 por hora y 10 al día. Ponga una cuenta atrás de 60 segundos en su botón "Reenviar".
  • Hay 60 envíos por minuto por clave de API, 120 solicitudes por minuto por dirección IP y, para la verificación, 10 intentos por minuto por número.
  • El límite diario y el calentamiento de los números nuevos afectan al envío; consulte nuestro artículo sobre cómo reducir el riesgo de bloqueo para más detalles.

Lista de seguridad

  • Nunca use la clave de API en un navegador, una aplicación móvil ni código público; haga las llamadas desde su servidor.
  • Verifique siempre el código en el servidor con /verify; no confíe en una marca de "verificado" que llegue desde el navegador.
  • Guarde la clave en una variable de entorno y fuera de su repositorio.
  • Aplique su propio límite de uso y, si es necesario, un CAPTCHA antes de enviar un código; el abuso puede consumir su cuota.
  • Mantenga un canal de respaldo (SMS o correo electrónico) para las acciones críticas. WapFlow OTP no es la API oficial de WhatsApp Business y no garantiza la entrega.

Si usa WordPress o WooCommerce, puede prescindir de programar y usar el plugin. Consulte la página de precios para los planes y la página de WapFlow OTP para la descripción general del producto.

Preguntas frecuentes

¿Qué cambia cuando pase a producción?

Solo la clave. Una clave de prueba empieza por wfo_test_, y sus reglas de envío y de límites son las mismas que las de una clave de producción; sigue siendo necesaria una suscripción activa.

¿Tengo que enviar request_id?

No, pero se recomienda. Si lo omite, se comprueba el último código vigente enviado a ese número.

¿Puedo cambiar el texto del mensaje?

Sí. En el panel puede configurar el nombre de la aplicación, la plantilla del mensaje, la longitud del código, la validez y el idioma. La plantilla usa las variables {code}, {app} y {minutes}. Por solicitud, puede sobrescribir estos valores con app_name, code_length, ttl y lang.

¿Cómo sé que el mensaje se entregó?

Consulte la solicitud con /status/:request_id; puede ver sent, delivered y read. La información de entrega depende de WhatsApp y no está garantizada.

¿Esta API está disponible también en la aplicación de Windows?

No. WapFlow OTP es un servicio independiente basado en la nube.

Artículos relacionados