Desarrolladores
Construye con las APIs de Inalambria
APIs REST para SMS, RCS, WhatsApp y Email, conexiones SMPP y envíos por archivo. Autenticación con token, payloads JSON y notificaciones de estado en tu propia infraestructura.
Introducción
Cada servicio tiene su propio host:
| Servicio | Host |
|---|---|
| SMS, RCS, token y monitoreo | https://rest.inalambria.com |
https://multichannel.inalambria.com | |
https://emailrest.inalambria.com | |
| SMPP | smsc.inalambria.com · smscssl.inalambria.com |
Requisitos: una cuenta de envío configurada por Inalambria, credenciales de autenticación y conexión HTTPS. Algunos servicios (RCS, notificaciones, monitoreo, archivos) requieren habilitación previa.
Esta página resume la referencia oficial. Para el detalle completo de cada endpoint consulta docs.inalambria.com .
Inicio rápido
- 1
Solicita tu cuenta
Inalambria configura tu cuenta de envío y te entrega usuario y contraseña.
- 2
Obtén el token
POST /tokencon Basic Authentication ygrant_type: password. - 3
Envía tu primer SMS
POST /mtmessagecon el Bearer Token. Guarda elTransactionNumber. - 4
Recibe los estados
Activa el webhook de cuenta o el callback por petición.
# 1. Solicita el token (Basic Authentication con tus credenciales)
TOKEN=$(curl -s -X POST https://rest.inalambria.com/token \
-u "$INALAMBRIA_USER:$INALAMBRIA_PASSWORD" \
-H "Content-Type: application/json" \
-d '{"grant_type": "password"}' | jq -r '.access_token')
# 2. Envía un SMS (Colombia: 12 dígitos, 57 + celular)
curl -X POST https://rest.inalambria.com/mtmessage \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"Type": 1,
"MessageText": "Tu pedido PEDIDO-4471 va en camino",
"Devices": "573001234567",
"CustomMessageId": "PEDIDO-4471"
}'// Node.js 18+
const BASE = 'https://rest.inalambria.com';
async function getToken() {
const basic = Buffer.from(`${process.env.INALAMBRIA_USER}:${process.env.INALAMBRIA_PASSWORD}`).toString('base64');
const res = await fetch(`${BASE}/token`, {
method: 'POST',
headers: { Authorization: `Basic ${basic}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ grant_type: 'password' }),
});
const { access_token } = await res.json(); // vigencia por defecto: 4 horas
return access_token;
}
const token = await getToken();
const res = await fetch(`${BASE}/mtmessage`, {
method: 'POST',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
Type: 1,
MessageText: 'Recordatorio: tu cita es mañana a las 8:30 a. m.',
Devices: '573001234567',
}),
});
console.log(await res.json()); // { TransactionNumber, Status: 0 | 1, MessageText }# Python 3 + requests
import os, requests
BASE = "https://rest.inalambria.com"
token = requests.post(
f"{BASE}/token",
auth=(os.environ["INALAMBRIA_USER"], os.environ["INALAMBRIA_PASSWORD"]),
json={"grant_type": "password"},
timeout=10,
).json()["access_token"]
resp = requests.post(
f"{BASE}/mtmessage",
headers={"Authorization": f"Bearer {token}"},
json={
"Type": 1,
"MessageText": "Tu factura de octubre ya está disponible",
"Devices": "573001234567-573007654321", # varios destinos separados por guion
"DateMessage": "2027-01-15 08:00:00", # envío programado (opcional)
},
timeout=10,
)
print(resp.status_code, resp.json())
Autenticación
- Token:
POST /tokencon Basic Authentication (usuario y contraseña en Base64) y el cuerpo{"grant_type": "password"}. La respuesta traeaccess_token,expires_in,refresh_tokenytoken_type. - Por defecto el token dura 4 horas y cada cuenta tiene 1 token activo: pedir uno nuevo expira el anterior. Ambos valores se pueden ampliar bajo solicitud.
- Para renovarlo sin credenciales, envía
{"grant_type": "refresh_token", "refresh_token": "..."}. - Los servicios SMS y RCS usan
Authorization: Bearer <token>(recomendado) o Basic. WhatsApp usa Basic. Email usa la cabecerax-api-key. - Las peticiones desde direcciones IP no autorizadas reciben
403.
SMS: POST /mtmessage
| Campo | Descripción |
|---|---|
Type* | 1 masivo (mismo texto), 2 personalizado (MessagePattern + MessageData), 3 plantilla (TemplateId + MessageData). |
Devices | Destinatarios separados por guion: 573XXXXXXXXX-573YYYYYYYYY. |
MessageText | Texto del mensaje (modo masivo). |
Channel | SMS (por defecto) o RCS. |
DateMessage | Programación: yyyy-MM-dd HH:mm:ss. |
FlashSMS | 1 para SMS flash. |
Url | URL larga que se acorta e inserta en el mensaje. |
HasMore / TransactionNumber | Envíos por partes bajo un mismo número de transacción. |
CustomMessageId / CallbackData | Datos propios que se devuelven en la notificación de estado. |
Respuesta: TransactionNumber (28 dígitos), Status (0 validado, 1 rechazado) y MessageText con el motivo del rechazo.
Formato: números de Colombia de 12 dígitos (57 + celular) y E.164 para el resto del mundo. No hay límite de caracteres, pero se recomienda no superar 500.
RCS
RCS usa el mismo endpoint /mtmessage con "Channel": "RCS". La cuenta y el agente RCS deben estar configurados previamente.
# RCS: mismo endpoint, con "Channel": "RCS" (requiere configuración previa de la cuenta)
curl -X POST https://rest.inalambria.com/mtmessage \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"Type": 1,
"Channel": "RCS",
"MessageText": "Tu pedido PEDIDO-4471 llega hoy entre 2 y 5 p. m.",
"Devices": "573001234567"
}'
Envíos en lotes: POST /mtmessage/massive
Varios mensajes, cada uno con su lista de destinations, en una sola petición. Cada mensaje admite flash, shortCode, notifyUrl, notifyContentType y callbackData (texto); en la raíz, bulkId agrupa la campaña.
# Lotes: varios mensajes y destinatarios en una sola petición, con notificación por petición
curl -X POST https://rest.inalambria.com/mtmessage/massive \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"bulkId": "CAMPANA-001",
"messages": [
{
"destinations": [
{ "to": "573001234567", "messageId": "1" },
{ "to": "573007654321", "messageId": "2" }
],
"text": "Tu cuota vence el 5 de diciembre",
"notifyUrl": "https://tu-servidor.example/inalambria/estado?token=TU_TOKEN",
"callbackData": "{\"campana\": \"cobro-dic\"}"
}
]
}'
SMS bidireccional: POST /momessage
Envía desde tu código corto asignado (ShortCode) para recibir respuestas. Responde Id, Message (OK o ERROR) y Status. Las respuestas de los usuarios también pueden recibirse por SMPP (modo Receiver).
# Bidireccional: envío por tu código corto asignado
curl -X POST https://rest.inalambria.com/momessage \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"MessageText": "¿Confirmas tu cita del jueves? Responde 1 para Sí, 2 para No",
"PhoneNumber": "573001234567",
"ShortCode": "12345"
}'
Notificaciones de estado
| Modalidad | Uso | Autenticación de tu endpoint |
|---|---|---|
| Webhook de cuenta | Con /mtmessage. La URL queda configurada en tu cuenta (puede tardar hasta 10 minutos en activarse). | Basic o token en la URL |
| Callback por petición | Con /mtmessage/massive. La URL viaja en notifyUrl. | Token en la URL |
- Ambas se habilitan escribiendo a soporte con las cuentas de envío y la URL receptora.
- Llega una petición por mensaje (
resultstrae un solo elemento) cuando el operador recibe o rechaza el envío;smsCountindica los segmentos. - Responde
2xx. Solo503provoca reintentos: hasta 5, a los 10, 20, 30, 40 y 50 segundos. Otro código o la falta de respuesta no se reintenta. - Sé idempotente con
transactionNumber+toy no asumas orden de llegada. status.nameesDELIVERED_TO_HANDSETen un envío exitoso yNO_SUCCESSen uno fallido.
// Receptor de notificaciones de estado (Node.js)
import http from 'node:http';
const seen = new Set();
http.createServer((req, res) => {
if (req.method !== 'POST' || !req.url.startsWith('/inalambria/estado')) {
res.writeHead(404).end();
return;
}
let body = '';
req.on('data', (chunk) => (body += chunk));
req.on('end', () => {
// Acusa recibo con 2xx de inmediato; responde 503 solo si quieres un reintento.
res.writeHead(200).end();
const [result] = JSON.parse(body).results; // siempre un único elemento
const key = `${result.transactionNumber}:${result.to}`;
if (seen.has(key)) return; // idempotencia
seen.add(key);
console.log(result.messageId, result.status.name, result.smsCount);
});
}).listen(8080);
Envía plantillas aprobadas por Meta con source, destination, templateId y parameters (en el orden exacto de la plantilla). Un 200 confirma la recepción y genera un número de transacción, no la entrega final.
# WhatsApp con plantilla aprobada de Meta (Basic Authentication)
curl -X POST https://multichannel.inalambria.com/MultiChannelInput/SendMessageMetaWhatsApp \
-u "$INALAMBRIA_USER:$INALAMBRIA_PASSWORD" \
-H "Content-Type: application/json" \
-d '{
"source": "573000000000",
"destination": "573000000001",
"templateId": "ID_PLANTILLA",
"parameters": ["Ana", "PEDIDO-4471"]
}'
fromdebe pertenecer a un dominio remitente verificado para tu cuenta.- Usa
templateId(consultaGET /email/v1/templates) ohtmlconsubject. Las variables{{variable}}se llenan confields. - Hasta 50 destinatarios por petición; adjuntos en base64 (máximo 10 archivos y 8 MB; la petición completa no puede superar 20 MB).
# Email con plantilla almacenada (cabecera x-api-key)
curl -X POST https://emailrest.inalambria.com/email/v1/deliver \
-H "x-api-key: $INALAMBRIA_EMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "notificaciones@tu-dominio-verificado.example",
"fromName": "Tu empresa",
"templateId": "TEMPLATE_ID_ASIGNADO",
"payload": [
{ "recipient": "usuario@example.com", "fields": { "nombre": "Ana" } }
]
}'
# Responde 202: revisa overallStatus, errors y el estado de cada destinatario.
Verify (OTP)
Inalambria Verify verifica el teléfono o el correo de tus usuarios con dos llamadas HTTP. Verify se ocupa del código, la entrega, los intentos, la expiración y los límites. Envía el código por WhatsApp, SMS o Email con cascada automática, y solo se facturan las verificaciones aprobadas.
| Paso | Endpoint | Resultado |
|---|---|---|
| 1. Enviar el código | POST https://verify.inalambria.com/v1/verifications | 201 con el id y status: "pending", sin esperar la entrega. |
| 2. Comprobar el código | POST https://verify.inalambria.com/v1/verifications/{id}/check | 200 con approved, pending (código incorrecto) o max_attempts_reached. |
Esta sección se sincroniza con la documentación de Verify en cada publicación del sitio. Documentación actualizada el 29 de octubre de 2026.
Empezar
Guía rápidaDe cero a tu primera verificación en dos llamadas. No hay que crear aplicaciones ni plantillas antes del primer envío.
Antes de empezar
Necesitas una clave de API y un backend desde donde llamar. La clave viaja en cada petición como Authorization: Bearer <clave> y nunca debe llegar al navegador ni a una app móvil.
Atención. Una clave live_ envía mensajes reales y factura las verificaciones aprobadas. Para probar las llamadas sin enviar nada, usa una clave test_ con los destinatarios del entorno de pruebas: una clave test_ rechaza los números reales.
Tu cuenta ya trae una política por defecto (longitud del código, vigencia, intentos y cascada de canales), así que el primer envío no requiere configurar nada.
Nota. Los mensajes de error de la API (detail y hint) pueden mejorar con el tiempo. Decide con el code numérico, nunca con el texto.
1. Envía el código
Indica el destinatario: un teléfono en formato E.164 o, si el correo está configurado para tu aplicación, una dirección de correo. Opcionalmente, la cascada de canales en orden de preferencia.
Nota. Si WhatsApp todavía no está habilitado para tu aplicación, ese paso se salta al instante y el código sale por el siguiente canal de la cascada, SMS en el ejemplo. Con ["whatsapp"] solo, la verificación termina en failed. No tienes que cambiar nada en tu integración. Detalles en Cascada de canales.
curl https://verify-api.inalambria.com/v1/verifications \
-H "Authorization: Bearer $VERIFY_API_KEY" \
-H "Idempotency-Key: signup-8812" \
--json '{ "to": "+573001234567", "channels": ["whatsapp", "sms"] }'const response = await fetch('https://verify-api.inalambria.com/v1/verifications', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VERIFY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'signup-8812',
},
body: JSON.stringify({ to: '+573001234567', channels: ['whatsapp', 'sms'] }),
});
const verification = await response.json();verification = requests.post(
"https://verify-api.inalambria.com/v1/verifications",
headers={
"Authorization": f"Bearer {os.environ['VERIFY_API_KEY']}",
"Idempotency-Key": "signup-8812",
},
json={"to": "+573001234567", "channels": ["whatsapp", "sms"]},
).json()La respuesta llega en cuanto la verificación existe; no espera a que el mensaje se entregue.
{
"id": "ver_01J9XQ4M7K2VBN3P",
"status": "pending",
"to": "+57******4567",
"channel": "whatsapp",
"attempts_remaining": 3,
"expires_at": "2026-09-29T14:37:05.000Z",
"resend_available_at": "2026-09-29T14:33:05.000Z",
"created_at": "2026-09-29T14:32:05.000Z"
}| Campo | Qué significa |
|---|---|
id | Identificador de la verificación. Lo necesitas para comprobar el código. |
to | El destinatario, siempre enmascarado. El código nunca viaja en la respuesta. |
channel | El primer canal de la cascada. En un 200, el paso en curso. |
attempts_remaining | Cuántas comprobaciones más admite. Un código incorrecto gasta una; uno correcto, no. |
expires_at | Después de este momento el código deja de valer. |
resend_available_at | Desde cuándo una nueva llamada reenvía el código. |
Los enteros opcionales expires_in (60–1800 s), code_length (4–10) y max_attempts (1–10) sobrescriben la política de tu aplicación solo para esta verificación; brand (hasta 64 caracteres) y client_reference (hasta 128) viajan con ella. El detalle está en la referencia.
2. Comprueba el código
Envía lo que escribió tu usuario, con el id del paso anterior.
curl https://verify-api.inalambria.com/v1/verifications/ver_01J9XQ4M7K2VBN3P/check \
-H "Authorization: Bearer $VERIFY_API_KEY" \
--json '{ "code": "418302" }'const response = await fetch(
`https://verify-api.inalambria.com/v1/verifications/${verification.id}/check`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VERIFY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ code: codeFromUser }),
},
);
const result = await response.json();result = requests.post(
f"https://verify-api.inalambria.com/v1/verifications/{verification['id']}/check",
headers={"Authorization": f"Bearer {os.environ['VERIFY_API_KEY']}"},
json={"code": code_from_user},
).json(){
"id": "ver_01J9XQ4M7K2VBN3P",
"status": "approved",
"attempts_remaining": 3,
"verified_at": "2026-09-29T14:32:41.000Z",
"channel_used": "whatsapp"
}verified_at y channel_used solo aparecen cuando la verificación se aprueba.
3. Actúa según el resultado
Un código incorrecto no es un error HTTP: responde 200 y el resultado viaja en status. Los 4xx quedan para peticiones que no se pudieron atender.
| Respuesta | Qué pasó | Qué hacer |
|---|---|---|
200 approved | Código correcto. | Continúa el flujo de tu usuario. |
200 pending | Código incorrecto; quedan intentos. | Pide el código otra vez. attempts_remaining bajó en uno. |
200 max_attempts_reached | Se agotaron los intentos. | Crea una verificación nueva si quieres reintentar. |
409 · 30002 | La verificación ya terminó: aprobada, expirada, fallida o sin intentos. | No reintentes esa verificación. |
404 · 30001 | El id no existe o pertenece a otra cuenta, aplicación o entorno. | Revisa que usas el id de la respuesta de creación. |
400 · 20002 | El código no tiene el formato esperado, o no es una cadena JSON. | No se gasta un intento: valida la longitud en tu formulario. |
Envía code como cadena. Los espacios alrededor y las mayúsculas no importan; los espacios en medio, sí. Envía también una Idempotency-Key en esta llamada: si se pierde la respuesta de un código correcto, reintentar con la misma clave devuelve el approved original; sin ella, el reintento responde 409.
switch (result.status) {
case 'approved':
return markPhoneAsVerified(user);
case 'pending':
return askAgain({ attemptsLeft: result.attempts_remaining });
case 'max_attempts_reached':
return offerNewCode();
}Reenviar el código
No hay un endpoint de reenvío: volver a crear la verificación es el reenvío. Si ya hay una activa para ese destinatario, recibes la misma con 200, nunca un 409.
- Antes de
resend_available_at, no se envía nada nuevo: te devolvemos la verificación en curso. - Después, se reenvía el mismo código por el canal en curso y el plazo de reenvío vuelve a empezar.
expires_atno se mueve. El reenvío vuelve a pasar por los límites, así que puede responder429o403; la verificación en curso queda intacta. - Por correo, si el envío anterior fue incierto, no se reenvía nada: te devolvemos la verificación en curso. Detalles en Cascada de canales.
- Mientras hay una verificación activa, las opciones de la nueva llamada (
channels,expires_in,code_length,max_attempts,brand,client_reference) se ignoran, aunque se siguen validando. Cuando termina, la siguiente llamada crea una verificación nueva con un código nuevo. - Usa una
Idempotency-Keynueva en cada «Reenviar»: la misma clave repite la primera respuesta y no envía nada. Más en Reintentos seguros.
Así un usuario que pulsa «Reenviar» dos veces no dispara dos mensajes ni recibe dos códigos distintos.
AutenticaciónCada petición lleva tu clave de API en el encabezado Authorization. Una clave live envía mensajes reales; una clave test usa el entorno de pruebas.
La clave en cada petición
Authorization: Bearer test_akey_01J9XQ4M7K2VBN3PWD5Q8R7T6C_4F9…La API solo acepta el esquema Bearer. Cualquier otra forma responde 401 con el código 10001.
Importante. La clave va solo en tu backend. Nunca la incluyas en el código de un navegador ni de una app móvil: quien la tenga puede enviar códigos a tu nombre.
Formato de la clave
Una clave se lee entorno_akey_identificador_secreto: tres partes, y el identificador lleva su propio prefijo akey_.
| Parte | Ejemplo | Qué es |
|---|---|---|
| Entorno | live o test | Producción o pruebas. |
| Identificador | akey_01J9XQ4M7K2VBN3PWD5Q8R7T6C | Identifica la clave. Aparece en registros y soporte. |
| Secreto | 52 caracteres en mayúsculas | Distingue mayúsculas de minúsculas. Nunca se muestra dos veces. |
Pruebas y producción
Las claves test_ y live_ usan la misma API, pero viven en dos entornos separados.
- Una clave
live_envía mensajes reales y sus verificaciones aprobadas se facturan. - Una clave
test_no envía nada: solo acepta los destinatarios fijos del entorno de pruebas, el código es siempre el mismo y nada se factura. - Una verificación creada en un entorno no existe para el otro: comprobarla con una clave del otro entorno responde
404con30001.
Obtener y revocar claves
Hoy las claves las emite el equipo de Inalambria. El secreto se entrega una sola vez; guárdalo en tu gestor de secretos.
Cuando una clave se revoca, las peticiones responden 401 con 10002. Puede seguir aceptándose durante unos segundos (siempre menos de un minuto) mientras expira su caché.
Errores de autenticación
| Código | HTTP | Cuándo |
|---|---|---|
10001 | 401 | La clave falta, está mal formada o no existe. |
10002 | 401 | La clave fue revocada. |
10003 | 403 | La clave está restringida a ciertas direcciones IP y la petición llegó desde otra. |
10010 | 403 | Al crear una verificación: la aplicación no tiene Verify habilitado. |
40003 | 429 | Demasiados fallos de autenticación desde tu IP. |
Nota. Los fallos de autenticación repetidos desde una misma IP activan un bloqueo temporal: por defecto, 20 fallos en 60 segundos. Mientras dura, toda petición desde esa IP responde 429 con un Retry-After que dice cuántos segundos esperar.
Entorno de pruebasPrueba tu integración con una clave test_ sin enviar un solo mensaje. Destinatarios fijos, un código fijo y la misma API que producción.
Qué es el entorno de pruebas
Una clave test_ habla con la misma API que una clave live_, pero nada sale de la plataforma: no se envía ningún WhatsApp, SMS ni correo, y nada se factura. En lugar de un número real usas los destinatarios de abajo, y el código es siempre el mismo.
Todo lo demás funciona como en producción: las respuestas, la cascada de canales, los intentos, el vencimiento, los límites, la Idempotency-Key y los webhooks.
Destinatarios de prueba
Con una clave test_ solo se aceptan estos destinatarios. Cualquier otro responde 400 con 20002 (sandbox_recipient_not_allowed). El mismo código rechaza estos destinatarios cuando la clave es live_.
| Teléfono | Correo | Qué pasa con cada envío |
|---|---|---|
+12025550101 | success@sandbox.invalid | Se acepta en todos los canales. Unos segundos después el sandbox lo reporta como entregado. |
+12025550102 | definitive@sandbox.invalid | Se rechaza en WhatsApp y correo. Se acepta en SMS y luego se reporta como entregado. |
+12025550103 | transient@sandbox.invalid | Falla en todos los canales. |
+12025550104 | timeout@sandbox.invalid | Se acepta en todos los canales. Nunca se reporta nada: el envío queda sin confirmar hasta que la verificación expira. |
+12025550105 | — | Se acepta y se reporta como entregado. Su SIM cambió hoy: sirve para probar la protección contra SIM swap. |
+12025550106 | delivery_failed@sandbox.invalid | Se acepta en todos los canales y luego se reporta como fallo definitivo: la cascada pasa al siguiente paso de inmediato. |
+12025550107 | delivery_transient@sandbox.invalid | Se acepta en todos los canales y luego se reporta como fallo transitorio: la cascada espera el tiempo del canal antes de avanzar. |
Para la verificación, «aceptado» y «rechazado» significan lo mismo que en producción:
- Un envío aceptado espera el tiempo del canal y luego pasa al siguiente paso. A menos que un reporte de entrega diga otra cosa (más abajo), la verificación sigue
pendinghasta que tu usuario comprueba el código o vence. - Un envío rechazado pasa al siguiente paso al instante. Cuando todos los pasos se rechazan, la verificación termina en
failedy el webhookverification.failedtraereason: "cascade_exhausted".
Dos ejemplos con channels: ["whatsapp", "sms"]:
| Destinatario | Qué pasa |
|---|---|
+12025550102 | WhatsApp se rechaza al instante y el paso de SMS se acepta. Al aprobar, channel_used es sms. |
+12025550103 | Los dos pasos fallan y la verificación termina en failed enseguida. |
El código
El entorno de pruebas no sortea un código: es siempre el comienzo de una secuencia fija, cortada a la longitud del código.
| Tipo de código | Secuencia | Con 6 caracteres |
|---|---|---|
numeric | 2345678923 | 234567 |
alphanumeric | ABCDEFGHJK | ABCDEF |
Un código numérico de 4 dígitos es 2345; uno de 8, 23456789. Compruébalo como cualquier otro: el correcto responde approved y uno incorrecto gasta un intento. Una verificación live_ nunca recibe este valor ni lo acepta, así que un código aprendido en pruebas no sirve en producción.
Canales
Con una clave test_ los tres canales están disponibles sin configurar nada: ni plantilla ni remitente de WhatsApp, ni plantilla de correo. La cascada, la espera por canal y los campos channel y channel_used se comportan como en producción.
Lo que el entorno de pruebas no simula:
- El mensaje. Nadie recibe nada: no hay texto que leer.
Cómo llegar a cada estado
Todos los estados que tu integración debe manejar se pueden alcanzar con los destinatarios de arriba y la misma API. Ninguno necesita un número especial fuera de la tabla.
| Quieres ver | Haz esto |
|---|---|
approved | Crea con +12025550101 y comprueba el código fijo. |
| Un código incorrecto | Comprueba cualquier otro código: la verificación sigue pending y gasta un intento. |
max_attempts_reached | Sigue comprobando códigos incorrectos hasta agotar los intentos. |
expired | Crea con "expires_in": 60 y espera un minuto sin comprobar. |
| Salto al siguiente canal | Crea con +12025550102 y channels: ["whatsapp", "sms"]. |
failed (cascade_exhausted) | Crea con +12025550103. |
| Aceptado pero nunca confirmado | Crea con +12025550104 y no compruebes: nunca llega un reporte y queda pending hasta que expira. |
verification.channel.delivered | Crea con +12025550101: el webhook llega unos tres segundos después del envío. |
| Un fallo de entrega tras la aceptación | Crea con +12025550106 (verification.channel.failed, la cascada avanza ya) o +12025550107 (el mismo evento, la cascada espera). |
| Rechazo por SIM swap | Crea con +12025550105 con una aplicación que bloquea cambios recientes. |
| Destinatario no permitido | Usa cualquier otro destinatario: 400 con 20002. |
Separado de producción
El entorno de pruebas y producción son dos mundos separados bajo la misma cuenta.
| En el entorno de pruebas | |
|---|---|
| Verificaciones | Una creada con clave test_ solo se puede comprobar con una clave test_ de la misma aplicación. Con cualquier otra clave responde 404 con 30001, como si no existiera. |
| Límites | Aplican los mismos límites por destinatario y por aplicación, con contadores propios: el tráfico de pruebas nunca consume tu cupo de producción. |
Idempotency-Key | Las claves son por entorno: una clave usada en pruebas queda libre en producción. |
| Webhooks | Un endpoint pertenece a un solo entorno. Los eventos de pruebas solo llegan a endpoints registrados para test, y cada evento dice cuál es en data.environment. |
| Facturación | Nada se factura. Una verificación approved de pruebas nunca produce un evento facturable. |
Pruébalo desde la consola
La consola tiene una pantalla Sandbox que ejecuta estas llamadas contra la API real, para que explores cada parámetro sin escribir código.
- Pega una clave. Pega una clave
test_cada vez: la consola nunca la guarda y solo muestra sus últimos cuatro caracteres. Una clavelive_también sirve, con un aviso de costo y una confirmación en cada envío. - Elige un escenario. Cada destinatario reservado de arriba es una tarjeta que rellena la petición; el formulario de parámetros y el JSON se mantienen sincronizados, y una lista de disparadores de error provoca a propósito los errores documentados.
- Síguela. Tras una llamada, la pantalla sigue la verificación: intentos restantes, tiempo que queda, canal actual, las entregas de webhook (con reenvío para administradores) y si es facturable. Cada intercambio se ve como petición y respuesta crudas o como vista legible, con sus equivalentes en cURL y Node.js.
Pueden usarla administradores y desarrolladores. La pantalla lee a un ritmo limitado y se frena sola cuando llega al límite.
Una prueba completa
# 1. Crear: no se envía nada.
curl https://verify-api.inalambria.com/v1/verifications \
-H "Authorization: Bearer $VERIFY_TEST_API_KEY" \
-H "Idempotency-Key: sandbox-run-1" \
--json '{ "to": "+12025550101", "channels": ["whatsapp", "sms"] }'
# 2. Comprobar el código fijo con el id de la respuesta.
curl https://verify-api.inalambria.com/v1/verifications/ver_01J9XQ4M7K2VBN3P/check \
-H "Authorization: Bearer $VERIFY_TEST_API_KEY" \
--json '{ "code": "234567" }'La segunda llamada responde 200 con status: "approved". Repite la primera con +12025550103 para ver una verificación failed y su webhook.
Conceptos
Ciclo de una verificaciónUna verificación nace pendiente y siempre termina sola en un estado final. No hay que cerrarla ni cancelarla.
De pendiente a un estado final
Toda verificación empieza en pending y termina exactamente una vez. Nadie tiene que cerrarla: si el usuario nunca escribe el código, vence sola al llegar a expires_at.
| Estado | Qué significa | Final | Se factura |
|---|---|---|---|
pending | Activa, esperando el código. | No | No |
approved | El usuario escribió el código correcto. | Sí | Sí, solo con clave live_ |
expired | Venció sin una comprobación correcta. | Sí | No |
max_attempts_reached | Se agotaron los intentos. | Sí | No |
failed | Todos los canales de la cascada fallaron de forma definitiva. | Sí | No |
Solo approved se factura. Un código que no llegó, un usuario que no terminó o un intento bloqueado no te cuestan nada.
Nota. El contrato reserva además canceled y blocked, pero hoy ninguna verificación llega a ellos: no hay cancelación por API y los bloqueos antifraude rechazan la petición antes de crear la verificación.
Cómo avanza
- Crear (
POST /v1/verifications): nace enpendingy empieza la cascada de canales. - Comprobar (
POST /v1/verifications/{id}/check):- código correcto →
approved; - incorrecto con intentos → sigue
pending, con un intento menos; - incorrecto en el último intento →
max_attempts_reached.
- código correcto →
- Vencer: al llegar a
expires_atsin aprobación, pasa aexpired. Una comprobación en ese momento o después responde409con30002, igual que cualquier comprobación sobre una verificación que ya terminó. - Fallar: si cada canal de la cascada falla de forma definitiva antes de vencer, pasa a
failed. Si un canal aceptó el mensaje pero no sabemos si llegó, o un envío de correo fue incierto, la verificación siguependinghasta vencer.
Parámetros que controlan el ciclo
Cada aplicación tiene su política. Puedes sobrescribirla por petición al crear la verificación:
| Campo | Rango | Error si está fuera de rango |
|---|---|---|
expires_in | 60–1800 segundos | 20007 |
code_length | 4–10 caracteres | 20009 |
max_attempts | 1–10 intentos | 20011 |
channels | hasta 4 pasos | 20006 |
El tiempo de espera por canal y el plazo de reenvío son ajustes de la aplicación, no de la petición.
Cómo te enteras del resultado
- En la respuesta de comprobación, si el usuario escribe el código en tu app.
- Por webhook, para los finales que ocurren sin una llamada tuya:
expiredyfailed. - Por cada paso de canal, si te suscribes a los eventos
verification.channel.*: si cada envío fue aceptado, rechazado o entregado.
No hay un endpoint para consultar el estado de una verificación: el resultado llega solo.
Cascada de canalesDeclaras el orden de los canales en la petición. Si un canal no entrega a tiempo, el mismo código sigue por el siguiente.
Cómo funciona
La cascada es la lista channels de la petición, en orden de preferencia. Verify envía el código por el primer canal y, si no hay aprobación dentro de su tiempo de espera, pasa al siguiente.
{ "to": "+573001234567", "channels": ["whatsapp", "sms"] }- El código es uno solo. Cada paso lleva el mismo código, así que tu usuario puede escribir el primero que le llegue.
- Si omites
channels(o envías[]), se usan los canales encendidos de tu aplicación, en su orden: un teléfono toma WhatsApp y SMS, y un correo, el correo. Por defecto están todos encendidos, consms → whatsapppara teléfonos. - Solo canales encendidos. Una petición puede pedir otro orden o menos canales, pero no uno que tu aplicación tiene apagado: responde
403con10013. - Hasta 4 pasos. Una cascada más larga responde
20006. - El canal debe servir al destinatario:
whatsappysmspara teléfonos,emailpara correos. Otra combinación responde20005. - Un canal puede repetirse (
["sms", "sms"]): el mismo código se envía otra vez por ese canal tras su tiempo de espera. Los nombres van en minúsculas; cualquier otra cosa responde20005.
Los canales de tu aplicación
En la consola, en Aplicación → Política de verificación, eliges el orden de WhatsApp y SMS y qué canales quedan encendidos. Al menos uno tiene que quedar encendido, y los cambios rigen desde la siguiente verificación.
- Con el correo apagado, Verify rechaza las verificaciones a correos con
403y10013. - Con WhatsApp y SMS apagados, rechaza las de teléfonos de la misma forma.
- Un rechazo así no crea la verificación y no se factura.
Canales disponibles
| Canal | Estado | Destinatario |
|---|---|---|
whatsapp | Disponible cuando está habilitado para tu aplicación | Teléfono |
sms | Disponible | Teléfono |
email | Disponible cuando está habilitado para tu aplicación | Correo |
WhatsApp necesita dos cosas que configura el equipo de Inalambria: una plantilla de autenticación aprobada por Meta y un remitente de WhatsApp asignado a tu aplicación. Mientras falte alguna, el paso de WhatsApp se salta al instante y la cascada sigue por SMS: tu integración no cambia.
El correo también lo configura el equipo de Inalambria: el envío de correo activado en la plataforma, una plantilla de correo de tu cuenta en la plataforma de correo de Inalambria, con el campo que lleva el código, y una dirección remitente asignada a tu aplicación.
Nota. Con una clave test_ los tres canales están disponibles sin configurar nada, y no se envía nada. Mira el entorno de pruebas.
Atención. Un correo tiene un solo canal posible, email, así que no hay respaldo. Si el correo no está configurado para tu aplicación, la verificación termina en failed al instante.
Cuándo pasa al siguiente canal
| Qué pasó con el paso | Qué hace la cascada |
|---|---|
| El canal no está habilitado o el proveedor rechazó el envío | Pasa al siguiente al instante. |
| No se pudo contactar al proveedor (SMS, WhatsApp) | Cuenta como paso fallido: pasa al siguiente al instante. El correo se trata como incierto, más abajo. |
| El proveedor aceptó el mensaje | Espera el tiempo del canal (por defecto 120 segundos) y, si no hubo aprobación, pasa al siguiente. |
| El usuario escribió el código correcto | Termina: approved. |
Que WhatsApp acepte un mensaje no confirma que llegó: WhatsApp no nos reporta la entrega. Por eso la cascada espera el tiempo del canal antes de probar por SMS, en lugar de saltar enseguida.
Cada paso espera el tiempo del canal antes de que empiece el siguiente, y un paso que empezaría después de expires_at nunca corre: deja expires_in más largo que (pasos − 1) × el tiempo del canal, o los últimos canales nunca se prueban.
Correo: cuando el envío es incierto
Que el proveedor de correo acepte un mensaje solo significa que lo puso en cola; tampoco nos reporta la entrega. A veces su respuesta ni siquiera dice eso: un tiempo de espera agotado, una conexión cortada, un error del servidor o una respuesta incompleta. En esos casos el correo pudo haber salido o no, así que Verify no lo vuelve a enviar:
- La verificación sigue
pendingcon el mismo código. Tu usuario todavía puede escribirlo, hastaexpires_at. - Crear la verificación de nuevo la devuelve con
200y no envía nada, aunque ya haya pasadoresend_available_at. No consume límites yresend_available_atno se mueve. - Ese envío no puede hacerla terminar en
failed: salvo que tu usuario la apruebe o agote los intentos, termina enexpired.
Qué canal ves en cada respuesta
channel, en la creación: el primer paso de la cascada, aunque ese canal termine saltándose. En un200(reutilizada o reenviada), el paso en curso en ese momento.channel_used, en la aprobación: el paso que estaba en curso cuando tu usuario escribió el código.
Como todos los pasos llevan el mismo código, channel_used no garantiza que ese fuera el mensaje que tu usuario leyó.
El texto del mensaje
El SMS lo puedes escribir tú, en la consola, en Aplicación → Mensaje SMS. Lleva {{code}} una vez, donde va el código, y si quieres {{minutes}}, los minutos que dura; ningún otro marcador, hasta 300 caracteres. Mientras no escribas uno, sale el de la plataforma:
Tu codigo de verificacion es 418302. Vence en 5 minutos. No lo compartas con nadie.Los minutos son el expires_in de la verificación, redondeado hacia arriba, no el tiempo que queda cuando sale ese mensaje en particular.
Sin tildes, en un SMS caben 160 caracteres. Una letra como «ó» o un emoji cambian la codificación y caben 70, así que un mensaje largo puede ocupar dos SMS. La consola muestra cuántos ocupa mientras lo escribes.
En WhatsApp se usa la plantilla de autenticación aprobada por Meta, igual para todas las cuentas. El campo brand aún no aparece en el texto de ningún canal.
El correo usa la plantilla de tu cuenta en la plataforma de correo de Inalambria. Verify solo completa el código: todo lo demás del mensaje sale de esa plantilla.
Cuándo falla
Una verificación termina en failed solo si cada paso falla de forma definitiva: el proveedor lo rechazó o no se pudo contactar, el canal no está disponible o configurado, o el operador confirmó que no se entregó. El correo es la excepción: un envío incierto nunca cuenta como fallo.
Si un canal aceptó el mensaje pero nadie confirmó la entrega, o el envío de correo fue incierto, no cuenta como fallo: la verificación sigue pending hasta vencer.
Límites y antifraudeVerify frena el abuso antes de gastar un mensaje. Los límites vienen activos y lo que se bloquea no se factura.
Qué se revisa antes de enviar
Cada vez que una petición va a enviar un mensaje, al crear o al reenviar, Verify revisa estos controles en orden. Si alguno se activa, no se envía nada y la petición no se factura.
| Control | HTTP | Código |
|---|---|---|
| País del destinatario no habilitado (solo teléfonos) | 403 | 40012 |
| Destinatario bloqueado: número o dirección exactos, o prefijo del número | 403 | 40011 |
| Demasiadas verificaciones para el mismo destinatario | 429 | 40001 |
| Demasiadas verificaciones para la aplicación | 429 | 40002 |
| La SIM del número cambió hace poco, si activaste la protección contra SIM swap (solo teléfonos) | 403 | 40014 |
Devolver una verificación que sigue activa, sin enviar nada nuevo, no consume los límites. Por eso un usuario impaciente que pulsa «Reenviar» no agota su cupo. La única excepción son dos creaciones simultáneas para el mismo destinatario: las dos cuentan.
Los contadores son por entorno: lo que envías con una clave test_ nunca cuenta contra tu cupo de producción, aunque en el entorno de pruebas aplican los mismos límites y bloqueos.
Límites por destinatario y por aplicación
- Por destinatario: cuenta cuántos códigos se envían a un mismo número o dirección de correo en ventanas de tiempo, verificaciones nuevas y reenvíos por igual. Por ejemplo, 5 por hora y 20 por día. El conteo es compartido por todas las aplicaciones de tu cuenta.
- Por aplicación: un tope global opcional para toda tu aplicación.
Hoy los valores son los mismos para todas las cuentas. Pide los vigentes a tu contacto de Inalambria si necesitas planear picos de tráfico.
Atención. Las respuestas 429 con 40001 y 40002 no incluyen Retry-After. No reintentes en bucle: muestra a tu usuario que espere y reintenta con retroceso exponencial, con una Idempotency-Key nueva: la misma clave repite el 429 guardado.
Fallos de autenticación por IP
Además, los fallos de autenticación repetidos desde una IP (por defecto, 20 en 60 segundos) bloquean esa IP durante un tiempo. Mientras dura, toda petición responde 429 con 40003 y un Retry-After en segundos.
Límite por clave
Una clave también puede llevar su propio límite de peticiones por minuto. Cuando se agota, las peticiones hechas con esa clave responden 429 con 40005 y un Retry-After en segundos; las demás claves de la misma cuenta no se ven afectadas.
Buenas prácticas
- Valida el número en tu formulario antes de llamar: evitas un
40020003y le das a tu usuario el error en el momento. - No expongas la creación de verificaciones sin control. Pon un captcha o un límite propio por sesión delante del botón «Enviar código».
- Guarda el
X-Request-Idde las respuestas4xx: es lo primero que pedirá soporte.
Protección contra SIM swapVerify puede negarse a enviar el código a un número cuya SIM cambió hace poco. Se activa por aplicación desde la consola.
Qué es un SIM swap
Para quedarse con los códigos de alguien, un atacante convence al operador de pasar el número de esa persona a una SIM nueva. Desde ese momento, los SMS y los WhatsApp dirigidos a esa persona llegan al teléfono del atacante.
Con la protección activada, Verify consulta cuándo cambió por última vez la SIM del número antes de enviar el código. Si cambió dentro del plazo que elegiste, no envía nada y responde con un error.
Cómo activarla
En la consola, en Aplicación → Protección contra SIM swap, elige el plazo: 1 día, 3 días o 7 días. Con Desactivada queda apagada, que es como viene. Solo un administrador puede cambiarla, y el cambio rige desde la siguiente verificación.
Qué cuenta como «dentro del plazo»
El operador informa la fecha del cambio, no la hora. Por eso el plazo cuenta días de calendario e incluye el día del borde:
| Plazo | Se bloquea un cambio de |
|---|---|
| 1 día | hoy o ayer |
| 3 días | hoy o los 3 días anteriores |
| 7 días | hoy o los 7 días anteriores |
Con un plazo de 1 día también se bloquea un cambio hecho ayer a las 23:59. Ningún cambio de las últimas 24 horas pasa.
A qué se aplica
- Solo a teléfonos, por SMS y por WhatsApp. Un correo no tiene SIM y se envía sin esta revisión.
- Al crear y al reenviar, cada vez que se va a enviar un código nuevo. Devolver una verificación que sigue activa no envía nada y no vuelve a consultar. Comprobar un código tampoco consulta.
- Después de los límites: una petición que ya frenó un límite no llega a consultar el cambio de SIM.
La respuesta
Cuando la SIM cambió dentro del plazo, la verificación no se crea y la petición responde 403 con 40014:
{
"type": "https://docs.inalambria.com/verify/errors/40014",
"title": "sim_swap_recent",
"status": 403,
"detail": "La SIM del número cambió hace poco y la aplicación no envía códigos en ese caso.",
"code": 40014,
"hint": "Verificá la identidad de la persona por otro medio antes de volver a intentarlo.",
"request_id": "req_01J9XQ4M7KZ3T8V2W6N5P0QRST"
}Una petición rechazada así no se factura. Reintentarla da el mismo resultado mientras dure el plazo: pide a tu usuario que confirme su identidad por otra vía, por ejemplo verificando su correo.
Si en ese momento no se puede consultar el cambio de SIM, Verify envía el código igual y deja constancia en sus registros.
Probarla en el entorno de pruebas
Con una clave test_, el último cambio de SIM de cada destinatario de prueba es fijo:
| Teléfono | Último cambio de SIM | Con la protección activada |
|---|---|---|
+12025550105 | Hoy | Se rechaza con 40014, con cualquier plazo. |
+12025550101 | 1 de enero de 2020 | Se envía. |
+12025550102 | Sin registro | Se envía. |
+12025550103 | Fuera de cobertura | Se envía. |
+12025550104 | La consulta falla | Se envía. |
Consultar el cambio de SIM por tu cuenta
POST /v1/tools/sim-swap dice cuándo cambió por última vez la SIM de un número, sin crear una verificación. Sirve para revisarlo en otros momentos, como antes de un cambio de contraseña o de una transferencia.
curl https://verify-api.inalambria.com/v1/tools/sim-swap \
-H "Authorization: Bearer $VERIFY_API_KEY" \
--json '{ "to": "+573001234567" }'const response = await fetch('https://verify-api.inalambria.com/v1/tools/sim-swap', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VERIFY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to: '+573001234567' }),
});
const simSwap = await response.json();sim_swap = requests.post(
"https://verify-api.inalambria.com/v1/tools/sim-swap",
headers={"Authorization": f"Bearer {os.environ['VERIFY_API_KEY']}"},
json={"to": "+573001234567"},
).json(){
"status": "swap_detected",
"last_swap_date": "2026-10-25",
"days_since_swap": 3
}status | Qué significa |
|---|---|
swap_detected | Hay un cambio registrado: last_swap_date trae su fecha y days_since_swap, los días desde entonces. |
unknown | El operador no tiene un cambio registrado para el número. |
out_of_coverage | El operador o el país del número no entrega este dato. |
Con unknown y out_of_coverage, last_swap_date y days_since_swap vienen en null. Con una clave test_ responde lo que dice la tabla de la sección anterior.
Los errores propios de esta consulta:
PrivacidadEl código nunca existe en claro fuera del mensaje que recibe tu usuario, y los destinatarios siempre vuelven enmascarados.
El código nunca en claro
El código de verificación solo existe en claro en el mensaje que recibe tu usuario.
- La API nunca lo devuelve. No hay respuesta, campo ni webhook que lo incluya.
- Nunca se guarda ni se registra en claro. Se guarda con hash, para comprobarlo, y cifrado, para poder reenviar el mismo código. Nunca aparece en registros ni en trazas.
- Ninguna herramienta lo muestra, tampoco las del equipo de soporte.
Destinatarios enmascarados
Cada vez que un destinatario aparece en una respuesta o en un registro, aparece enmascarado.
| Tipo | Enviado | Devuelto |
|---|---|---|
| Teléfono | +573001234567 | +57******4567 |
| Correo | juanita@ejemplo.com | j*****a@ejemplo.com |
Del teléfono se conservan los tres primeros caracteres (+ y dos dígitos) y los últimos cuatro. Del correo, la primera y la última letra del usuario, y el dominio completo.
Mensajes de error que no repiten tus datos
El detail de cada error es un texto fijo: nunca interpola lo que enviaste. Un número mal formado responde «El número indicado no es un número móvil válido en formato E.164», sin repetir el número.
Qué conviene guardar de tu lado
- El
idde la verificación, para relacionarla con tu usuario. - El
X-Request-Idde cada respuesta, para soporte. - Si lo necesitas, una
client_referencepropia (hasta 128 caracteres) que viaja en los webhooks. No pongas datos personales en ella.
Integración
Reintentos segurosCon Idempotency-Key puedes repetir cualquier POST sin miedo a crear una segunda verificación ni a enviar un segundo código.
Por qué hace falta
Una red inestable puede cortar la respuesta aunque la petición sí llegó. Si reintentas a ciegas, podrías crear dos verificaciones. Con Idempotency-Key, el reintento devuelve exactamente la misma respuesta que la primera vez.
Idempotency-Key: signup-8812-attempt-1Funciona en los dos endpoints. Es opcional, pero recomendado en toda llamada que tu código pueda repetir.
Cómo se comporta
| Situación | Respuesta |
|---|---|
| Primera vez con esa clave | Se procesa normalmente y se guarda la respuesta. |
| Misma clave, mismo cuerpo | Se devuelve la respuesta guardada: el mismo estado HTTP y el mismo cuerpo. No se envía nada de nuevo. |
| Misma clave, cuerpo distinto | 422 con 20010. La clave ya está atada a otra petición. |
| Misma clave, la primera petición sigue en curso | 409 con 20010 y un Retry-After. Espera y repite. |
- La clave vale 24 horas y es por cuenta y por entorno: dos cuentas pueden usar la misma sin chocar, y también tus claves
test_ylive_. - Admite de 1 a 255 caracteres. Fuera de ese rango responde
400con20002. - «Mismo cuerpo» significa el mismo método, la misma ruta y los mismos bytes del cuerpo.
- Las respuestas
2xxy4xxse guardan,429incluido: para reintentar tras un límite, usa una clave nueva. Un5xxno se guarda: puedes reintentar con la misma clave y la petición se procesa de nuevo. - La clave es compartida por los dos endpoints: no reutilices una clave de creación en
/check.
Cómo elegir la clave
Usa algo que identifique la intención, no el intento: el mismo valor en cada reintento de la misma acción, y un valor nuevo para cada acción nueva. Un «Reenviar» es una acción nueva y necesita otra clave (por ejemplo signup-8812-send-2): reutilizar la clave de creación repite la primera respuesta y no envía nada. En /check, usa una clave por cada código que escriba tu usuario.
// Una clave por intento de registro, reutilizada en cada reintento de red.
const key = `signup-${signupId}`;
for (let attempt = 0; attempt < 3; attempt++) {
const response = await fetch(url, {
method: 'POST',
headers: { ...headers, 'Idempotency-Key': key },
body,
});
if (response.status < 500) return response;
await sleep(2 ** attempt * 500);
}Consejo. Sin Idempotency-Key, Verify igual te protege del doble clic: volver a crear una verificación para un destinatario que ya tiene una activa te devuelve esa misma, con 200. La clave de idempotencia cubre además el caso de la red: la respuesta perdida.
ErroresCada error dice qué pasó, con un código estable para tu código y un mensaje para las personas. Este catálogo se genera desde el de la API.
Formato
Todo 4xx y 5xx responde con application/problem+json (RFC 9457):
{
"type": "https://docs.inalambria.com/verify/errors/20003",
"title": "invalid_phone_number",
"status": 400,
"detail": "El número indicado no es un número móvil válido en formato E.164.",
"code": 20003,
"field": "to",
"hint": "Incluye el indicativo de país precedido de '+'. Para Colombia: +57 seguido de 10 dígitos.",
"request_id": "req_01J9XQ4M7KZ3T8V2W6N5P0QRST"
}| Campo | Para qué sirve |
|---|---|
code | Decide con este. Es estable: no cambia entre versiones. |
title | El nombre del error, legible y estable. Algunos códigos agrupan casos relacionados; title y field los distinguen. |
detail | Qué pasó, en español. Puede mejorar con el tiempo: no lo compares como texto. |
hint | Qué hacer, cuando hay una acción clara. |
field | El campo de la petición que lo causó, cuando aplica. |
request_id | El mismo valor que el encabezado X-Request-Id. Inclúyelo al pedir soporte. |
type | Enlace a la entrada de este catálogo. |
Las respuestas que se producen antes de que tu petición llegue a la API, como 404 por una ruta desconocida, 405, 413 por un cuerpo mayor de 16 KiB o 415 por un Content-Type que no es JSON, no traen code: para esas decide con status.
Consejo. Un código incorrecto no es un error: responde 200 con status: "pending". Los errores quedan para peticiones que no se pudieron atender.
Qué reintentar
5xx: sí, con la mismaIdempotency-Keyy retroceso exponencial.429: sí, después de esperar y con unaIdempotency-Keynueva. RespetaRetry-Aftercuando viene.409con20010: sí, después delRetry-After; la primera petición sigue en curso.- Cualquier otro
4xx: no. Corrige la petición: repetirla dará el mismo resultado.
Autenticación (10000–10999)
La clave de API o el producto de la aplicación.
10001
HTTP 401
invalid_api_key— La clave de API es inválida. Verificá que la clave enviada en el encabezado Authorization sea correcta y esté vigente.
10002
HTTP 401
revoked_api_key— La clave de API fue revocada. Emití una nueva clave desde la consola; esta ya no puede usarse.
10003
HTTP 403
api_key_ip_not_allowed— La clave de API no puede usarse desde esta dirección IP. Revisá las direcciones IP permitidas de la clave en la consola.
10010
HTTP 403
product_not_enabled— La aplicación no tiene este producto habilitado. Contactá a soporte para habilitar el producto en esta aplicación.
10011
HTTP 401
api_key_not_found— La clave de API indicada no existe o no pertenece a esta cuenta.
10013
HTTP 403
channel_not_enabled— La aplicación tiene apagado el canal que hace falta para esta verificación. Revisá los canales encendidos de la aplicación en la consola de Verify.
Petición inválida (20000–20999)
El cuerpo o los encabezados no cumplen el contrato. Corrige la petición antes de reintentar.
20001
HTTP 400
malformed_json— El cuerpo de la petición no es un JSON válido. Verificá que el cuerpo enviado sea JSON bien formado.
20002
HTTP 400
sandbox_recipient_not_allowed— El destinatario no está permitido para el entorno autenticado. Utilice destinos documentados de prueba únicamente con claves test.missing_field— Falta un campo requerido en la petición.invalid_request_field— Un campo de la petición tiene un tipo inválido.idempotency_key_invalid— La cabecera Idempotency-Key es inválida. Debe tener entre 1 y 255 caracteres.malformed_code— El código enviado no tiene el formato esperado.resend_cooldown_out_of_range— La configuración de reenvío de la aplicación está fuera de rango.channel_timeout_out_of_range— El tiempo de espera del canal configurado está fuera de rango.
20003
HTTP 400
invalid_phone_number— El número indicado no es un número móvil válido en formato E.164. Incluye el indicativo de país precedido de '+'. Para Colombia: +57 seguido de 10 dígitos.
20004
HTTP 400
invalid_email— La dirección de correo indicada no es válida.
20005
HTTP 400
channel_incompatible_with_recipient— El canal indicado no es compatible con el tipo de destinatario. Los canales whatsapp/sms requieren un teléfono; email requiere una dirección de correo.
20006
HTTP 400
cascade_too_long— La cascada de canales tiene más pasos de los permitidos.
20007
HTTP 400
ttl_out_of_range— El tiempo de expiración solicitado está fuera de rango.
20009
HTTP 400
code_length_out_of_range— La longitud de código solicitada está fuera de rango.
20010
HTTP 422, 409
idempotency_key_reuse— La clave de idempotencia ya fue usada con un cuerpo distinto.idempotency_request_in_flight— Ya hay una petición en curso con esta clave de idempotencia. Reintentá luego del tiempo indicado en Retry-After.
20011
HTTP 400
max_attempts_out_of_range— La cantidad máxima de intentos solicitada está fuera de rango.
20012
HTTP 400
code_type_invalid— El tipo de código configurado no es válido.
20013
HTTP 400
brand_invalid— El nombre de marca indicado no es válido. Debe tener hasta 64 caracteres y no contener caracteres de control.
20014
HTTP 400
client_reference_invalid— La referencia de cliente indicada no es válida. Debe tener hasta 128 caracteres y no contener caracteres de control.
Estado de la verificación (30000–30999)
La verificación no existe o ya terminó.
30001
HTTP 404
verification_not_found— La verificación indicada no existe.
30002
HTTP 409
verification_terminal— La verificación ya alcanzó un estado final y no acepta más intentos.
Límites y antifraude (40000–40999)
La petición es válida pero no se atiende. El tráfico bloqueado no se factura.
40001
HTTP 429
recipient_rate_limit_exceeded— Se superó el límite de solicitudes para este destinatario.
40002
HTTP 429
application_rate_limit_exceeded— Se superó el límite de solicitudes para esta aplicación.
40003
HTTP 429
ip_rate_limit_exceeded— Se superó el límite de solicitudes para esta dirección IP.
40004
HTTP 429 · Aún no se emite
custom_key_rate_limit_exceeded— Se superó el límite de solicitudes para esta clave personalizada.
40005
HTTP 429
api_key_rate_limit_exceeded— Se superó el límite de solicitudes por minuto de esta clave de API. Esperá el tiempo indicado en Retry-After antes de reintentar.
40006
HTTP 429
sim_swap_rate_limit_exceeded— La aplicación superó su límite de consultas de SIM swap por minuto. Esperá un minuto antes de volver a consultar.
40010
HTTP 403 · Aún no se emite
anti_fraud_blocked— La solicitud fue bloqueada por el motor antifraude.
40011
HTTP 403
recipient_blocked— El destinatario está en la lista de bloqueo.
40012
HTTP 403
country_not_enabled— El país del destinatario no está habilitado para esta aplicación.
40013
HTTP 403 · Aún no se emite
preflight_denied— La solicitud fue denegada por la validación previa al envío.
40014
HTTP 403
sim_swap_recent— La SIM del número cambió hace poco y la aplicación no envía códigos en ese caso. Verificá la identidad de la persona por otro medio antes de volver a intentarlo.
Plataforma (50000–50999)
Algo falló de nuestro lado. Reintenta con la misma Idempotency-Key.
50010
HTTP 500
internal_error— Ocurrió un error interno. Intentá nuevamente más tarde.
50011
HTTP 503
sim_swap_provider_unavailable— No se pudo consultar el cambio de SIM con el proveedor. Intentá nuevamente en unos minutos.
WebhooksVerify avisa a tu backend cuando una verificación termina, y cómo fue cada paso de canal. Cada evento va firmado con Standard Webhooks y se reintenta hasta dos días.
Para qué sirven
La respuesta de comprobación te dice si el código es correcto. Pero hay finales que ocurren sin una llamada tuya: la verificación vence o se agotan los canales. El webhook te avisa de esos finales. Si quieres, también te cuenta cómo fue cada paso de canal por el camino.
Eventos
| Evento | Cuándo |
|---|---|
verification.approved | El usuario escribió el código correcto. |
verification.expired | Venció sin una comprobación correcta. |
verification.failed | Terminó sin aprobarse. data.reason dice por qué: max_attempts_reached o cascade_exhausted. |
verification.channel.sent | Un canal aceptó el mensaje. |
verification.channel.delivered | El operador confirmó la entrega. Hoy solo lo reporta SMS. |
verification.channel.failed | Un canal rechazó el envío, o el operador reportó que no pudo entregarlo. |
Recibes exactamente uno de los tres primeros por verificación, cuando llega a su estado final. Los eventos de canal llegan mientras está en curso, uno por envío; un endpoint suscrito a todos los tipos de evento los recibe todos.
Qué recibes
Un POST a tu URL con este cuerpo:
{
"id": "evt_01M2K81GC7W06ZRKDS9K21QNDJ",
"type": "verification.failed",
"occurred_at": "2026-09-29T14:37:05.000Z",
"sequence": null,
"data": {
"verification_id": "ver_01J9XQ4M7K2VBN3P",
"application_id": "app_01J9XQ2B8Y6T4R1M0K9H7G5F3D",
"environment": "live",
"status": "max_attempts_reached",
"reason": "max_attempts_reached",
"client_reference": "signup-8812"
}
}reason solo aparece en verification.failed. client_reference es el valor que enviaste al crear la verificación.
En los eventos de canal, data describe el envío:
{
"id": "evt_01M2K81GC7W06ZRKDS9K21QNDK",
"type": "verification.channel.failed",
"occurred_at": "2026-09-29T14:32:06.000Z",
"sequence": null,
"data": {
"verification_id": "ver_01J9XQ4M7K2VBN3P",
"application_id": "app_01J9XQ2B8Y6T4R1M0K9H7G5F3D",
"environment": "live",
"attempt_id": "atm_01J9XQ4M8A1B2C3D4E5F6G7H8J",
"channel": "whatsapp",
"step": 0,
"attempt": 0,
"send_state": "rejected_definitive"
}
}| Campo | Qué significa |
|---|---|
channel, step | El canal y su posición en la cascada, empezando en 0. |
attempt | 0 en el primer envío de ese paso; cada reenvío suma uno. |
send_state | En channel.sent, siempre accepted. En channel.failed, por qué falló el envío: rejected_definitive, unavailable_transient, channel_unavailable o denied. |
delivery_state | Solo cuando el operador reportó: delivered en channel.delivered; failed_definitive o failed_transient en channel.failed. |
Un channel.failed no significa que la verificación falló: la cascada puede seguir por el siguiente canal. Por correo, un envío incierto también llega como unavailable_transient mientras la verificación sigue pending. client_reference solo viaja en los eventos finales.
Con estos encabezados:
content-type: application/json
webhook-id: evt_01M2K81GC7W06ZRKDS9K21QNDJ
webhook-timestamp: 1790693825
webhook-signature: v1,g0hM9SsE+OTHF9QDLvhRAmMOCQ8Qm9ZQnJwoUCP0+Tk=Verificar la firma
La firma sigue Standard Webhooks: un HMAC-SHA256 en base64 sobre webhook-id.webhook-timestamp.cuerpo. La clave es el secreto sin el prefijo whsec_, decodificado de base64.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function isValidWebhook(rawBody: string, headers: Headers, secret: string): boolean {
const id = headers.get('webhook-id');
const timestamp = headers.get('webhook-timestamp');
const signatures = headers.get('webhook-signature');
if (!id || !timestamp || !signatures) return false;
// Rechaza eventos de hace más de 5 minutos: frena reenvíos maliciosos.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();
// Durante una rotación llegan dos firmas separadas por un espacio.
return signatures.split(' ').some((candidate) => {
const [version, signature] = candidate.split(',');
if (version !== 'v1' || !signature) return false;
const received = Buffer.from(signature, 'base64');
return received.length === expected.length && timingSafeEqual(received, expected);
});
}# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook
webhook = Webhook(os.environ["VERIFY_WEBHOOK_SECRET"]) # whsec_…
# Lanza una excepción si la firma o la marca de tiempo no son válidas.
event = webhook.verify(raw_body, request.headers)Atención. Verifica la firma sobre el cuerpo crudo, tal como llegó. Si tu framework ya lo convirtió a JSON y lo vuelves a serializar, la firma no coincidirá.
Responder y reintentos
- Responde con un
2xxen menos de 5 segundos. Si tienes trabajo pesado, encólalo y responde enseguida. - Un
408,425,429, un5xx, un timeout o un error de red, DNS o TLS se reintenta hasta 7 veces: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h después del intento anterior, con una variación de ±20 %, unas 45 horas en total. Después, el evento se descarta. Si respondesRetry-After, podemos adelantar el reintento, nunca atrasarlo. - Cualquier otro
3xxo4xxdetiene los reintentos. Las redirecciones no se siguen. - Un mismo evento puede llegar más de una vez: descarta los repetidos por su
webhook-id. - Los eventos pueden llegar desordenados: usa
occurred_at.sequenceestá reservado y por ahora esnull. - Si tu endpoint sigue fallando, las entregas hacia él se pausan un rato, hasta una hora, y se reanudan solas.
- Tu URL debe resolver a una dirección pública; una dirección privada o de loopback se rechaza sin reintentos.
Registrar tu endpoint
Hoy el equipo de Inalambria registra tu URL: debe ser https, y se registra para un solo entorno, live o test. La misma URL puede registrarse una vez por entorno, cada una con su propio secreto. Un endpoint test solo recibe eventos del entorno de pruebas, y cada evento dice su entorno en data.environment. También puedes elegir qué tipos de evento recibe; si no eliges, recibe todos, eventos de canal incluidos.
Al registrarla recibes el secreto whsec_… una sola vez; guárdalo en tu gestor de secretos.
Cuando el secreto rota, durante 24 horas cada evento llega firmado con el secreto nuevo y con el anterior. El código de arriba acepta cualquiera de las dos.
SMPP y archivos
| Conexión | Host | Puerto |
|---|---|---|
| SMPP sin SSL | smsc.inalambria.com | 5020 |
| SMPP con SSL/TLS | smscssl.inalambria.com | 6011 |
| Mensajes entrantes (MO), modo Receiver | smscmo.inalambria.com | 6900 |
Modos de conexión: Transceiver, Transmitter o Receiver, con el System ID y la contraseña que te entrega Inalambria.
SMS por archivo: deja un archivo .txt (personalizado: número y mensaje por línea; o masivo: un mensaje para muchos números) en un sitio SFTP o un bucket S3 configurado, y en minutos se generan los envíos.
Monitoreo
GET /platformmonitory: estado de los operadores, si se usan como alternos y su tiempo de entrega, en lo posible en tiempo real.GET /bireports/effectivitybyclient: tiempos de procesamiento por estado (últimos 15 minutos).GET /bireports/msgmtclient: mensajes procesados por operador y estado (últimos 15 minutos).
Servicios de valor agregado: requieren habilitación previa.
Códigos de respuesta
| Código | Significado |
|---|---|
| 200 | Recibido y en procesamiento (o token generado). |
| 202 | Email: solicitud registrada; revisa el estado de cada destinatario. |
| 400 | Estructura del payload inválida. |
| 401 | No autorizado: revisa las credenciales. |
| 403 | Permisos insuficientes, por ejemplo una IP no permitida. |
| 500 | Error interno: reintenta en unos minutos o contacta a soporte. |
Catálogo de servicios
| Servicio | Endpoint | Host | Autenticación | Referencia |
|---|---|---|---|---|
| Solicitar token | POST /token | rest.inalambria.com | Basic | Ver |
| SMS / RCS unidireccional | POST /mtmessage | rest.inalambria.com | Bearer | Ver |
| SMS en lotes | POST /mtmessage/massive | rest.inalambria.com | Bearer | Ver |
| SMS bidireccional | POST /momessage | rest.inalambria.com | Bearer | Ver |
| Webhook de cuenta | Inalambria → tu servidor | — | Basic o token en URL | Ver |
| Callback por petición | Inalambria → tu servidor | — | Token en URL | Ver |
POST /MultiChannelInput/SendMessageMetaWhatsApp | multichannel.inalambria.com | Basic | Ver | |
| Enviar Emails | POST /email/v1/deliver | emailrest.inalambria.com | x-api-key | Ver |
| Plantillas de Email | GET /email/v1/templates | emailrest.inalambria.com | x-api-key | Ver |
| Verify: enviar código | POST /v1/verifications | verify.inalambria.com | Bearer | Ver |
| Verify: comprobar código | POST /v1/verifications/{id}/check | verify.inalambria.com | Bearer | Ver |
| Monitoreo de operadores | GET /platformmonitory | rest.inalambria.com | Bearer | Ver |
| Monitoreo de efectividad | GET /bireports/effectivitybyclient | rest.inalambria.com | Bearer | Ver |
| Monitoreo de estado de mensajes | GET /bireports/msgmtclient | rest.inalambria.com | Bearer | Ver |
| SMS por archivo | SFTP / Amazon S3 | — | — | Ver |
| SMPP | smsc.inalambria.com | :5020 / :6011 (TLS) | System ID | Ver |
Inalambria Express API
Para pymes y desarrolladores que quieren empezar sin contrato, la API de Inalambria Express (OpenAPI 3.1, Bearer Token) ofrece:
- Envío de SMS a uno o varios destinatarios
- Lotes con mensajes distintos para distintos grupos
- Mensajes personalizados con plantillas y variables
- Historial de consumo, saldo y presupuesto
- Seguimiento de trabajos asíncronos y colas
Soporte técnico
Escribe a soporte@inalambria.com o abre una solicitud en el formulario de soporte seleccionando «API REST» como producto.
¿Listo para comunicarte mejor con tus clientes?
Cuéntanos tu caso y diseñamos contigo la solución adecuada, con el respaldo de más de 23 años de experiencia en Colombia.