La verificación OTP por SMS envía un código de un solo uso al celular del usuario para confirmar su identidad. Tres endpoints especializados (POST /otp/send, /otp/verify, /otp/resend) gestionan el ciclo completo: generación, validación y reenvío, con entrega garantizada en menos de 5 segundos y fallback a WhatsApp o Voz cuando el SMS no llega.
Si tu sistema todavía usa email para confirmar identidades, estás perdiendo usuarios antes del primer login. El SMS llega aunque el dispositivo no tenga WiFi, funciona en cualquier teléfono sin apps adicionales y el código aparece en la pantalla de bloqueo sin que el usuario haga nada. Para un backend en México que necesita verificar usuarios en tiempo real, es la opción más directa.
En esta guía vas a ver los tres endpoints de la API OTP de SMS Masivos, los parámetros exactos de cada llamada, cómo manejar el fallback a WhatsApp y Voz, y cuánto cuesta integrarlo en producción.
Por qué el SMS supera al email para verificación de identidad
El problema con el email como canal OTP no es el código: es el canal. Los filtros de spam interceptan mensajes automáticos, las bandejas de entrada están llenas de ruido y el usuario tiene que salir de tu app para buscar el código en otra pantalla. Con SMS, el mensaje llega en segundos y el código aparece donde el usuario ya está mirando.
Según el RFC 6238 del IETF, los códigos sensibles al tiempo requieren un canal de entrega con latencia predecible y baja. El SMS en México cumple esa condición: entrega en menos de 5 segundos, confirmada en las especificaciones técnicas de la plataforma. Ningún cliente de correo puede garantizar eso.
Para flujos de signup, login con autenticación de dos factores o confirmación de pago, el SMS reduce la fricción de verificación en el primer intento. No hay paso intermedio: el código llega, el usuario lo ve, lo ingresa. Sin abrir Outlook, sin buscar en spam, sin esperar que el servidor SMTP procese la cola.
Para entender más sobre cómo funciona el mecanismo de los códigos OTP, consulta qué son las contraseñas OTP y cómo funcionan.
Los tres endpoints que forman el flujo OTP
La API OTP de SMS Masivos tiene un diseño modular: cada etapa del flujo de verificación tiene su propio endpoint. La generación del código, su almacenamiento y la lógica de expiración corren en la plataforma. No tienes que mantener estado en tu base de datos para rastrear qué código enviaste a qué número.
Mapa del flujo
| Endpoint | Acción | Cuándo se llama |
|---|---|---|
| POST /otp/send | Genera y envía el código OTP al número indicado | Al iniciar el flujo (login, signup, confirmación de pago) |
| POST /otp/verify | Valida el código que ingresó el usuario en tu UI | Cuando el usuario envía el código |
| POST /otp/resend | Reenvía por WhatsApp o Voz si el SMS no llegó | Cuando el usuario toca "No recibí" en tu app |
Autenticación: header apikey: TU_API_KEY en todas las peticiones. No es Authorization: Bearer. La base URL es https://api.smsmasivos.com.mx. Sin prefijo /api/v2/.
Paso 1: Envía el código con POST /otp/send
Este endpoint inicia el flujo. La plataforma genera el código único, lo almacena con su tiempo de expiración configurado y lo envía al número indicado. Tu backend solo llama el endpoint: el resto lo hace la API.
curl -X POST https://api.smsmasivos.com.mx/otp/send \
-H "apikey: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "5512345678",
"country_code": "52",
"company": "Tu Empresa",
"template": "a",
"code_length": 6,
"code_type": "numeric"
}'Respuesta exitosa:
{
"success": true,
"message": "Código enviado",
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}Respuesta con error (número inválido o fuera de cobertura):
{
"success": false,
"message": "phone_number inválido o fuera de cobertura",
"code": "verification_send_01"
}Parámetros obligatorios: phone_number, country_code, company y template.
phone_number: 10 dígitos en formato nacional (sin +52 ni 00). Cobertura exclusiva en México.country_code: código de país sin + ni 00. Para México:"52".company: nombre de tu empresa que aparece en el cuerpo del SMS.template: identifica la plantilla de mensaje configurada en tu cuenta.code_length(opcional): longitud del código. Por defecto: 6 dígitos.
El parámetro code_type acepta tres valores: "numeric" para códigos de solo números, "alphanumeric" para combinación de letras y números, y "letters" para códigos de solo letras. Para la mayoría de flujos, "numeric" reduce fricción porque el usuario lo ingresa desde el teclado numérico sin cambiar de vista.
Paso 2: Verifica el código con POST /otp/verify
Cuando el usuario ingresa el código en tu pantalla, tu backend llama a este endpoint. La respuesta confirma si el código es válido, si ya expiró o si el número de intentos se agotó. No necesitas implementar tu propio contador.
curl -X POST https://api.smsmasivos.com.mx/otp/verify \
-H "apikey: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "5512345678",
"company": "Tu Empresa",
"verification_code": "482916"
}'Respuesta: código válido:
{
"success": true,
"data": { "verified": true },
"message": "Código válido"
}Respuesta: código expirado:
{
"success": false,
"message": "El código ha expirado",
"code": "verification_check_01"
}Respuesta: intentos agotados:
{
"success": false,
"message": "Número de intentos agotado",
"code": "verification_check_02"
}El parámetro es verification_code, no code ni otp_code. Si la validación falla, la API devuelve el motivo específico: código incorrecto, código expirado o intentos agotados. Con esa respuesta tu UI puede mostrar el mensaje correcto al usuario sin adivinanzas.
Paso 3: Gestiona el reenvío con POST /otp/resend
No todos los SMS llegan al primer intento. Portabilidad numérica, señal intermitente, operadores con congestión. El endpoint /otp/resend cubre ese escenario con fallback a WhatsApp y Voz.
Una regla importante: el reenvío siempre lo dispara una acción del usuario, no un timer automático del sistema. El flujo correcto en tu UI es un botón "No recibí" visible después de los primeros 15-20 segundos, no un countdown automático que dispara el reenvío sin que el usuario lo pida.
# Primera opción: reenvío por WhatsApp
# (el usuario toca "No recibí" por primera vez)
curl -X POST https://api.smsmasivos.com.mx/otp/resend \
-H "apikey: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "5512345678",
"country_code": "52",
"company": "Tu Empresa",
"whatsapp": true
}'# Segunda opción: reenvío por Voz robótica
# (el usuario toca "No recibí" por segunda vez)
curl -X POST https://api.smsmasivos.com.mx/otp/resend \
-H "apikey: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "5512345678",
"country_code": "52",
"company": "Tu Empresa",
"voice": true
}'Respuesta exitosa (ambos canales):
{
"success": true,
"message": "Código reenviado"
}El flujo de escalación recomendado: SMS en el primer intento, WhatsApp si el usuario reporta que no llegó, Voz robótica si WhatsApp tampoco llegó. La voz robótica dicta el código por llamada al número del usuario. La lógica de cuándo ofrecer cada canal la controlas tú en tu frontend con dos interacciones del mismo botón "No recibí".
Personaliza el código: tipo, longitud y plantillas
Cuatro parámetros definen el comportamiento del código que genera la API:
- Tipo (
code_type): numérico, alfanumérico o solo letras. El tipo numérico minimiza errores de transcripción porque el usuario no tiene que cambiar de teclado. - Longitud (
code_length): define cuántos caracteres tiene el código. Códigos de 4 dígitos tienen menor fricción para confirmaciones de baja sensibilidad; 6-8 dígitos son estándar para accesos y transacciones de mayor valor. - Plantilla (
template): el texto del SMS que rodea al código. Puedes tener múltiples plantillas configuradas en tu cuenta para distintos flujos: signup, recuperación de contraseña, confirmación de pago. Cada llamada a/otp/sendespecifica cuál usar. - Canal de fallback: SMS por defecto, WhatsApp o Voz en
/otp/resendsegún la acción del usuario.
El tiempo de expiración del código también es configurable en tu cuenta. Para flujos de pago donde la seguridad es crítica, expiraciones cortas de 2-3 minutos son el estándar. Para signup donde hay más fricción de usuario, 5-10 minutos reducen abandono sin sacrificar demasiada seguridad.
Para los esquemas de respuesta completos y los códigos de error, revisa la documentación técnica de la API. Para una guía orientada a casos de uso por industria, consulta la guía de códigos de verificación para empresas.
Cuánto cuesta integrar OTP por SMS
El costo va por volumen mensual de SMS enviados. Sin cuota de activación ni licencia de API.
Precio por envío SMS (aplica a OTP, MXN + IVA)
| Volumen mensual | Precio por SMS | Ejemplo: 1,000 envíos |
|---|---|---|
| Desde 500 | $0.90 MXN + IVA | $1,044 MXN + IVA |
| Desde 1,000 | $0.77 MXN + IVA | $893 MXN + IVA |
| Desde 10,000 | $0.68 MXN + IVA | $789 MXN + IVA |
El volumen mínimo de compra es 500 SMS. El saldo no expira: los créditos que compras hoy siguen disponibles meses después si no los consumes todos.
Un dato práctico: el costo real por verificación exitosa puede ser mayor al precio unitario si algunos usuarios necesitan reenvío. Para calcular tu presupuesto real, multiplica el precio por SMS por el volumen esperado más un margen conservador para intentos que requieran reenvío a WhatsApp o Voz.
Obtén tu API Key y prueba el endpoint OTP en 5 minutos
SMS Masivos es una plataforma mexicana de mensajería empresarial con 15 años en México, conexión directa a los 5 principales carriers en México, tasa de entrega del 99% y saldo que no expira. Su API OTP está diseñada específicamente para flujos de autenticación en apps y sistemas de backend.
Preguntas frecuentes sobre la integración OTP
¿Necesito un desarrollador para integrar la API OTP?
Sí. La API OTP requiere que tu backend haga peticiones HTTP REST. No es una solución no-code: necesitas a alguien que pueda hacer llamadas a endpoints desde tu servidor. Un desarrollador con experiencia básica en APIs REST lo integra en menos de un día de trabajo.
¿Funciona para números de celular fuera de México?
No. La cobertura es exclusiva en México. Si tu app tiene usuarios en otros países y necesitas verificación OTP internacional, esa limitación debes evaluarla antes de integrar.
¿Qué pasa si el código expira mientras el usuario lo busca?
El endpoint /otp/verify devuelve un error de expiración específico. En tu UI puedes mostrar el tiempo restante con un contador visual o simplemente un botón "Solicitar nuevo código" que llame a /otp/send de nuevo. La plataforma invalida automáticamente el código anterior cuando se emite uno nuevo.
¿El reenvío por WhatsApp es un mensaje de marketing o transaccional?
Transaccional. El fallback de OTP por WhatsApp usa la API de WhatsApp Business para mensajes transaccionales, con ventana de entrega diferente a los mensajes de marketing. El contenido del OTP ya está configurado en la plataforma: no necesitas crear una plantilla adicional en tu cuenta de WhatsApp Business.
¿Puedo usar la misma cuenta para múltiples apps o flujos?
Sí. El parámetro template en /otp/send te permite seleccionar qué plantilla de mensaje usar por llamada. Puedes configurar plantillas distintas para signup, recuperación de contraseña y confirmación de pago, y elegir cuál usar según el flujo de tu app.
Si tu empresa ya usa SMS masivos para marketing y quieres añadir verificación OTP al mismo stack, ve la página completa de verificación OTP con detalles técnicos y casos de uso. Para contexto general sobre autenticación de dos factores por SMS, el post qué son las contraseñas OTP cubre la teoría detrás del mecanismo.
