Construya con Narvark.
Una API RESTful limpia para enviar y verificar OTP por WhatsApp, SMS, email y voz, con SDK para Node.js, Python, PHP y Go.
Operativo en 5 minutos.
Sin acuerdos con operadores, sin configuración SMPP, sin alta en WhatsApp Business. Obtenga una clave de API y empiece.
Solicite acceso a través del formulario de demo de Narvark y nuestro equipo le indicará el proceso de onboarding adecuado y los datos de acceso a la API.
Haga un POST a /v1/otp/send con un número de teléfono y un canal. El OTP se envía en menos de 200ms.
Cuando el usuario envíe su código, haga un POST a /v1/otp/verify. Recibirá un booleano valid en milisegundos.
Autenticación de la API
Todas las solicitudes a la API deben incluir su clave de API en la cabecera Authorization como Bearer token. Las claves de API están vinculadas a un entorno (test / live).
Utilice las claves nvk_test_sk_ para desarrollo: no se envía ningún OTP y no se aplican cargos. Cambie a nvk_live_sk_ para producción.
Enviar OTP
Envía una contraseña de un solo uso a un número de teléfono o una dirección de email por el canal especificado. Devuelve un ID de OTP para el seguimiento del estado y la verificación.
Parámetros de la solicitud
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| to | string | obligatorio | Número de teléfono del destinatario en formato E.164 (p. ej., +447911123456) o dirección de email. |
| channel | string | obligatorio | Canal de entrega. Uno de: whatsapp, sms, email, voice. |
| ttl | integer | opcional | Caducidad del código en segundos. Por defecto: 300. Mín.: 60. Máx.: 86400. |
| fallback | string | opcional | Canal de respaldo si el principal falla. P. ej., "sms" cuando el principal es "whatsapp". |
| code_length | integer | opcional | Longitud del código OTP. Por defecto: 6. Opciones: 4, 6, 8. |
| template | string | opcional | Solo WhatsApp. Nombre de la plantilla de mensaje preaprobada. Por defecto: "otp_verification". |
| metadata | object | opcional | Pares clave-valor arbitrarios asociados al OTP. Se devuelven en los webhooks y en las respuestas de estado. Máx. 10 claves. |
Respuesta
{
"id": "otp_wa_k9x2m",
"status": "sent",
"channel": "whatsapp",
"to": "+447911123456",
"expires_at": "2026-03-27T16:28:00Z",
"latency_ms": 187,
"created_at": "2026-03-27T16:23:00Z"
}
Verificar OTP
Verifica un código enviado por el usuario frente al OTP identificado por su ID. Devuelve si el código es válido y si ya se ha utilizado.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| id | string | obligatorio | El ID de OTP devuelto por el endpoint de envío. |
| code | string | obligatorio | El código enviado por el usuario. Acepta formato con espacios (p. ej., "492 817") o sin formato ("492817"). |
{
"id": "otp_wa_k9x2m",
"valid": true,
"consumed": true,
"verified_at": "2026-03-27T16:24:12Z"
}
{
"valid": false,
"error": "code_invalid",
"attempts_remaining": 2
}
Errores y límites de frecuencia
Narvark utiliza códigos de estado HTTP estándar. Todas las respuestas de error incluyen un código error legible por máquina y un message legible por personas.
| Código | Error | Descripción |
|---|---|---|
| 400 | invalid_request | Parámetros de la solicitud ausentes o mal formados. |
| 401 | unauthorized | Clave de API no válida o ausente. |
| 429 | rate_limited | Demasiadas solicitudes. Por defecto: 1,000 req/min por clave. Enterprise: ilimitado. |
| 500 | internal_error | Error del servidor de Narvark. Se reintenta automáticamente de forma interna; poco frecuente. |
Webhooks
Narvark envía webhooks POST en tiempo real a su endpoint para los eventos del ciclo de vida del OTP: enviado, entregado, leído, verificado, caducado y fallido.
"event": "otp.delivered",
"otp_id": "otp_wa_k9x2m",
"channel": "whatsapp",
"to": "+447911123456",
"timestamp": "2026-03-27T16:23:01Z",
"latency_ms": 187,
"metadata": { "user_id": "usr_abc123" }
}
Verifique la autenticidad de los webhooks con la cabecera X-Narvark-Signature: una firma HMAC-SHA256 del cuerpo bruto de la solicitud generada con su secreto de webhook.