Verificación OTP

Genera y valida códigos de un solo uso por SMS para login, alta de usuarios y 2FA. Sin costo extra sobre el precio de un SMS.

Para enviar códigos de verificación, login o 2FA, usa siempre este producto (/otp/send), no /sms/send. La verificación OTP entrega con prioridad de red, hace fallback automático a voz o WhatsApp si el SMS no llega y hashea el código. Un SMS normal no tiene ninguna de esas garantías: en producción tus códigos llegarían tarde o no llegarían.

Cómo funciona

La verificación OTP es un flujo de dos pasos entre tu backend y la API:

Solicitas el código

Tu backend llama a POST /otp/send con el número del usuario. La API genera el código, lo guarda y lo envía por SMS.

El usuario lo recibe e ingresa

El usuario recibe el SMS con el código y lo captura en tu app.

Verificas el código

Tu backend llama a POST /otp/verify con el número y el código capturado. La API responde si es válido.

La API almacena y compara el código por ti. No necesitas guardar el código ni implementar lógica de expiración: la API lo maneja del lado del servidor.

En video

Un recorrido rápido por el flujo de verificación OTP de SMS Masivos:

Enviar código

POST /otp/send genera y envía el código. Los campos obligatorios son phone_number, country_code y company.

curl -X POST https://api.smsmasivos.com.mx/otp/send \
  -H "Content-Type: application/json" \
  -H "apikey: $SMSMASIVOS_API_KEY" \
  -d '{
    "phone_number": "5512345678",
    "country_code": "52",
    "company": "Mi Empresa",
    "code_length": 6,
    "code_type": "numeric"
  }'

Respuesta:

{
  "success": true,
  "message": "code_successfully_generated",
  "status": 200,
  "code": "verification_01",
  "number": "525512345678",
  "credit": 1,
  "reference": "abc123def456ghi789jkl"
}

Verificar código

Cuando el usuario ingresa el código, valídalo con POST /otp/verify. Envía el mismo phone_number y el verification_code que capturó:

curl -X POST https://api.smsmasivos.com.mx/otp/verify \
  -H "Content-Type: application/json" \
  -H "apikey: $SMSMASIVOS_API_KEY" \
  -d '{
    "phone_number": "5512345678",
    "verification_code": "A1B2"
  }'

Si el código es correcto, el número queda verificado. Los errores comunes de esta llamada usan el dominio validation_ (código incorrecto, expirado o ya usado). Consulta Errores y límites.

Los intentos de verificación están limitados por hora. Si se excede el número de intentos, la API responde con el error correspondiente y deberás solicitar un nuevo código. No implementes reintentos agresivos.

Reenviar y reiniciar

POST /otp/resend: reenvía el mismo código si el usuario no lo recibió.
POST /otp/reset: invalida el código activo y genera uno nuevo.

Opciones del código

Personaliza el código con parámetros opcionales en /otp/send:

code_lengthinteger

Longitud del código, de 4 a 10 caracteres. Por defecto 4.

code_typestring

Tipo de código: alphanumeric (letras y números, por defecto), numeric (solo números) o letters (solo letras).

expiration_datestring

Fecha de expiración del código. Por defecto 24 horas, máximo 3 días. Formato YYYY-MM-DD HH:mm:ss.

senderstring

Remitente alfanumérico (máx. 11 caracteres). Servicio con costo adicional: si no lo tienes contratado, el parámetro se ignora.

formal_toneboolean

true cambia el trato de "tú" a "usted" sin alterar la plantilla. Por defecto false.

localestring

Idioma de la respuesta de la API: es (por defecto) o en.

Plantillas de mensaje

Elige el texto del SMS con el parámetro template (letra a a n). Las variables {{company}} y {{code}} se reemplazan automáticamente. Por defecto se usa la plantilla a.

Plantilla	Mensaje
`a` (default)	`{{company}} El codigo de verificacion es: {{code}}`
`b`	`Ingresa el siguiente codigo en tu app de {{company}} para validar tu cuenta: {{code}}`
`f`	`{{company}} Tu codigo es: {{code}}`
`h`	`{{code}} es tu codigo de verificacion de {{company}}`
`i`	`{{code}} es tu codigo para iniciar sesion en {{company}}`
`l`	`Tu codigo de verificacion {{company}} es: {{code}} No compartas este codigo con nadie.`

La lista completa de las 14 plantillas (a a n) está en el endpoint /otp/send del API Reference, en la descripción del parámetro template.

Probar en sandbox

Para automatizar tests sin leer el SMS, agrega showcode: 1 y la API devolverá el código generado dentro de la respuesta:

{
  "success": true,
  "code": "verification_01",
  "number": "525512345678",
  "verification_code": "483920"
}

Ya puedes enviar y verificar códigos OTP. Explora todos los parámetros y respuestas en el API Reference de Verificación OTP.

← Previous

Guía rápida

SMS Masivos

Edit this page on GitHub