Para developers

API SMS en España: una API REST de mensajería multicanal para SMS, WhatsApp y Telegram

Integra el envío de SMS, WhatsApp Business API y Telegram con una sola API REST en JSON: autenticación con X-Api-Key, idempotencia nativa, webhooks de estado firmados con HMAC-SHA256, rate limit configurable, errores claros y un modo sandbox para integrar sin gastar un euro.

Crea tu cuenta gratis Cómo funciona el modo sandbox

Idempotencia nativa
Webhooks firmados HMAC-SHA256
Sandbox sin coste
Saldo sin caducidad

Envía tu primer SMS con la API REST en cinco minutos

Sin SDK obligatorio, sin whitelist de IP, sin hablar con ventas para activar canales: una petición HTTPS con JSON y tu mensaje está en cola.

1. Crea tu cuenta

Regístrate gratis. La cuenta nace pendiente y una persona la revisa antes de habilitar el envío real; el modo sandbox te deja integrar y probar la API sin gastar saldo y sin que salga ningún mensaje.

2. Copia tus credenciales

En el panel encontrarás tu api_key (formato sk_live_…) y tu api_secret. Se envían en las cabeceras X-Api-Key y X-Api-Secret de cada petición, siempre sobre HTTPS. El secreto se muestra una sola vez, al generarlo. Si vienes de otra plataforma, son los mismos dos campos que ya tienes configurados: solo cambian los valores.

3. Haz el POST

Llama a POST /api/v1/messages con el canal, el destinatario en formato E.164 y el texto. El remitente va en from y es opcional: si no lo indicas se usa el remitente por defecto de la plataforma. La respuesta te devuelve el mensaje creado, su coste en euros y su estado.

terminal — enviar un SMS

curl -X POST https://app.smsverifica.com/api/v1/messages \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Idempotency-Key: pedido-1234-confirmacion" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+34612345678",
    "from": "MITIENDA",
    "body": "Tu pedido 1234 ha sido enviado. Lo recibiras manana antes de las 14:00."
  }'

respuesta — 201 Created

{
  "data": {
    "id": 98231,
    "channel": "sms",
    "direction": "out",
    "to": "+34612345678",
    "from": "MITIENDA",
    "status": "queued",
    "cost_eur": "0.0390",
    "queued_at": "2026-07-08T10:15:02+02:00",
    "created_at": "2026-07-08T10:15:02+02:00"
  }
}

El destinatario se normaliza a E.164 y el prefijo del país se detecta automáticamente para aplicar la tarifa correcta (consulta las tarifas de SMS por país). El coste se descuenta de tu saldo de forma transaccional al encolar y, si el mensaje falla de forma definitiva, se reembolsa automáticamente.

Una sola API de mensajería multicanal: SMS, WhatsApp Business API y Telegram

El mismo endpoint, el mismo JSON y los mismos webhooks para los tres canales: cambiar de SMS a WhatsApp o a Telegram es cambiar el valor de un campo. Así es una API WhatsApp Business y una API de Telegram que no te obligan a aprender tres integraciones distintas.

Enviar una plantilla de WhatsApp Business API

Envía plantillas aprobadas por Meta con variables e indica la categoría de conversación para una tarificación exacta por mensaje (precios de WhatsApp por categoría). El texto libre dentro de la ventana de servicio de 24 horas también está soportado.

terminal — enviar WhatsApp con plantilla

curl -X POST https://app.smsverifica.com/api/v1/messages \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Idempotency-Key: entrega-5566-aviso" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+34612345678",
    "template_name": "aviso_entrega",
    "template_vars": { "1": "Maria", "2": "jueves de 9:00 a 14:00" },
    "category": "utility"
  }'

Enviar un mensaje de Telegram (0,010 € por mensaje)

Conecta tu propio bot y envía notificaciones de Telegram a 0,010 € por mensaje. Nuestro webhook de Telegram captura automáticamente el chat_id cuando el cliente inicia conversación con tu bot; a partir de ahí, envías usando su número de teléfono como referencia.

terminal — enviar Telegram

curl -X POST https://app.smsverifica.com/api/v1/messages \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Idempotency-Key: visita-889-recepcion" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "to": "+34612345678",
    "body": "Tu visita acaba de llegar a recepcion. Aviso automatico de QRACCESO."
  }'

Consultar tu saldo de saldo

terminal — saldo de la cuenta

curl https://app.smsverifica.com/api/v1/account/balance \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret"

# {"data":{"balance_eur":"842.3100"}}

Crear una campaña completa con una sola petición

Esto casi no se ve en el mercado español: una API de campañas de verdad. Con POST /api/v1/campaigns lanzas un envío masivo a toda una lista de contactos, con programación de fecha y validación de saldo previa; la plataforma calcula el coste, encola los mensajes y actualiza los contadores de enviados, entregados, fallidos y leídos en tiempo real.

terminal — crear campaña programada

curl -X POST https://app.smsverifica.com/api/v1/campaigns \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "name": "Recordatorio ITV octubre",
    "contact_list_id": 42,
    "body": "Tu ITV caduca este mes. Reserva cita en tu taller de confianza.",
    "scheduled_at": "2026-10-01T09:00:00+02:00"
  }'

# {"data":{"id":57,"status":"scheduled","total":1840,"cost_estimate":"71.7600", ...}}

Si prefieres empezar por el panel antes de integrar, el manual de usuario recorre cada pantalla con capturas.

Mensajería certificada por API: dos endpoints y a producción

La mensajería certificada —expediente de evidencias encadenadas y PDF verificable— va incluida en la misma API REST, sin módulos aparte ni contratos adicionales: no todos los proveedores la ofrecen por API, y quien integró la de otro y se quedó sin ella puede migrar aquí con dos endpoints. El suplemento por certificar es 0,25 € por mensaje, igual en los tres canales, sobre el precio del canal.

terminal — enviar una notificación certificada

curl -X POST https://app.smsverifica.com/api/v1/certified \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: notif-2026-0001" \
  -d '{
    "channel": "sms",
    "to": "+34612345678",
    "subject": "Requerimiento de pago",
    "content": "Texto íntegro que quedará certificado en el expediente."
  }'

# {"data":{"id":31,"status":"queued","content_hash":"5f1c…","portal_url":"…/c/…", ...}}
# El PDF de evidencias, cuando lo necesites: GET /api/v1/certified/31/certificate

Disponible hoy solo a España (+34) y como servicio de entrega electrónica certificada no cualificado (art. 3.36 del Reglamento eIDAS), con sello de tiempo cualificado de Camerfirma en cada expediente — los límites y lo que prueba cada cosa, en la página de la mensajería certificada.

Todos los endpoints de la API v1

Endpoints de la API REST v1 (prefijo `/api/v1`)
Método y ruta	Qué hace
`POST /messages`	Envía un SMS, WhatsApp o Telegram. Admite `Idempotency-Key`.
`GET /messages/{id}`	Consulta un mensaje: estado, coste, timestamps de todo el ciclo de vida.
`GET /messages`	Lista tus mensajes con paginación y filtros.
`POST /campaigns`	Crea y confirma una campaña masiva sobre una lista de contactos, con programación opcional.
`GET /campaigns/{id}`	Estadísticas de campaña: enviados, entregados, fallidos, leídos y coste.
`POST /verify/start`	Envía un código OTP de verificación por SMS, WhatsApp o Telegram.
`POST /verify/check`	Comprueba el código OTP (un código erróneo es 200 con `status: invalid`).
`POST /certified`	Envía una comunicación certificada: expediente de evidencias + portal del destinatario.
`GET /certified/{id}`	Estado del expediente certificado: aperturas, lectura, firma.
`GET /certified/{id}/certificate`	Descarga el PDF de evidencias (se emite al pedirlo).
`GET /account/balance`	Saldo de saldo en tiempo real.
`GET /pricing/sms`	Tarifas de SMS por prefijo de país, siempre actualizadas.

Idempotencia nativa: reintenta sin miedo a envíos duplicados

Un timeout de red en el peor momento y tu cliente recibe dos veces el mismo SMS... y tú lo pagas dos veces. Con SMSverifica eso no puede pasar.

Añade la cabecera Idempotency-Key a tu POST /messages con un identificador único de tu operación (por ejemplo, pedido-1234-confirmacion). Si repites la petición — porque tu job la reintentó, porque hubo un timeout, porque tu proceso se reinició — la API no crea un segundo mensaje ni cobra dos veces: te devuelve la respuesta original con la cabecera X-Idempotency-Replayed: true.

Esto es idempotencia de envío nativa, integrada en la propia API, y es un diferencial real: ninguno de los proveedores españoles de SMS la documenta en su API, y tampoco lo hacen las grandes plataformas internacionales de mensajería en su endpoint de envío. Si construyes sistemas serios — colas, reintentos con backoff, workers — sabes exactamente por qué importa.

La comprobación, documentación en mano y con fecha de consulta, está en las comparativas con Twilio, LabsMobile, Esendex, Instasent y BulkGate.

segunda petición idéntica — respuesta reproducida

# Repetimos el mismo POST con la misma Idempotency-Key
curl -i -X POST https://app.smsverifica.com/api/v1/messages \
  -H "Idempotency-Key: pedido-1234-confirmacion" \
  ...

HTTP/2 201
X-Idempotency-Replayed: true

# Mismo JSON, mismo message id: cero duplicados, cero doble cobro

Webhooks de estado firmados con HMAC-SHA256, con reintentos y reenvío manual

Recibe en tu servidor cada transición de estado — message.sent, message.delivered, message.failed, message.read, message.received y campaign.completed — con una firma criptográfica que te permite verificar que el aviso es auténtico. De los proveedores españoles cuya documentación revisamos en julio de 2026, ninguno firmaba sus notificaciones de entrega; nosotros lo hacemos en todas.

POST a tu endpoint — payload firmado

X-Signature: sha256=7f83b1657ff1fc53b92dc18148a1d6...
Content-Type: application/json

{
  "event": "message.delivered",
  "delivery_id": 4521,
  "timestamp": "2026-07-08T10:15:09+02:00",
  "data": {
    "id": 98231,
    "channel": "sms",
    "to": "+34612345678",
    "status": "delivered",
    "delivered_at": "2026-07-08T10:15:08+02:00"
  }
}

verificar la firma en PHP

// El secreto lo defines por webhook en tu panel
$cuerpo = file_get_contents('php://input');
$esperada = 'sha256=' . hash_hmac('sha256', $cuerpo, $secreto);

if (hash_equals($esperada, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) {
    // Payload auténtico: procesa el evento
}

Firma HMAC-SHA256

Cada entrega lleva la cabecera X-Signature: sha256=<hmac> calculada sobre el cuerpo exacto con tu secreto. Verificarla son tres líneas de código en cualquier lenguaje.

Reintentos automáticos

Si tu endpoint no responde 2xx, reintentamos hasta 5 veces con esperas crecientes (1 min, 5 min, 15 min, 1 h, 4 h). Semántica at-least-once: usa delivery_id para deduplicar.

Log y reenvío manual

Cada intento queda registrado en tu panel con código de respuesta y fecha. ¿Tu servidor estuvo caído? Reenvía la entrega manualmente con un clic, sin abrir tickets.

Modo sandbox: integra la API sin gastar un solo euro

Un entorno de simulación documentado, sin coste: integra y prueba sin gastar saldo y sin que salga ningún mensaje real.

Con el modo sandbox activado, tus peticiones a la API se comportan exactamente igual que en producción — mismos endpoints, mismas respuestas, mismos webhooks firmados — pero ningún mensaje sale a la red y el coste es 0,0000 de saldo. El simulador recorre el ciclo de vida completo del mensaje: queued → sent → delivered (o failed/read), disparando tus webhooks en cada transición para que pruebes tu integración de punta a punta.

Además dispones de números de prueba (magic numbers) que fuerzan cada estado final — entregado, fallido, leído — para verificar cómo reacciona tu aplicación ante cada escenario, incluido el reembolso automático de un envío fallido. Todo documentado en tu panel, sin tarjeta y sin caducidad de la cuenta de pruebas.

Cómo funciona, sin adornos: el registro crea la cuenta en estado pendiente y en modo sandbox; en sandbox no sale ningún mensaje y no se gasta saldo. Una persona revisa el alta antes de habilitar el envío real. Cualquier duda, escríbenos.

Crea tu cuenta gratis

Qué puedes probar en sandbox

Envíos SMS, WhatsApp y Telegram con respuesta JSON real
Webhooks de estado firmados en cada transición
Estados forzados con números de prueba: entregado, fallido, leído
Idempotencia con Idempotency-Key y respuestas reproducidas
Campañas completas con estimación de coste
Manejo de errores: 402, 422, 429 y validaciones por campo

Errores JSON claros y rate limit configurable por cuenta

Todos los errores comparten el mismo formato — {"error":{"code":"<slug>","message":"..."}} — con un código estable sobre el que puedes programar y un mensaje legible para humanos. Las validaciones incluyen el detalle por campo.

Códigos de error de la API v1
HTTP	Código	Cuándo ocurre
401	`unauthorized`	API key o secreto inválidos.
402	`insufficient_balance`	Saldo insuficiente: el mensaje o la campaña no se encolan. Nunca hay envíos a medias.
403	`account_not_active`	Cuenta pendiente de aprobación o suspendida.
404	`not_found`	El recurso no existe o pertenece a otra cuenta (aislamiento multi-tenant).
422	`validation_failed`	Datos inválidos; incluye `details` con los errores por campo.
422	`wa_outside_window`	Texto libre de WhatsApp fuera de la ventana de servicio de 24 h: usa una plantilla.
422	`telegram_no_chat_id`	El contacto aún no ha iniciado conversación con tu bot de Telegram.
422	`no_provider`	No hay proveedor configurado para ese canal en tu cuenta.
422	`no_pricing`	Prefijo de destino sin tarifa: nunca enviamos a ciegas ni gratis por error.
429	`rate_limited`	Superado tu límite de peticiones por minuto.

Rate limit por cuenta, no por plataforma

Cada cuenta tiene su propio límite — 60 peticiones por minuto por defecto, ampliable según tu volumen real —, así que el tráfico de otros clientes jamás afecta al tuyo. Para envíos masivos no necesitas martillear la API: POST /campaigns despacha miles de mensajes con una única petición y con throttle controlado hacia los operadores.

402: sin saldo, sin sorpresas

Si tu saldo no cubre el envío recibes un 402 insufficient_balance inmediato y nada se encola. El descuento de saldo es transaccional, con reembolso automático si el mensaje falla de forma definitiva, y puedes activar la auto-recarga con umbral para que el saldo nunca te frene. Consulta el modelo de saldo sin caducidad.

Una plataforma multi-tenant con cuentas aprobadas manualmente

La calidad de entrega de tus SMS depende de la reputación de las rutas. Por eso no dejamos entrar a cualquiera.

Cada alta en SMSverifica la revisa una persona antes de activar la cuenta. Ese filtro antispam mantiene limpias nuestras rutas y remitentes, y busca que tu tráfico legítimo —tus OTP, tus avisos de entrega, tus campañas— no comparta ruta con envíos basura. El modo sandbox no espera a esa revisión: se abre solo al verificar tu correo, y la revisión humana desbloquea después el envío real y los pagos.

El aislamiento entre cuentas es total: tus mensajes, contactos, campañas y credenciales viven bajo tu account_id y son invisibles para cualquier otra cuenta. Las credenciales de canal se guardan cifradas en base de datos y puedes rotar tu api_secret desde el panel en cualquier momento.

Aprobación manual antispam: mejor reputación de rutas y remitentes
Aislamiento multi-tenant verificado con tests automáticos
Credenciales cifradas y rotación de secretos self-service
RGPD y LSSI: servidores en la UE y facturación española con IVA
Enrutado configurable por canal: cada cuenta define su proveedor principal y, si tiene contratado un segundo, uno de respaldo dentro del mismo canal
Saldo sin caducidad: tu saldo de integración no expira nunca

Preguntas frecuentes sobre la API de SMS y mensajería

¿Puedo usar la API de SMS desde PHP, Python, Node.js o cualquier otro lenguaje?

Sí. Es una API REST estándar con JSON sobre HTTPS: cualquier lenguaje capaz de hacer una petición HTTP puede enviar SMS, WhatsApp y Telegram. Los ejemplos curl de esta página se trasladan tal cual a PHP (cURL/Guzzle), Python (requests), Node.js (fetch/axios), Java, C# o Go.

¿Necesito tarjeta para probar la API?

No, y el modo sandbox tampoco: simula todo el ciclo de vida del mensaje (encolado, enviado, entregado, fallido, leído) con coste 0 y sin que salga ningún mensaje real. El envío real se habilita cuando una persona revisa y aprueba tu cuenta.

¿Cómo recibo los estados de entrega de los mensajes?

De dos formas: consultando GET /api/v1/messages/{id} o, mejor, recibiendo webhooks de estado en tu servidor (message.sent, message.delivered, message.failed, message.read, message.received y campaign.completed). Cada webhook va firmado con HMAC-SHA256 en la cabecera X-Signature y se reintenta automáticamente con esperas crecientes si tu endpoint no responde.

¿Qué pasa si mi cuenta se queda sin saldo?

La API responde 402 con el código insufficient_balance y el mensaje no se encola: nunca hay envíos a medias ni sorpresas en la facturación. Puedes activar la auto-recarga con umbral para que el saldo se reponga solo.

¿Qué límite de peticiones tiene la API?

Cada cuenta tiene un rate limit propio, 60 peticiones por minuto por defecto, ampliable bajo petición según tu volumen. Si lo superas recibes un 429 (rate_limited) estándar. Para envíos masivos usa POST /campaigns: una sola petición para miles de destinatarios.

¿Qué ocurre si envío dos veces la misma petición POST /messages?

Si incluyes la cabecera Idempotency-Key, la segunda petición no genera un envío ni un cobro duplicado: la API devuelve la respuesta original con la cabecera X-Idempotency-Replayed: true. Es idempotencia nativa de la API, ideal para reintentos seguros tras un timeout.

Crea tu cuenta y envía tu primer SMS por API

Cuenta gratis y sin tarjeta, con modo sandbox sin tarjeta, alta revisada a mano, saldo sin caducidad y soporte en español de gente que ha leído tu misma documentación. ¿Montas verificación de usuarios? Mira también la API de verificación OTP por SMS.

Crea tu cuenta gratis API de verificación OTP