OTPS Senvia /developersOpenAPI JSON ↗
SENVIA / INTEGRATION API

Senvia Developers

Envía un código por correo y valida la respuesta desde tu software. Una integración pequeña, con el contexto de cada empresa separado.

Crear tu primera integración →
01Solicita el códigoLa API acepta el envío
02Tu usuario lo recibePor correo electrónico
03Valida una sola vezContinúa tu flujo
PRIMEROS PASOS

Del backend al buzón.

Necesitas una cuenta, una empresa activa con email habilitado y créditos disponibles. Genera una clave API para esa empresa y usa su identificador junto con la clave. Conserva ambos en el servidor de tu aplicación.

URL basehttps://api.tu-dominio.comLa misma dirección donde está alojada esta documentación, sin /developers.
TERMINAL · cURL
curl -X POST "$SENVIA_BASE_URL/otp/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SENVIA_API_KEY" \
  -H "x-project-id: $SENVIA_COMPANY_ID" \
  -d '{"target":"persona@example.com","channel":"email","format":"alphanumeric"}' 

Guarda el challengeId recibido y úsalo al validar. La respuesta de envío confirma la aceptación, no la entrega del correo.

ACCESO

Dos headers. Una empresa.

Los cinco endpoints requieren ambos headers en cada petición. La clave debe corresponder a esa empresa. Tanto la empresa como su cuenta propietaria deben estar activas.

Campo Descripción
x-api-key Clave secreta de esta empresa, con prefijo snv_. No debe aparecer en código de navegador, apps distribuidas ni repositorios.
x-project-id ID de la empresa, por ejemplo PRJ_ABC123DEF456. El nombre del header se conserva por compatibilidad.
Content-Type Usa application/json para solicitudes POST.

Cada empresa mantiene créditos, canales, límites y plantillas propios. Selecciona siempre el ID de la empresa que debe recibir el consumo. Una clave de la empresa A no permite acceder a la empresa B, aunque ambas pertenezcan a tu cuenta. El ID de empresa es un identificador, no un segundo secreto.

Generación, rotación y revocaciónLa clave se entrega una sola vez al generarla desde la gestión de la empresa. Guárdala en los secretos de tu servidor. Rotarla invalida la anterior; revocarla bloquea el acceso hasta generar otra. Usa siempre HTTPS. No necesitas Firebase ni un JWT para estos cinco endpoints.

Compatibilidad: las empresas anteriores a las claves independientes pueden seguir usando su clave de cuenta. Al generar o revocar una clave propia, ese acceso de cuenta queda deshabilitado para esa empresa. Las empresas nuevas requieren su propia clave.

REFERENCIA / ENVIAR

Envía un código.

POST/otp/send

Solicita un OTP para un destinatario. Se reserva un crédito al aceptar la solicitud, salvo empresas con créditos ilimitados.

Campo Descripción
target · requerido Correo del destinatario, máximo 254 caracteres, sin espacios.
channel · requeridoenum<string> Un solo valor: email o whatsapp, nunca una lista. WhatsApp devuelve 503 mientras esté desactivado o no se haya implementado su transporte. No consume créditos.
format · opcionalenum<string> alphanumeric: 8 caracteres, siempre letras mayúsculas y números. numeric: 6 dígitos. Predeterminado: alphanumeric.
recordId · opcional Referencia de tu sistema, hasta 128 caracteres. No es una clave de idempotencia.
countryCode · opcional Formato + seguido de 1 a 4 dígitos. No se necesita para email.
El tiempo empieza al aceptarLa vigencia depende de la configuración de la empresa. Incluye el tiempo en cola. El ejemplo usa 300 segundos.
Solicitud de ejemplo

Email disponible. WhatsApp pendiente de implementación.

SOLICITUD · JSON
{
  "target": "persona@example.com",
  "channel": "email",
  "format": "alphanumeric",
  "recordId": "checkout-1042"
}
201 · ACCEPTED FOR DELIVERY
{
  "message": "OTP accepted for delivery",
  "expiresIn": 300,
  "expiresAt": "2026-09-12T15:05:00.000Z",
  "recordId": "507f1f77bcf86cd799439011",
  "challengeId": "507f1f77bcf86cd799439011"
}
REFERENCIA / VALIDAR

Confirma la respuesta.

POST/otp/verify

Envía exactamente el código que escribió el usuario y el challengeId devuelto al crear el OTP. El destinatario debe coincidir.

Campo Descripción
target · requerido El mismo correo de la solicitud de envío.
code · requerido Código de 6 dígitos o 8 caracteres alfanuméricos. Conserva las mayúsculas.
challengeId · recomendado Identificador de 24 caracteres hexadecimales devuelto por /otp/send.
recordId · legado Alternativa de compatibilidad. Si no envías un identificador, se busca el desafío más reciente del destinatario.

Un código se consume una sola vez. Hay un máximo de cinco intentos por desafío. Un código vencido se rechaza inmediatamente, aunque su limpieza física siga pendiente.

Lee valid, no solo el HTTPUna validación incorrecta también devuelve 200, con valid: false.
SOLICITUD · JSON
{
  "target": "persona@example.com",
  "code": "A7B2C9D4",
  "challengeId": "507f1f77bcf86cd799439011"
}
200 · CÓDIGO VÁLIDO
{
  "valid": true,
  "recordId": "507f1f77bcf86cd799439011",
  "challengeId": "507f1f77bcf86cd799439011",
  "verifiedAt": "2026-09-12T15:01:00.000Z"
}
200 · NO VÁLIDO
{
  "valid": false,
  "reason": "Invalid or expired code"
}
REFERENCIA / REGISTROS

Consulta la actividad.

GET/otp/records

Consulta metadatos de uso de la empresa. Los registros no incluyen códigos, hashes ni contenido del correo.

Campo Descripción
page / limit Página desde 1 (máximo 100000). Tamaño desde 1 hasta 100. Valores predeterminados: 1 y 10.
channelenum<string> Filtro opcional: email o whatsapp.
verifiedboolean Filtro opcional: true o false. No es un enum.
dateFrom / dateTo Fechas ISO 8601 opcionales. Se filtra por fecha de creación del evento.
Filtros del ejemplo
SOLICITUD
GET /otp/records?page=1&limit=10&verified=true
200 · EJEMPLO
{
  "records": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "projectId": "PRJ_ABC123DEF456",
      "challengeId": "507f1f77bcf86cd799439011",
      "channel": "email",
      "recordId": "checkout-1042",
      "verified": true,
      "verifiedAt": "2026-09-12T15:01:00.000Z",
      "deliveredAt": "2026-09-12T15:00:02.000Z",
      "createdAt": "2026-09-12T15:00:00.000Z",
      "updatedAt": "2026-09-12T15:01:00.000Z",
      "__v": 0
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "pages": 1
  }
}
REFERENCIA / ESTADISTICAS

Mide las verificaciones.

GET/otp/stats

Agrega los eventos de la empresa. Acepta dateFrom y dateTo en ISO 8601. La tasa se devuelve como texto con dos decimales, o como número 0 si no hay eventos.

Estos datos permanecen aunque se borre el desafío vencido o consumido.

SOLICITUD
GET /otp/stats?dateFrom=2026-09-01T00:00:00Z&dateTo=2026-09-30T23:59:59Z
200 · EJEMPLO
{
  "total": 10,
  "verified": 8,
  "unverified": 2,
  "verificationRate": "80.00",
  "byChannel": {
    "email": 10
  }
}
REFERENCIA / CREDITOS

Comprueba el saldo.

GET/otp/token-info

Consulta el saldo de la empresa antes de iniciar tu flujo. Esta consulta no reserva créditos: otra solicitud puede consumir saldo antes del envío.

remainingTokens: -1 representa crédito ilimitado cuando hasUnlimitedTokens es true.

SOLICITUD
GET /otp/token-info
200 · EJEMPLO
{
  "tokens": 100,
  "tokensUsed": 15,
  "remainingTokens": 85,
  "hasUnlimitedTokens": false
}
OPERACIÓN

Diseña para las respuestas.

Campo Descripción
400 Campos inválidos, canal deshabilitado, saldo insuficiente o empresa inactiva al reservar.
401 / 403 Credenciales ausentes, inválidas o sin acceso a la empresa.
404 Recurso no encontrado.
429 Límite de solicitudes. Respeta Retry-After cuando esté presente; en otro caso aplica espera progresiva.
500 / 503 Fallo interno, protección temporalmente no disponible o canal sin implementar.
400 · EJEMPLO DE ERROR
{
  "statusCode": 400,
  "timestamp": "2026-09-12T15:00:00.000Z",
  "path": "/otp/send",
  "method": "POST",
  "message": "Canal deshabilitado para esta empresa",
  "originalMessage": "Channel disabled for this company",
  "details": {
    "status": 400,
    "originalMessage": "Channel disabled for this company"
  }
}

Las respuestas de protección temprana pueden incluir solo message. No dependas del texto para decidir: usa el estado HTTP y, al validar, valid.

Reintentos con intención

Un timeout de envío no prueba que la solicitud falló. POST /otp/send no es idempotente: repetirlo puede crear otro código y consumir otro crédito. No uses recordId para deduplicar. Conserva challengeId cuando recibas la respuesta y ofrece un reenvío explícito a tu usuario.

La cola reintenta la entrega internamente. No hagas polling de /verify: cada intento cuenta. La vigencia nunca se extiende por un reintento.

Ejemplo de validación desde tu servidor

JAVASCRIPT · FETCH
const response = await fetch(`${process.env.SENVIA_BASE_URL}/otp/verify`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.SENVIA_API_KEY,
    'x-project-id': process.env.SENVIA_COMPANY_ID
  },
  body: JSON.stringify({ target, code, challengeId })
});
if (!response.ok) throw new Error(`Senvia: HTTP ${response.status}`);
const result = await response.json();
if (result.valid) {
  // Continúa la operación de tu usuario.
} else {
  // Solicita corregir el código o reenviarlo si expiró.
}