OTP V1 (deprecado)

Referencia de los endpoints anteriores de verificación OTP (`/protected/json/phones/verification/*`). Siguen funcionando, pero la versión recomendada es OTP v2.

Deprecado

Estos son los endpoints anteriores de verificación OTP (/protected/json/phones/verification/*). Siguen funcionando para las integraciones que ya los usan, pero es la versión anterior y se retirará más adelante — todavía no hay fecha confirmada. Para integraciones nuevas usa OTP v2 (/v2/otp*): un solo endpoint para enviar, reenviar y rotar, con hint/next en cada respuesta. Si ya integraste esta versión, la tabla de equivalencias muestra el mapeo exacto para cuando decidas migrar.

Antes de empezar

Misma autenticación que el resto de la API: header apikey.
Igual que el resto de la API, las respuestas de error llegan con su status HTTP real (400, 401, 404, 409, 410, 429, 500…) — el resultado también va en el cuerpo (success + code). Si tu integración todavía asume que todo llega en 200, hay un puente temporal: manda X-Api-Http-Semantics: 0. Las variantes XML (fuera de esta página) conservan 200 en sus propios errores sin importar el header. El detalle completo de códigos, status y la excepción conocida de saldo insuficiente está en Errores y límites.
El cuerpo no trae hint ni next como v2. Todas las respuestas comparten success, message (texto en español, no lo uses para lógica), status (campo heredado, ignóralo) y code (el identificador estable para tu lógica); las llamadas que envían un mensaje agregan además total_messages, number y credit cuando tienen éxito, más reference salvo que mandes reference: false.
No hay un solo endpoint que decida por ti: enviar, reenviar y reiniciar son tres llamadas distintas (a diferencia de v2, donde repetir POST /v2/otp reenvía automáticamente).

Enviar código

POST /protected/json/phones/verification/start genera un código nuevo y lo envía.

Campo	Tipo	Requerido	Notas
`phone_number`	string	Sí	Numérico, máximo 10 caracteres.
`country_code`	string	Sí
`company`	string	Sí	Máx. 40 caracteres.
`code_length`	integer	No	4–10. Default `4`.
`code_type`	string	No	`alphanumeric` (default), `numeric` o `letters`.
`channel`	string	No	`sms` (default) o `whatsapp`. `voice` no está disponible aquí — solo en reenvío.
`voice` / `whatsapp`	boolean	No	Forma anterior a `channel`; usa `channel` si puedes.
`expiration_date`	string	No	`YYYY-MM-DD HH:mm:ss`. Default +24h, tope +3 días.
`template`	string	No	Plantilla de mensaje `a`–`n`. Default `a`. El texto exacto de cada plantilla no está publicado en esta documentación (v2 lo reemplazó por `message` libre) — si necesitas confirmar qué recibe el usuario, pruébalo en tu cuenta con `showcode: "1"` o contacta a soporte.
`reference`	boolean	No	Incluir `reference` en la respuesta. Default `true`.
`showcode`	boolean	No	Si es `"1"` y la llamada tuvo éxito, agrega `verification_code` a la respuesta (pruebas/sandbox).

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

Respuesta (200):

{
  "success": true,
  "message": "Código generado exitosamente.",
  "status": 200,
  "code": "verification_01",
  "total_messages": 1,
  "number": "525512345678",
  "credit": 1,
  "reference": "abc123"
}

Si ya hay un código vigente para ese número, start no lo reenvía: responde error (verification_03, 429) con los segundos que faltan para que expire. Para reenviar el mismo código o mandarlo por otro canal, usa resend.

Verificar código

POST /protected/json/phones/verification/check valida el código capturado por el usuario.

Campo	Tipo	Requerido	Notas
`phone_number`	string	Sí	Numérico, máximo 10 caracteres.
`verification_code`	string	Sí	El código que capturó el usuario.

country_code no se manda aquí: la búsqueda es solo por phone_number.

curl -X POST https://api.smsmasivos.com.mx/protected/json/phones/verification/check \
  -H "Content-Type: application/json" \
  -H "apikey: TU_API_KEY" \
  -d '{
    "phone_number": "5512345678",
    "verification_code": "483920"
  }'

Respuesta (200):

{
  "success": true,
  "message": "Usuario verificado exitosamente.",
  "status": 200,
  "code": "validation_01"
}

Cada código admite 7 intentos. Al agotarlos, el número queda bloqueado hasta que pase 1 hora desde que ese código se generó o reenvió (no desde el último intento fallido — un intento incorrecto no reinicia el contador de tiempo) o hasta que reenvíes/reinicies el código explícitamente con resend (reset_code: true) o reset.

Reenviar código

POST /protected/json/phones/verification/resend reenvía el código vigente o genera uno nuevo, sin importar el estado actual (pendiente, verificado o bloqueado). Es la llamada que usarías para "no recibí el código" o para cambiar de canal.

Campo	Tipo	Requerido	Notas
`phone_number`	string	Sí	Numérico, máximo 10 caracteres.
`country_code`	string	Sí
`company`	string	Sí	Máx. 40 caracteres.
`channel`	string	No	`sms` (default), `whatsapp` o `voice` — aquí sí está disponible `voice`.
`reset_code`	boolean	No	`true` genera un código nuevo (con 7 intentos frescos); `false` (default) reenvía el mismo código.
`code_length`, `code_type`, `voice`, `whatsapp`, `expiration_date`, `template`, `reference`, `showcode`	—	No	Mismo significado que en Enviar código.

# Mismo código, por WhatsApp esta vez
curl -X POST https://api.smsmasivos.com.mx/protected/json/phones/verification/resend \
  -H "Content-Type: application/json" \
  -H "apikey: TU_API_KEY" \
  -d '{
    "phone_number": "5512345678",
    "country_code": "52",
    "company": "Mi Empresa",
    "channel": "whatsapp"
  }'

La forma de la respuesta es igual a la de Enviar código.

Reiniciar el estado

POST /protected/json/phones/verification/reset limpia la verificación en curso sin enviar nada — útil para arrancar limpio antes de un start, o para destrabar un número tras verificarlo por error.

Si ya integraste v2 para el mismo número, no llames este endpoint: comparte estado con /v2/otp y puede dejarte bloqueado con 429 otp_throttled sin que el cooldown llegue a vencer. Detalle en Migrar desde la API anterior.

Campo	Tipo	Requerido	Notas
`phone_number`	string	Sí	Numérico, máximo 10 caracteres.
`country_code`	string	Sí
`reset_code`	boolean	No	`true` genera un código nuevo (no lo envía); `false` (default) conserva el código actual, solo limpia estatus e intentos.
`code_type`, `code_length`, `showcode`	—	No	Igual que en Enviar código. Con `showcode: "1"` puedes ver el código sin que se haya enviado.

curl -X POST https://api.smsmasivos.com.mx/protected/json/phones/verification/reset \
  -H "Content-Type: application/json" \
  -H "apikey: TU_API_KEY" \
  -d '{
    "phone_number": "5512345678",
    "country_code": "52"
  }'

Respuesta (200):

{
  "success": true,
  "message": "Reinicio exitoso.",
  "status": 200,
  "code": "verification_01"
}

Errores

Los códigos usan dos namespaces: verification_* en start/resend/reset y validation_* en check (no hay una tabla exhaustiva código-por-código, a diferencia de los otp_* de v2). El resumen de categorías HTTP (expirado→410, ya verificado→409, no encontrado→404, código incorrecto→401, intentos agotados/cooldown→429, validación→400, interno→500) y la excepción de saldo insuficiente están en Errores y límites → Verificación OTP.

Excepción conocida: saldo insuficiente sale como 500 genérico, no como un código de saldo específico — a diferencia de v2, que sí lo distingue con 402.

Si estás integrando por primera vez, mejor arranca directo con OTP v2 — esta página es para mantener andando una integración que ya existe.