Cómo enviar y verificar un código OTP por SMS paso a paso

Para enviar un código de verificación por SMS, el backend debe solicitar o generar una contraseña de un solo uso (OTP), enviarla al usuario y validar después el código introducido. Con una API de OTP , la generación, el envío y la verificación pueden gestionarse dentro de un mismo flujo, sin exponer las credenciales del servicio en el navegador o la aplicación móvil.

1. Crear una plantilla OTP

   Defina el canal, el idioma, la longitud del código y su periodo de validez.

2. Obtener las credenciales API

   Cree una API Key y mantenga el dev_secret exclusivamente en el servidor.

3. Enviar el código

   Llame al endpoint de envío desde su backend y conserve el message_id de la respuesta.

4. Recibir el código del usuario

   La interfaz recoge el OTP y lo envía a su backend, no directamente al proveedor con una credencial secreta.

5. Verificar el OTP

   El backend envía el message_id y el código recibido al endpoint de verificación antes de aprobar la acción.

Cómo enviar y verificar un código OTP por SMS con una API

Un flujo de verificación no termina cuando el SMS se acepta para su envío. Para que la autenticación esté completa, la aplicación debe vincular la solicitud de envío con el código que el usuario devuelve. En EngageLab, el flujo estándar utiliza POST /v1/messages para generar y enviar el OTP y POST /v1/verifications para comprobarlo.

1 Crear una plantilla y una API Key

La configuración inicial del flujo se realiza desde la consola de EngageLab. Primero, active el servicio OTP, cree una aplicación y configure una plantilla. Ahí define el canal, el contenido y las reglas básicas del código, como su longitud y tiempo de validez. La API admite códigos de 4 a 10 caracteres y, en SMS, una validez de 1 a 10 minutos; algunas estrategias multicanal ofrecen opciones más limitadas. Antes de utilizar la plantilla en producción, asegúrese de que esté aprobada.

Después, acceda al área de claves API para crear las credenciales que utilizará su backend. Desde el portal puede gestionar las claves asociadas a la aplicación, definir su vigencia y aplicar restricciones adicionales antes de comenzar la integración.

Ejemplo de la gestión de claves API en el portal de EngageLab. La captura corresponde al módulo SMS; para un flujo OTP, cree y gestione las credenciales desde la sección API Keys del servicio OTP.

Al crear una clave, puede definir parámetros como su descripción, vigencia y las IP autorizadas. En el servicio OTP, revise también los permisos disponibles para limitar las operaciones que puede realizar cada clave.

Ejemplo del formulario de creación de una clave API, con opciones de vigencia y lista blanca IP. La interfaz y los campos disponibles pueden variar entre los distintos servicios de EngageLab.

La autenticación de las llamadas REST utiliza HTTP Basic con dev_key y dev_secret . El secreto debe permanecer en el servidor: no debe incluirse en JavaScript del navegador, aplicaciones móviles ni repositorios públicos.

Si necesita revisar todo el proceso de configuración inicial, consulte el inicio rápido de OTP de EngageLab .

2 Conectar la API desde su backend

Una vez configuradas la plantilla y las credenciales en el portal, el resto del flujo pasa al backend de su aplicación. Las solicitudes de envío y verificación deben realizarse desde el servidor, no directamente desde el navegador o la aplicación móvil.

En la práctica, esto significa guardar el dev_key y el dev_secret en un entorno seguro del servidor y utilizarlos allí para autorizar las llamadas API. De este modo, el frontend solo recoge la información necesaria del usuario, mientras que el backend mantiene el control sobre quién puede solicitar o verificar un código.

Seguridad

En producción, mantenga el dev_secret únicamente en el servidor, configure una lista blanca con las IP de salida autorizadas y limite los permisos de la API Key a las operaciones que realmente necesita.

3 Enviar el OTP

Para que EngageLab genere el código y lo envíe según la estrategia definida en la plantilla, utilice:

curl --request POST "https://otp.api.engagelab.cc/v1/messages" \
  --user "$ENGAGELAB_DEV_KEY:$ENGAGELAB_DEV_SECRET" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "<NUMERO_E164>",
    "end_user_ip": "203.0.113.10",
    "template": {
      "id": "mi-plantilla-otp",
      "language": "es"
    }
  }'

El parámetro end_user_ip es opcional y puede ayudar a limitar solicitudes anómalas por IP. Una respuesta correcta devuelve un message_id y el canal utilizado en esa etapa:

{
  "message_id": "1725407449772531712",
  "send_channel": "sms"
}

En términos prácticos: su aplicación envía el número del usuario y la plantilla que quiere utilizar; EngageLab genera el OTP y devuelve un message_id . Guarde ese identificador, porque conecta el envío con la verificación posterior. El campo send_channel indica el canal usado en esa etapa, pero no demuestra por sí solo que el usuario haya recibido el código. Para comprobar la entrega, utilice los callbacks o el historial de mensajes.

4 Recoger el código introducido por el usuario

Cuando el usuario recibe el SMS, introduce el código en su web o aplicación. Esa interfaz debe enviar el valor a su propio backend junto con el identificador de la verificación que corresponda a la sesión.

El navegador o la app móvil no deberían llamar a la API de OTP con el dev_secret . El backend es quien debe decidir si la sesión puede verificar un código, aplicar controles de frecuencia y enviar la solicitud al proveedor.

5 Verificar el OTP

En el flujo gestionado por EngageLab, la verificación se realiza mediante POST /v1/verifications . Envíe el message_id obtenido en el paso anterior y el código introducido por el usuario:

curl --request POST "https://otp.api.engagelab.cc/v1/verifications" \
  --user "$ENGAGELAB_DEV_KEY:$ENGAGELAB_DEV_SECRET" \
  --header "Content-Type: application/json" \
  --data '{
    "message_id": "<MESSAGE_ID>",
    "verify_code": "<CODIGO_OTP>"
  }'

En términos prácticos: su backend envía el message_id anterior junto con el código que ha escrito el usuario. Si la respuesta devuelve verified: true , puede continuar con el inicio de sesión, registro o acción sensible. Si el OTP ha caducado o ya se utilizó correctamente, debe iniciar una nueva verificación. Por eso, enviar el SMS no equivale a verificar la identidad .

Dos formas de gestionar un flujo OTP

No todas las empresas necesitan delegar todo el ciclo de vida del código. Una decisión de arquitectura importante es determinar quién genera y quién verifica el OTP.

OTP generado y verificado por el proveedor

En el flujo estándar, su backend solicita el envío con /v1/messages . EngageLab genera el código según la plantilla y, cuando el usuario lo introduce, su backend lo comprueba con /v1/verifications . Este enfoque centraliza la generación, el envío y la comprobación y reduce la cantidad de lógica de OTP que debe mantener su aplicación.

OTP generado por su propia aplicación

Si ya dispone de un sistema de autenticación que genera y valida códigos, puede utilizar POST /v1/codes para enviar un OTP pregenerado. En este caso, EngageLab actúa como capa de entrega y la validación permanece en su infraestructura. La documentación de Custom Send OTP indica expresamente que, después de este envío, no es necesario utilizar la API Verify de EngageLab.

Si genera sus propios códigos, la empresa pasa a ser responsable de su almacenamiento temporal, caducidad, uso único, límites de intentos y eliminación segura. No conviene adoptar el segundo modelo solo para “tener más control” si el equipo no necesita mantener esa lógica internamente.

Controles antes de pasar el flujo OTP a producción

Una prueba que devuelve verified: true demuestra que la integración básica funciona, pero todavía no que el sistema esté preparado para tráfico real. Antes del lanzamiento, revise al menos estos controles:

Para el canal SMS, el Security Center de EngageLab permite limitar solicitudes por número o IP, establecer avisos y cuotas, restringir países o regiones y detener temporalmente los envíos ante una anomalía. Puede incluir end_user_ip para aplicar controles sobre la IP del usuario final. Aun así, su propia aplicación también debería decidir cuándo puede solicitarse un código, bloquear patrones abusivos y, cuando corresponda, añadir CAPTCHA.

Para saber qué está ocurriendo después del envío, utilice los callbacks o el historial de mensajes. Así puede diferenciar entre un mensaje aceptado para envío, uno entregado, una verificación completada y un fallo. Esta distinción es importante porque una respuesta correcta de la API de envío no significa automáticamente que el usuario haya recibido y validado el OTP.

Los límites de reenvío y seguridad deben tratarse como parte normal de la experiencia. Si el usuario solicita códigos con demasiada frecuencia o se supera un límite por número, IP o volumen, no intente reenviar de forma continua. Muestre un tiempo de espera claro, aplique reintentos progresivos desde el backend y consulte la documentación de errores si necesita distinguir la causa exacta.

Si genera su propio OTP

Si su empresa genera y verifica el OTP, también asume su seguridad: defina una caducidad breve, permita un solo uso, limite los intentos y evite registrar o conservar el código en texto plano más tiempo del necesario. Estas prácticas coinciden con las recomendaciones de OWASP para OTP gestionados por la propia aplicación.

Fallback, entrega y límites del SMS OTP

Canales disponibles y fallback

El SMS puede ser el canal principal de un flujo OTP, pero no es necesario tratar cada fallo de entrega como un callejón sin salida. La configuración actual de plantillas de EngageLab admite SMS, WhatsApp, Email, Voice, Zalo y Viber. En las estrategias multicanal compatibles, los canales se ordenan para que el siguiente se utilice cuando falle el anterior.

Hay una distinción importante: que un canal esté disponible no significa que pueda formar parte de cualquier cadena de fallback . La API de plantillas indica actualmente que Email no puede combinarse con otros canales dentro de send_channel_strategy . Por tanto, una estrategia como SMS → WhatsApp → Voice puede plantearse como fallback cuando la configuración lo admita, mientras que Email debe tratarse como una opción de entrega independiente, no como un paso automático dentro de esa misma cadena.

Cuándo SMS OTP no debe ser el único factor

Mejorar la entrega del OTP no significa automáticamente aumentar la seguridad de la autenticación. El SMS sigue siendo práctico y ampliamente accesible, pero puede verse afectado por riesgos como el SIM swapping y no es resistente al phishing. Para cuentas de alto valor, operaciones sensibles o escenarios con mayores requisitos de seguridad, conviene valorar factores adicionales o alternativos, como TOTP o métodos resistentes al phishing basados en WebAuthn/passkeys. NIST establece precisamente restricciones específicas para la autenticación mediante SMS y voz sobre la red telefónica pública.

Si necesita profundizar en la diferencia entre factores de autenticación, consulte la guía de EngageLab sobre 2FA y MFA . Para los conceptos y tipos de OTP, puede consultar la guía completa sobre contraseñas de un solo uso ; y para los riesgos específicos del canal móvil, la guía de SMS OTP .

Preguntas frecuentes

¿Cuál es la diferencia entre un código de verificación y un OTP?

Un código de verificación es un término general para un código usado para confirmar una acción o identidad. Un OTP es un tipo de código de verificación diseñado para utilizarse una sola vez y caducar después de un periodo limitado o tras su uso correcto.

¿Necesito una API de SMS o una API de OTP?

Depende del nivel de lógica que quiera gestionar. Una API de SMS se centra en transportar mensajes; una API de OTP puede añadir generación del código, periodo de validez, verificación y controles específicos del flujo de autenticación. Si su backend ya gestiona todo el ciclo de vida del OTP, puede usar una API de envío; si no, un servicio OTP reduce la lógica que debe desarrollar y mantener.

¿Puedo generar mi propio código OTP?

Sí. EngageLab ofrece POST /v1/codes para enviar un código pregenerado. En ese modelo, su sistema debe generar y verificar el código y aplicar sus propias políticas de caducidad, intentos y almacenamiento.

¿Se puede usar Email como fallback automático de SMS?

No dentro de la misma estrategia multicanal actual de EngageLab. Email está disponible como canal OTP, pero la API de creación de plantillas especifica que no puede combinarse con otros canales en send_channel_strategy . Si necesita Email, configure un flujo o una plantilla independiente.

¿Qué ocurre cuando un OTP caduca o ya se ha utilizado?

Debe iniciar una nueva solicitud de verificación y enviar un código nuevo. En el flujo gestionado por EngageLab, la API Verify no permite verificar de nuevo un código que ya se validó correctamente y devuelve error cuando el código ha caducado.