Solicitar demo

Inicio › SMS masivo › API de SMS

API REST

API de SMS para empresas en Perú

Conecta tu sistema, app o e-commerce y envía códigos OTP, alertas, recordatorios y campañas a Claro, Movistar, Entel y Bitel con una API REST. Latencia de API menor a 1 segundo, hasta 10 mil SMS por minuto, reportes de entrega en tiempo real y soporte técnico en Lima.

Actualizado: 7 de octubre de 2026

¿Qué es la API de SMS de Clicklab?

Es una interfaz REST que permite a tus sistemas enviar y recibir SMS sin intervención manual: tu plataforma hace una petición HTTPS con el número y el texto, y el mensaje llega al celular en segundos. Sirve para todo lo que debe salir de forma automática, como códigos de verificación OTP, alertas de transacciones, confirmaciones de pedido o recordatorios de pago.

Paso 1

Solicita tu cuenta

Te damos acceso al portal Clicklab y una cuenta de prueba para validar el envío con tu propio caso.

Paso 2

Copia tu API key

En el portal obtienes tu API key y la URL base de la API. Puedes crear varias keys con permisos limitados.

Paso 3

Envía tu primer SMS

Haz una petición POST al endpoint de envío con el remitente, el número y el texto. Abajo tienes el código listo.

Envía tu primer SMS por API

Reemplaza TU_URL_BASE y TU_API_KEY por los datos de tu portal Clicklab. El número va en formato internacional: 51 seguido de los 9 dígitos del celular. Como remitente puedes usar el código corto 13579, sin costo adicional, o el nombre de tu empresa.

curl -X POST "https://TU_URL_BASE/sms/3/messages" \
  -H "Authorization: App TU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "messages": [{
      "sender": "TuMarca",
      "destinations": [{ "to": "51987654321" }],
      "content": { "text": "TuMarca: 482913 es tu clave de acceso. Vence en 5 minutos." }
    }]
  }'

Respuesta

{
  "bulkId": "2034072219640523072",
  "messages": [{
    "messageId": "2250be2d4219-3af1-78856-aabe-1362af1edfd2",
    "status": { "groupName": "PENDING", "name": "PENDING_ACCEPTED" },
    "destination": "51987654321",
    "details": { "messageCount": 1 }
  }]
}

El messageId identifica cada SMS y te permite seguir su estado. messageCount indica en cuántas partes se dividió el mensaje: cada parte se cobra como un SMS. Revisa tus textos con el contador de caracteres SMS.

Endpoints de la API de SMS

Todas las rutas se llaman sobre tu URL base, por HTTPS, con la cabecera Authorization: App TU_API_KEY y cuerpo en JSON.

Método y ruta

Para qué sirve

Detalle

POST /sms/3/messages

Enviar SMS

Uno o miles de mensajes, personalizados por destinatario, en una sola petición

GET /sms/3/text/query

Enviar SMS por URL

Para integraciones simples que solo pueden hacer peticiones GET

POST /sms/1/preview

Previsualizar

Cuenta caracteres y partes antes de enviar

GET · PUT /sms/1/bulks

Envíos programados

Consulta o reprograma un envío por su bulkId

GET · PUT /sms/1/bulks/status

Estado de programados

Pausa, reanuda o cancela un envío programado

GET /sms/3/reports

Reportes de entrega

Descarga los reportes que aún no recibiste por webhook

GET /sms/3/logs

Logs de envío

Historial de las últimas 48 horas, hasta 1000 registros por consulta

GET /sms/1/inbox/reports

SMS recibidos

Respuestas de tus clientes (requiere número propio)

POST /ct/1/log/end/{messageId}

Confirmar conversión

Marca un OTP como validado para medir tu tasa de conversión

Funciones para enviar mejor

Todo se configura en la misma petición de envío, sin pasos adicionales.

  • Programación: elige fecha y hora de envío con hasta 180 días de anticipación.
  • Franja horaria de entrega: define días y horas en que se permite entregar, ideal para respetar los horarios de cobranza.
  • Velocidad de envío: limita los mensajes por minuto, hora o día para no saturar tu call center.
  • Vigencia del mensaje: si no se entrega a tiempo, deja de intentarse (máximo 48 horas).
  • Personalización: un texto distinto por destinatario en la misma petición.
  • Transliteración: reemplaza tildes y caracteres especiales para mantener los 160 caracteres.
  • Enlaces cortos y clics: acorta las URL del mensaje y mide quién hizo clic.
  • Campañas: agrupa envíos con un identificador para medirlos juntos.

Ejemplo: envío programado, en horario hábil, con reporte de entrega y enlaces rastreados

{
  "messages": [{
    "sender": "TuMarca",
    "destinations": [{ "to": "51987654321" }, { "to": "51912345678" }],
    "content": { "text": "TuMarca: tu cuota de S/ 150.00 vence el 15/10. Paga en tumarca.pe/pagar" },
    "options": {
      "deliveryTimeWindow": {
        "days": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
        "from": { "hour": 14, "minute": 0 },
        "to": { "hour": 23, "minute": 0 }
      }
    },
    "webhooks": { "delivery": { "url": "https://tusistema.pe/reportes-sms" } }
  }],
  "options": {
    "schedule": { "sendAt": "2026-10-15T09:00:00.000-0500" },
    "tracking": { "shortenUrl": true, "trackClicks": true },
    "includeSmsCountInResponse": true
  }
}

Se envía a POST /sms/3/messages. La franja horaria se expresa en UTC: de 14:00 a 23:00 UTC equivale a 9 a. m. a 6 p. m. en Perú.

Reportes de entrega, webhooks y respuestas

Indica una URL de tu sistema en cada envío y recibirás el reporte de entrega de cada SMS en tiempo real, por webhook. Si tu servidor no está disponible, puedes descargar los reportes pendientes por API. Con el campo callbackData agregas tus propios datos (por ejemplo, el ID del pedido) y vuelven junto con el reporte.

Estado

Qué significa

Qué hacer

PENDING

El mensaje fue aceptado y está en camino al operador

Esperar el reporte final

DELIVERED

El SMS llegó al celular

Nada: entrega confirmada

UNDELIVERABLE

El operador no pudo entregarlo (número inexistente, apagado por mucho tiempo, etc.)

Revisar el número o usar otro canal

EXPIRED

Venció la vigencia sin poder entregarse

Reintentar o cambiar de canal

REJECTED

Rechazado antes del envío (destino o remitente no válido, saldo, etc.)

Corregir la petición

Para recibir las respuestas de tus clientes necesitas SMS de dos vías, que se activa con un número propio: cada respuesta llega a tu URL por webhook o se consulta por API.

Seguridad, librerías y límites

  • API keys con permisos: crea una key por sistema y limítala solo a las llamadas que necesita.
  • HTTPS en todas las llamadas y autenticación en la cabecera de cada petición.
  • Rutas directas con Claro, Movistar, Entel y Bitel, sin intermediarios.
  • Librerías oficiales en Java, C#, PHP, Go y Python, además de la API REST.
  • Alto volumen: hasta 10 mil SMS por minuto desde la API de envío.
  • Errores claros: 401 si la key no es válida, 403 si no tiene permiso y 429 si se excede el uso en llamadas de consulta.

Qué puedes automatizar con la API

Verificación OTP

Códigos de acceso que llegan en menos de 4 segundos, con respaldo automático por WhatsApp o voz.

Ver verificación OTP →

Cobranzas y recordatorios

Avisos de vencimiento y confirmaciones de pago disparados desde tu sistema.

Ver cobranzas →

Sin programar

Si usas Shopify, VTEX, HubSpot, Zapier u otras herramientas, conéctalas sin escribir código.

Ver integraciones →

Preguntas frecuentes sobre la API de SMS

¿Qué es una API de SMS?

Es una interfaz que permite a un sistema enviar y recibir SMS de forma automática mediante peticiones HTTPS, sin usar un panel manual. Se usa para OTP, alertas, confirmaciones y recordatorios.

¿Cómo obtengo mi API key?

Al activar tu cuenta te damos acceso al portal Clicklab, donde copias tu API key y la URL base de la API. Puedes crear varias keys y limitar los permisos de cada una.

¿Cuánto cuesta enviar SMS por API?

Pagas por SMS enviado: desde S/ 0.038 + IGV por SMS en volúmenes desde 2 millones, con bolsas desde 1,000 SMS y sin costo de activación. Si un mensaje se divide en partes, cada parte se cobra como un SMS. Revisa la guía de precios.

¿Puedo programar envíos y limitar el horario de entrega?

Sí. Puedes programar el envío con hasta 180 días de anticipación, definir días y horas en que se permite entregar y limitar la velocidad de envío.

¿Cómo sé si el SMS llegó?

Cada SMS tiene un identificador y un estado. Recibes el reporte de entrega en tu sistema por webhook o lo consultas por API.

¿Puedo recibir respuestas de mis clientes?

Sí, con SMS de dos vías, que se activa con un número propio (costo adicional). Las respuestas llegan a tu sistema por webhook o se consultan por API.

¿Hay librerías para mi lenguaje?

Sí. Además de la API REST, hay librerías oficiales en Java, C#, PHP, Go y Python.

API de SMS

Empieza a integrar hoy

Solicita tu cuenta de prueba y recibe tu acceso al portal Clicklab con tu API key. Conoce también el servicio de SMS masivos y el contador de caracteres.