Saltar al contenido
REST API v1

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.

https://api.narvark.com/v1
Inicio rápido

Operativo en 5 minutos.

Sin acuerdos con operadores, sin configuración SMPP, sin alta en WhatsApp Business. Obtenga una clave de API y empiece.

// paso 01
Obtenga su clave de API

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.

// paso 02
Envíe su primer OTP

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.

// paso 03
Verifique el código

Cuando el usuario envíe su código, haga un POST a /v1/otp/verify. Recibirá un booleano valid en milisegundos.

// autenticación

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).

HTTP Header
Authorization: Bearer nvk_live_sk_a1b2c3d4e5f6g7h8i9j0
cURL Example
curl https://api.narvark.com/v1/otp/send \ -H "Authorization: Bearer nvk_live_sk_your_key" \ -H "Content-Type: application/json" \ -d '{"to": "+447911123456", "channel": "sms"}'

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.

// endpoints de otp

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.

POST /v1/otp/send

Parámetros de la solicitud

ParámetroTipoObligatorioDescripción
tostringobligatorioNúmero de teléfono del destinatario en formato E.164 (p. ej., +447911123456) o dirección de email.
channelstringobligatorioCanal de entrega. Uno de: whatsapp, sms, email, voice.
ttlintegeropcionalCaducidad del código en segundos. Por defecto: 300. Mín.: 60. Máx.: 86400.
fallbackstringopcionalCanal de respaldo si el principal falla. P. ej., "sms" cuando el principal es "whatsapp".
code_lengthintegeropcionalLongitud del código OTP. Por defecto: 6. Opciones: 4, 6, 8.
templatestringopcionalSolo WhatsApp. Nombre de la plantilla de mensaje preaprobada. Por defecto: "otp_verification".
metadataobjectopcionalPares clave-valor arbitrarios asociados al OTP. Se devuelven en los webhooks y en las respuestas de estado. Máx. 10 claves.
cURLCopy
curl -X POST https://api.narvark.com/v1/otp/send \ -H "Authorization: Bearer nvk_live_sk_your_key" \ -H "Content-Type: application/json" \ -d '{ "to": "+447911123456", "channel": "whatsapp", "fallback": "sms", "ttl": 300, "metadata": { "user_id": "usr_abc123", "action": "login" } }'
Node.jsCopy
import Narvark from '@narvark/node'; const client = new Narvark('nvk_live_sk_your_key'); const otp = await client.otp.send({ to: '+447911123456', channel: 'whatsapp', fallback: 'sms', ttl: 300, }); console.log(otp.id); // otp_wa_k9x2m
PythonCopy
import narvark client = narvark.Client("nvk_live_sk_your_key") otp = client.otp.send( to="+447911123456", channel="whatsapp", fallback="sms", ttl=300, ) print(otp.id) # otp_wa_k9x2m

Respuesta

200 OK

{
  "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.

POST /v1/otp/verify
ParámetroTipoObligatorioDescripción
idstringobligatorioEl ID de OTP devuelto por el endpoint de envío.
codestringobligatorioEl código enviado por el usuario. Acepta formato con espacios (p. ej., "492 817") o sin formato ("492817").
cURL
curl -X POST https://api.narvark.com/v1/otp/verify \ -H "Authorization: Bearer nvk_live_sk_your_key" \ -H "Content-Type: application/json" \ -d '{"id": "otp_wa_k9x2m", "code": "492817"}'
200 OK

{
  "id": "otp_wa_k9x2m",
  "valid": true,
  "consumed": true,
  "verified_at": "2026-03-27T16:24:12Z"
}
400 Invalid Code

{
  "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ódigoErrorDescripción
400invalid_requestParámetros de la solicitud ausentes o mal formados.
401unauthorizedClave de API no válida o ausente.
429rate_limitedDemasiadas solicitudes. Por defecto: 1,000 req/min por clave. Enterprise: ilimitado.
500internal_errorError 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.

Webhook Payload
{
  "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.