Integra OTP por SMS en Perú.

Acceso, tokens y plantillas

El registro requiere aprobación previa. Desde tu panel puedes crear tokens con vencimiento, revocarlos y consultar la referencia de la API. El token completo se muestra una sola vez al crearlo. Las solicitudes usan HTTPS y el encabezado Authorization: Bearer TOKEN.

Guarda el token en el servidor de tu aplicación, nunca en JavaScript público, aplicaciones móviles distribuidas ni repositorios. Para integrar, solicita la aprobación de una plantilla con el marcador {{code}}. Usa el identificador real de esa plantilla en cada envío.

Ejemplo de plantilla: MiApp: tu codigo es {{code}}. No lo compartas. Solo se permiten plantillas aprobadas y texto compatible; los requisitos completos están en el panel.

Enviar un código OTP por SMS

La URL base de la API es https://api.peruotp.com. Envía POST /v1/otp con el teléfono en formato +519XXXXXXXX y el ID de una plantilla aprobada. Al omitir code, PeruOTP genera un código de seis dígitos.

curl -X POST "https://api.peruotp.com/v1/otp" \
  -H "Authorization: Bearer $PERUOTP_TOKEN" \
  -H "Idempotency-Key: acceso-usuario-001" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+519XXXXXXXX","template_id":"TU_PLANTILLA"}'

La respuesta HTTP 202 incluye id, state y expires_at. El estado inicial es queued: la solicitud se aceptó en la cola; aún no confirma que el teléfono haya recibido un SMS.

Repetir una solicitud sin duplicar el envío

Usa una Idempotency-Key de 8 a 128 caracteres por operación. Si repites la misma solicitud, conserva la misma clave y el mismo cuerpo. No reutilices esa clave para otro teléfono, plantilla o código.

Enviar el código generado por tu sistema

Agrega el campo code al mismo cuerpo JSON, con un valor de 4 a 8 dígitos. En ese caso, tu sistema se encarga de la generación, vigencia y verificación. El endpoint de verificación de PeruOTP se utiliza para los códigos generados por PeruOTP.

Verificar un OTP generado por PeruOTP

Envía el código que ingresó el usuario a POST /v1/otp/ID_DEL_ENVIO/verify, con el mismo token de tu cuenta. La respuesta indica verified: true o false.

curl -X POST "https://api.peruotp.com/v1/otp/ID_DEL_ENVIO/verify" \
  -H "Authorization: Bearer $PERUOTP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"CODIGO_RECIBIDO"}'

El código vence a los cinco minutos desde la solicitud, permite hasta cinco intentos y solo puede validarse una vez. El tiempo en cola forma parte de esos cinco minutos. La verificación del código y el estado de transporte del SMS son datos distintos.

Consultar el estado del mensaje

Consulta GET /v1/messages/ID_DEL_ENVIO con el token Bearer. Para listar tus plantillas disponibles, usa GET /v1/templates.

queued

En cola, con un crédito reservado.

dispatching

Un envío está en proceso.

sent

Nuestra infraestructura aceptó el envío. No constituye un acuse de entrega al móvil.

failed

El envío falló antes de presentarse para transmisión; el crédito se devuelve.

expired

La solicitud venció en cola; el crédito se devuelve.

uncertain

No se pudo determinar el resultado. El crédito queda reservado mientras se investiga; no se reenvía automáticamente.

Cobertura, límites y créditos

La cobertura actual es Perú, para números móviles con prefijo +51 y nueve dígitos que comienzan en 9. Las solicitudes pasan por una cola; el tiempo efectivo depende de la capacidad disponible y de la red. No se garantiza entrega inmediata.

Los límites por minuto y por día se asignan a cada cuenta. Cada solicitud reserva un crédito; los paquetes se expresan en soles y se gestionan desde el panel. Consulta allí la oferta vigente y las condiciones de habilitación de tu cuenta.

La referencia de endpoints, los tokens y la gestión de plantillas están en tu panel de desarrollador. También puedes consultar la especificación OpenAPI.