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:

ServicioHost
SMS, RCS, token y monitoreohttps://rest.inalambria.com
WhatsApphttps://multichannel.inalambria.com
Emailhttps://emailrest.inalambria.com
SMPPsmsc.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. 1

    Solicita tu cuenta

    Inalambria configura tu cuenta de envío y te entrega usuario y contraseña.

  2. 2

    Obtén el token

    POST /token con Basic Authentication y grant_type: password.

  3. 3

    Envía tu primer SMS

    POST /mtmessage con el Bearer Token. Guarda el TransactionNumber.

  4. 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"
  }'

Autenticación

  • Token: POST /token con Basic Authentication (usuario y contraseña en Base64) y el cuerpo {"grant_type": "password"}. La respuesta trae access_token, expires_in, refresh_token y token_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 cabecera x-api-key.
  • Las peticiones desde direcciones IP no autorizadas reciben 403.

SMS: POST /mtmessage

CampoDescripción
Type*1 masivo (mismo texto), 2 personalizado (MessagePattern + MessageData), 3 plantilla (TemplateId + MessageData).
DevicesDestinatarios separados por guion: 573XXXXXXXXX-573YYYYYYYYY.
MessageTextTexto del mensaje (modo masivo).
ChannelSMS (por defecto) o RCS.
DateMessageProgramación: yyyy-MM-dd HH:mm:ss.
FlashSMS1 para SMS flash.
UrlURL larga que se acorta e inserta en el mensaje.
HasMore / TransactionNumberEnvíos por partes bajo un mismo número de transacción.
CustomMessageId / CallbackDataDatos 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

ModalidadUsoAutenticación de tu endpoint
Webhook de cuentaCon /mtmessage. La URL queda configurada en tu cuenta (puede tardar hasta 10 minutos en activarse).Basic o token en la URL
Callback por peticiónCon /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 (results trae un solo elemento) cuando el operador recibe o rechaza el envío; smsCount indica los segmentos.
  • Responde 2xx. Solo 503 provoca 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 + to y no asumas orden de llegada.
  • status.name es DELIVERED_TO_HANDSET en un envío exitoso y NO_SUCCESS en 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);

WhatsApp

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"]
  }'

Email

  • from debe pertenecer a un dominio remitente verificado para tu cuenta.
  • Usa templateId (consulta GET /email/v1/templates) o html con subject. Las variables {{variable}} se llenan con fields.
  • 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.

PasoEndpointResultado
1. Enviar el códigoPOST https://verify.inalambria.com/v1/verifications201 con el id y status: "pending", sin esperar la entrega.
2. Comprobar el códigoPOST https://verify.inalambria.com/v1/verifications/{id}/check200 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
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"] }'
Node.js
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();
Python
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.

201 Created
{
  "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"
}
CampoQué significa
idIdentificador de la verificación. Lo necesitas para comprobar el código.
toEl destinatario, siempre enmascarado. El código nunca viaja en la respuesta.
channelEl primer canal de la cascada. En un 200, el paso en curso.
attempts_remainingCuántas comprobaciones más admite. Un código incorrecto gasta una; uno correcto, no.
expires_atDespués de este momento el código deja de valer.
resend_available_atDesde 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
curl https://verify-api.inalambria.com/v1/verifications/ver_01J9XQ4M7K2VBN3P/check \
  -H "Authorization: Bearer $VERIFY_API_KEY" \
  --json '{ "code": "418302" }'
Node.js
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();
Python
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()
200 OK
{
  "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.

RespuestaQué pasóQué hacer
200 approvedCódigo correcto.Continúa el flujo de tu usuario.
200 pendingCódigo incorrecto; quedan intentos.Pide el código otra vez. attempts_remaining bajó en uno.
200 max_attempts_reachedSe agotaron los intentos.Crea una verificación nueva si quieres reintentar.
409 · 30002La verificación ya terminó: aprobada, expirada, fallida o sin intentos.No reintentes esa verificación.
404 · 30001El id no existe o pertenece a otra cuenta, aplicación o entorno.Revisa que usas el id de la respuesta de creación.
400 · 20002El 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.

Node.js
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_at no se mueve. El reenvío vuelve a pasar por los límites, así que puede responder 429 o 403; 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-Key nueva 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.

Ver esta guía en docs.inalambria.com

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

Encabezado
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_.

ParteEjemploQué es
Entornolive o testProducción o pruebas.
Identificadorakey_01J9XQ4M7K2VBN3PWD5Q8R7T6CIdentifica la clave. Aparece en registros y soporte.
Secreto52 caracteres en mayúsculasDistingue 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 404 con 30001.

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ódigoHTTPCuándo
10001401La clave falta, está mal formada o no existe.
10002401La clave fue revocada.
10003403La clave está restringida a ciertas direcciones IP y la petición llegó desde otra.
10010403Al crear una verificación: la aplicación no tiene Verify habilitado.
40003429Demasiados 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.

Ver esta guía en docs.inalambria.com

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éfonoCorreoQué pasa con cada envío
+12025550101success@sandbox.invalidSe acepta en todos los canales. Unos segundos después el sandbox lo reporta como entregado.
+12025550102definitive@sandbox.invalidSe rechaza en WhatsApp y correo. Se acepta en SMS y luego se reporta como entregado.
+12025550103transient@sandbox.invalidFalla en todos los canales.
+12025550104timeout@sandbox.invalidSe 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.
+12025550106delivery_failed@sandbox.invalidSe acepta en todos los canales y luego se reporta como fallo definitivo: la cascada pasa al siguiente paso de inmediato.
+12025550107delivery_transient@sandbox.invalidSe 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 pending hasta 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 failed y el webhook verification.failed trae reason: "cascade_exhausted".

Dos ejemplos con channels: ["whatsapp", "sms"]:

DestinatarioQué pasa
+12025550102WhatsApp se rechaza al instante y el paso de SMS se acepta. Al aprobar, channel_used es sms.
+12025550103Los 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ódigoSecuenciaCon 6 caracteres
numeric2345678923234567
alphanumericABCDEFGHJKABCDEF

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 verHaz esto
approvedCrea con +12025550101 y comprueba el código fijo.
Un código incorrectoComprueba cualquier otro código: la verificación sigue pending y gasta un intento.
max_attempts_reachedSigue comprobando códigos incorrectos hasta agotar los intentos.
expiredCrea con "expires_in": 60 y espera un minuto sin comprobar.
Salto al siguiente canalCrea con +12025550102 y channels: ["whatsapp", "sms"].
failed (cascade_exhausted)Crea con +12025550103.
Aceptado pero nunca confirmadoCrea con +12025550104 y no compruebes: nunca llega un reporte y queda pending hasta que expira.
verification.channel.deliveredCrea con +12025550101: el webhook llega unos tres segundos después del envío.
Un fallo de entrega tras la aceptaciónCrea con +12025550106 (verification.channel.failed, la cascada avanza ya) o +12025550107 (el mismo evento, la cascada espera).
Rechazo por SIM swapCrea con +12025550105 con una aplicación que bloquea cambios recientes.
Destinatario no permitidoUsa 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
VerificacionesUna 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ímitesAplican 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-KeyLas claves son por entorno: una clave usada en pruebas queda libre en producción.
WebhooksUn 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ónNada 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 clave live_ 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

cURL
# 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.

Ver esta guía en docs.inalambria.com

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.

EstadoQué significaFinalSe factura
pendingActiva, esperando el código.NoNo
approvedEl usuario escribió el código correcto.SíSí, solo con clave live_
expiredVenció sin una comprobación correcta.SíNo
max_attempts_reachedSe agotaron los intentos.SíNo
failedTodos 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

  1. Crear (POST /v1/verifications): nace en pending y empieza la cascada de canales.
  2. 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.
  3. Vencer: al llegar a expires_at sin aprobación, pasa a expired. Una comprobación en ese momento o después responde 409 con 30002, igual que cualquier comprobación sobre una verificación que ya terminó.
  4. 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 sigue pending hasta vencer.

Parámetros que controlan el ciclo

Cada aplicación tiene su política. Puedes sobrescribirla por petición al crear la verificación:

CampoRangoError si está fuera de rango
expires_in60–1800 segundos20007
code_length4–10 caracteres20009
max_attempts1–10 intentos20011
channelshasta 4 pasos20006

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: expired y failed.
  • 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.

Ver esta guía en docs.inalambria.com

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.

Petición
{ "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, con sms → whatsapp para 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 403 con 10013.
  • Hasta 4 pasos. Una cascada más larga responde 20006.
  • El canal debe servir al destinatario: whatsapp y sms para teléfonos, email para correos. Otra combinación responde 20005.
  • 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 responde 20005.

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 403 y 10013.
  • 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

CanalEstadoDestinatario
whatsappDisponible cuando está habilitado para tu aplicaciónTeléfono
smsDisponibleTeléfono
emailDisponible cuando está habilitado para tu aplicaciónCorreo

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 pasoQué hace la cascada
El canal no está habilitado o el proveedor rechazó el envíoPasa 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 mensajeEspera el tiempo del canal (por defecto 120 segundos) y, si no hubo aprobación, pasa al siguiente.
El usuario escribió el código correctoTermina: 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 pending con el mismo código. Tu usuario todavía puede escribirlo, hasta expires_at.
  • Crear la verificación de nuevo la devuelve con 200 y no envía nada, aunque ya haya pasado resend_available_at. No consume límites y resend_available_at no se mueve.
  • Ese envío no puede hacerla terminar en failed: salvo que tu usuario la apruebe o agote los intentos, termina en expired.

Qué canal ves en cada respuesta

  • channel, en la creación: el primer paso de la cascada, aunque ese canal termine saltándose. En un 200 (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:

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

Ver esta guía en docs.inalambria.com

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.

ControlHTTPCódigo
País del destinatario no habilitado (solo teléfonos)40340012
Destinatario bloqueado: número o dirección exactos, o prefijo del número40340011
Demasiadas verificaciones para el mismo destinatario42940001
Demasiadas verificaciones para la aplicación42940002
La SIM del número cambió hace poco, si activaste la protección contra SIM swap (solo teléfonos)40340014

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 400 20003 y 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-Id de las respuestas 4xx: es lo primero que pedirá soporte.

Ver esta guía en docs.inalambria.com

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:

PlazoSe bloquea un cambio de
1 díahoy o ayer
3 díashoy o los 3 días anteriores
7 díashoy 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:

403 Forbidden
{
  "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 SIMCon la protección activada
+12025550105HoySe rechaza con 40014, con cualquier plazo.
+120255501011 de enero de 2020Se envía.
+12025550102Sin registroSe envía.
+12025550103Fuera de coberturaSe envía.
+12025550104La consulta fallaSe 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
curl https://verify-api.inalambria.com/v1/tools/sim-swap \
  -H "Authorization: Bearer $VERIFY_API_KEY" \
  --json '{ "to": "+573001234567" }'
Node.js
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();
Python
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()
200 OK
{
  "status": "swap_detected",
  "last_swap_date": "2026-10-25",
  "days_since_swap": 3
}
statusQué significa
swap_detectedHay un cambio registrado: last_swap_date trae su fecha y days_since_swap, los días desde entonces.
unknownEl operador no tiene un cambio registrado para el número.
out_of_coverageEl 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:

HTTPCódigoCuándo
40310010La consulta no está habilitada para tu aplicación. Pídela a tu contacto de Inalambria.
42940006Tu aplicación pasó de 60 consultas en un minuto.
50350011No se pudo consultar al operador. Reintenta en unos minutos.

Ver esta guía en docs.inalambria.com

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.

TipoEnviadoDevuelto
Teléfono+573001234567+57******4567
Correojuanita@ejemplo.comj*****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 id de la verificación, para relacionarla con tu usuario.
  • El X-Request-Id de cada respuesta, para soporte.
  • Si lo necesitas, una client_reference propia (hasta 128 caracteres) que viaja en los webhooks. No pongas datos personales en ella.

Ver esta guía en docs.inalambria.com

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.

Encabezado
Idempotency-Key: signup-8812-attempt-1

Funciona en los dos endpoints. Es opcional, pero recomendado en toda llamada que tu código pueda repetir.

Cómo se comporta

SituaciónRespuesta
Primera vez con esa claveSe procesa normalmente y se guarda la respuesta.
Misma clave, mismo cuerpoSe devuelve la respuesta guardada: el mismo estado HTTP y el mismo cuerpo. No se envía nada de nuevo.
Misma clave, cuerpo distinto422 con 20010. La clave ya está atada a otra petición.
Misma clave, la primera petición sigue en curso409 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_ y live_.
  • Admite de 1 a 255 caracteres. Fuera de ese rango responde 400 con 20002.
  • «Mismo cuerpo» significa el mismo método, la misma ruta y los mismos bytes del cuerpo.
  • Las respuestas 2xx y 4xx se guardan, 429 incluido: para reintentar tras un límite, usa una clave nueva. Un 5xx no 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.

Node.js
// 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.

Ver esta guía en docs.inalambria.com

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

400 Bad Request
{
  "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"
}
CampoPara qué sirve
codeDecide con este. Es estable: no cambia entre versiones.
titleEl nombre del error, legible y estable. Algunos códigos agrupan casos relacionados; title y field los distinguen.
detailQué pasó, en español. Puede mejorar con el tiempo: no lo compares como texto.
hintQué hacer, cuando hay una acción clara.
fieldEl campo de la petición que lo causó, cuando aplica.
request_idEl mismo valor que el encabezado X-Request-Id. Inclúyelo al pedir soporte.
typeEnlace 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 misma Idempotency-Key y retroceso exponencial.
  • 429: sí, después de esperar y con una Idempotency-Key nueva. Respeta Retry-After cuando viene.
  • 409 con 20010: sí, después del Retry-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.

Ver esta guía en docs.inalambria.com

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

EventoCuándo
verification.approvedEl usuario escribió el código correcto.
verification.expiredVenció sin una comprobación correcta.
verification.failedTerminó sin aprobarse. data.reason dice por qué: max_attempts_reached o cascade_exhausted.
verification.channel.sentUn canal aceptó el mensaje.
verification.channel.deliveredEl operador confirmó la entrega. Hoy solo lo reporta SMS.
verification.channel.failedUn 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:

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:

Cuerpo · evento de canal
{
  "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"
  }
}
CampoQué significa
channel, stepEl canal y su posición en la cascada, empezando en 0.
attempt0 en el primer envío de ese paso; cada reenvío suma uno.
send_stateEn channel.sent, siempre accepted. En channel.failed, por qué falló el envío: rejected_definitive, unavailable_transient, channel_unavailable o denied.
delivery_stateSolo 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:

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.

Node.js
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);
  });
}
Python
# 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 2xx en menos de 5 segundos. Si tienes trabajo pesado, encólalo y responde enseguida.
  • Un 408, 425, 429, un 5xx, 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 respondes Retry-After, podemos adelantar el reintento, nunca atrasarlo.
  • Cualquier otro 3xx o 4xx detiene 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. sequence está reservado y por ahora es null.
  • 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.

Ver esta guía en docs.inalambria.com

Conoce Inalambria Verify para tu negocio

SMPP y archivos

ConexiónHostPuerto
SMPP sin SSLsmsc.inalambria.com5020
SMPP con SSL/TLSsmscssl.inalambria.com6011
Mensajes entrantes (MO), modo Receiversmscmo.inalambria.com6900

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ódigoSignificado
200Recibido y en procesamiento (o token generado).
202Email: solicitud registrada; revisa el estado de cada destinatario.
400Estructura del payload inválida.
401No autorizado: revisa las credenciales.
403Permisos insuficientes, por ejemplo una IP no permitida.
500Error interno: reintenta en unos minutos o contacta a soporte.

Catálogo de servicios

ServicioEndpointHostAutenticaciónReferencia
Solicitar tokenPOST /tokenrest.inalambria.comBasicVer
SMS / RCS unidireccionalPOST /mtmessagerest.inalambria.comBearerVer
SMS en lotesPOST /mtmessage/massiverest.inalambria.comBearerVer
SMS bidireccionalPOST /momessagerest.inalambria.comBearerVer
Webhook de cuentaInalambria → tu servidor—Basic o token en URLVer
Callback por peticiónInalambria → tu servidor—Token en URLVer
WhatsAppPOST /MultiChannelInput/SendMessageMetaWhatsAppmultichannel.inalambria.comBasicVer
Enviar EmailsPOST /email/v1/deliveremailrest.inalambria.comx-api-keyVer
Plantillas de EmailGET /email/v1/templatesemailrest.inalambria.comx-api-keyVer
Verify: enviar códigoPOST /v1/verificationsverify.inalambria.comBearerVer
Verify: comprobar códigoPOST /v1/verifications/{id}/checkverify.inalambria.comBearerVer
Monitoreo de operadoresGET /platformmonitoryrest.inalambria.comBearerVer
Monitoreo de efectividadGET /bireports/effectivitybyclientrest.inalambria.comBearerVer
Monitoreo de estado de mensajesGET /bireports/msgmtclientrest.inalambria.comBearerVer
SMS por archivoSFTP / Amazon S3——Ver
SMPPsmsc.inalambria.com:5020 / :6011 (TLS)System IDVer

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

api.inalambria.express/docs · GitHub

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.