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 →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.
https://api.tu-dominio.comLa misma dirección donde está alojada esta documentación, sin
/developers.
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.
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.
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.
Envía un código.
/otp/sendSolicita 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. |
{
"target": "persona@example.com",
"channel": "email",
"format": "alphanumeric",
"recordId": "checkout-1042"
}
{
"message": "OTP accepted for delivery",
"expiresIn": 300,
"expiresAt": "2026-09-12T15:05:00.000Z",
"recordId": "507f1f77bcf86cd799439011",
"challengeId": "507f1f77bcf86cd799439011"
}
Confirma la respuesta.
/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.
{
"target": "persona@example.com",
"code": "A7B2C9D4",
"challengeId": "507f1f77bcf86cd799439011"
}
{
"valid": true,
"recordId": "507f1f77bcf86cd799439011",
"challengeId": "507f1f77bcf86cd799439011",
"verifiedAt": "2026-09-12T15:01:00.000Z"
}
{
"valid": false,
"reason": "Invalid or expired code"
}
Consulta la actividad.
/otp/recordsConsulta 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. |
GET /otp/records?page=1&limit=10&verified=true
{
"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
}
}
Mide las verificaciones.
/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.
GET /otp/stats?dateFrom=2026-09-01T00:00:00Z&dateTo=2026-09-30T23:59:59Z
{
"total": 10,
"verified": 8,
"unverified": 2,
"verificationRate": "80.00",
"byChannel": {
"email": 10
}
}
Comprueba el saldo.
/otp/token-infoConsulta 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.
GET /otp/token-info
{
"tokens": 100,
"tokensUsed": 15,
"remainingTokens": 85,
"hasUnlimitedTokens": false
}
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. |
{
"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
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ó.
}