Volver¿Cómo enviar SMS?
El servicio de Envío de SMS permite a tu empresa enviar SMS a cualquier país del mundo a un precio único, indiferentemente del país de destino.
La API SMS v1.0 de netelip conecta tus aplicaciones con la pasarela de envío de SMS M2M (de máquina a máquina) de netelip: tu sistema envía y consulta SMS mediante peticiones web, sin ejecutarlos manualmente desde el panel.
Esta guía reúne todo lo necesario para integrarla —requisitos, autenticación, envío, consulta de estado, recepción, límites, códigos de error, casos de uso y preguntas frecuentes— a partir de la documentación técnica oficial de la API SMS v1.0.
Frontera funcional. La API SMS envía, consulta y entrega datos de SMS. No gestiona reservas, pedidos, citas, campañas, contactos ni reglas de negocio. Esos procesos pertenecen al sistema del cliente.
- 1. Qué es, qué permite hacer y cuándo utilizarla
- 2. Requisitos y primeros pasos
- 3. Cómo obtener y proteger el token de seguridad
- 4. Cómo enviar un SMS mediante la API
- 5. Parámetros de envío
- 6. Cómo interpretar la respuesta y guardar el ID-SMS
- 7. Cómo consultar el estado de entrega
- 8. Cómo recibir SMS mediante una URL
- 9. Límites de peticiones y códigos de error
- 10. Casos de uso de la API SMS
- 11. Preguntas frecuentes y resolución de errores
La API SMS v1.0 de netelip permite conectar una aplicación con la pasarela de envío de SMS M2M de netelip. Está pensada para que un sistema pueda realizar y controlar envíos mediante peticiones web, sin que una persona tenga que ejecutar cada envío manualmente desde el panel.
- Enviar un SMS mediante una petición POST.
- Indicar un remitente, un número de destino y el contenido del mensaje.
- Obtener un identificador único del envío, denominado ID-SMS.
- Consultar posteriormente el estado del SMS mediante su ID-SMS.
- Recibir en una aplicación los datos de un SMS entrante mediante una URL configurada para un número compatible.
La API no decide cuándo debe enviarse un mensaje ni administra el proceso que lo origina. Por ejemplo, una aplicación de reservas puede decidir que debe enviarse una confirmación y realizar la petición a netelip. La reserva continúa gestionándose en la aplicación del cliente; la API SMS realiza el envío.
- No gestiona reservas, citas, compras, envíos o expedientes.
- No crea reglas de automatización dentro del sistema del cliente.
- No ofrece en su documentación técnica plantillas, variables, listas de contactos o un CRM.
- No documenta un endpoint específico de campañas o envíos masivos.
- No documenta la programación de envíos por fecha y hora desde la API. Esa función sí aparece asociada al panel privado.
Tiene sentido utilizar la API cuando el envío o la recepción de un SMS debe formar parte de un proceso gestionado por otra aplicación. El sistema del cliente detecta el evento, construye el mensaje y llama a la API. netelip procesa el SMS y devuelve la información documentada para el envío.
En una frase. Tu aplicación gobierna el proceso; la API SMS de netelip conecta ese proceso con el envío o la recepción del SMS.
Antes de integrar la API SMS necesitas una cuenta de netelip, saldo disponible para realizar envíos, el token de seguridad de la cuenta y una aplicación capaz de enviar peticiones HTTPS de tipo POST.
- Disponer de una cuenta de netelip.
- Localizar el
tokende seguridad en el panel de control, dentro de la sección de datos personales. - Mantener saldo suficiente para el envío de SMS. La API contempla el código
402cuando el saldo es insuficiente. - Preparar los números de destino en formato internacional, comenzando por
00. - Limitar cada mensaje a un máximo de 160 caracteres.
- Definir un remitente de un máximo de 11 caracteres.
- Utilizar HTTPS para todas las peticiones.
Obtén el token de seguridad desde tu panel y guárdalo en una ubicación protegida.
Prepara un número de destino válido en formato internacional con el prefijo 00.
Construye una petición POST al endpoint de envío con los cuatro parámetros obligatorios.
Comprueba la respuesta XML.
Si el envío se acepta, guarda el valor ID-SMS devuelto.
Utiliza ese ID-SMS para consultar el estado del envío.
Importante. Los tokens, números y mensajes de los ejemplos son ficticios. Sustitúyelos por valores válidos antes de realizar una prueba.
La API SMS utiliza autenticación mediante token. Todas las peticiones documentadas deben incluir el parámetro token.
El token de seguridad se encuentra en el panel de control de netelip, en la sección de datos personales. La documentación técnica lo identifica como el valor de autenticación utilizado por la API SMS.
Incluye el token en los datos de la petición POST junto con el resto de parámetros requeridos por el endpoint que estés utilizando.
token=TU_TOKEN_DE_SEGURIDAD
netelip indica expresamente que el token no debe publicarse ni facilitarse a personal no autorizado. No lo incluyas en ejemplos públicos, documentación compartida, capturas o repositorios accesibles.
Si recibes un 401. La documentación lo identifica como un error de autenticación. Comprueba el token enviado. Consulta el detalle en códigos de error.
Para enviar un SMS, realiza una petición HTTPS de tipo POST al endpoint de envío de la API SMS v1.0.
POST https://api.netelip.com/v1/sms/api.php
| Parámetro | Tipo | Descripción |
|---|---|---|
| token | string | Token de seguridad de la cuenta. |
| from | string | Remitente que se mostrará en el SMS. |
| destination | string | Número de destino en formato internacional, comenzando por 00. |
| message | string | Contenido del SMS, con un máximo de 160 caracteres. |
Cada campo se detalla en Parámetros de envío.
curl -X POST "https://api.netelip.com/v1/sms/api.php" \ --data "token=TU_TOKEN" \ --data "from=MiEmpresa" \ --data "destination=0034666554433" \ --data "message=Tu cita ha sido confirmada"
Valores de ejemplo. El token y el número de destino no son reales. «MiEmpresa» y el contenido del mensaje solo muestran la estructura de la petición.
Cuando la petición se procesa correctamente, la API devuelve una cadena XML que incluye el estado, el ID-SMS y el saldo restante.
<?xml version="1.0"?> <response> <status>200</status> <ID-SMS>1573128467.3902</ID-SMS> <remainingbalance>4.0101</remainingbalance> </response>
Guarda el valor ID-SMS devuelto: lo necesitarás para interpretar la respuesta y para consultar el estado del envío.
Token de seguridad de la cuenta. Es obligatorio y se obtiene desde el panel de control, en la sección de datos personales.
Indica el remitente que se utilizará en el SMS. Su tamaño máximo es de 11 caracteres. La documentación técnica señala que, si se introduce un remitente con más de 11 caracteres, el remitente aparecerá vacío.
from=MiEmpresa
Número de teléfono al que se enviará el SMS. Debe escribirse en formato internacional y comenzar por 00.
destination=0034666554433
Una petición, un destino. El endpoint técnico documenta un único campo destination. No se documenta el envío de varios números separados por comas en una misma petición API; esa opción aparece en el panel de cliente.
Contenido del mensaje corto. La longitud máxima documentada es de 160 caracteres.
message=Tu pedido ha salido de nuestras instalaciones
No documentado. La API técnica no describe concatenación de mensajes, segmentación automática, plantillas, variables dinámicas ni reglas específicas de codificación. No des por hecho esos comportamientos.
Una petición de envío aceptada devuelve una respuesta XML con tres valores mostrados en la documentación: status, ID-SMS y remainingbalance.
| Campo | Qué indica |
|---|---|
| status | Código incluido en la respuesta. El ejemplo de envío correcto muestra 200. |
| ID-SMS | Identificador único del SMS enviado. Se utiliza después para consultar su estado. |
| remainingbalance | Saldo restante devuelto por la respuesta de envío. |
La consulta de estado requiere dos parámetros: el token de seguridad y el ID-SMS. Si tu aplicación necesita comprobar más tarde el resultado del envío, debe conservar el identificador devuelto en la respuesta inicial.
Realiza la petición de envío.
Comprueba la respuesta recibida.
Extrae el valor ID-SMS del XML.
Asócialo en tu sistema al registro que originó el mensaje, si necesitas mantener esa trazabilidad.
Precisión. La documentación no especifica la unidad, el formato contable ni las reglas de redondeo de remainingbalance. Limítate a tratarlo como el valor de saldo que devuelve la API.
El estado de un SMS se consulta mediante una petición POST al endpoint status.php. Necesitas el token de seguridad y el ID-SMS devuelto en el envío.
POST https://api.netelip.com/v1/sms/status.php
| Parámetro | Tipo | Descripción |
|---|---|---|
| token | string | Token de seguridad de la cuenta. |
| id-sms | string | Identificador devuelto por la petición de envío. |
curl -X POST "https://api.netelip.com/v1/sms/status.php" \ --data "token=TU_TOKEN" \ --data "id-sms=1573128467.3902"
| Estado | Información confirmada |
|---|---|
| OK | Estado posible. La respuesta de ejemplo incluye una fecha de entrega. |
| ERROR | Estado posible. La respuesta de ejemplo muestra el campo date vacío. |
| PENDING | Estado posible. La respuesta de ejemplo muestra el campo date vacío. |
Cuando el SMS figura como entregado, la respuesta puede incluir la fecha en el formato mostrado por la API. La documentación no define causas detalladas para ERROR ni un tiempo máximo de permanencia en PENDING.
<?xml version="1.0"?> <response> <status>OK</status> <date>2019-11-07 13:07:49</date> </response>
Los estados ERROR y PENDING devuelven la misma estructura con el campo date vacío.
No confundir. La API documenta una consulta activa del estado por ID-SMS. No documenta un callback automático de cambios de estado hacia la aplicación del cliente.
La recepción de SMS puede configurarse para enviarse por correo electrónico y/o a una aplicación mediante una URL. Esta función requiere un número de netelip que admita recepción de SMS y que tenga configurado el destino correspondiente.
Accede a la configuración de numeración de tu panel privado.
Localiza el número compatible que quieres utilizar.
Edita el número y configura el destino del SMS.
Indica la URL de tu aplicación si quieres recibir los datos mediante API.
Disponibilidad. No todos los números admiten recepción de SMS. Consulta la disponibilidad vigente antes de contratar o configurar la numeración.
Cuando se configura la recepción por URL, netelip envía la información mediante una petición HTTP POST a la URL indicada.
| Campo | Descripción documentada |
|---|---|
| date | Fecha de recepción con formato YYYY-MM-DD HH:II:SS. |
| from | Identificador de origen del SMS. |
| destination | Número de netelip en el que se ha recibido el SMS. |
| message | Contenido del mensaje recibido. |
date=2026-08-05 10:30:00 from=0034666554433 destination=NUMERO_NETELIP message=Confirmo mi asistencia
Seguridad pendiente de definición. La documentación pública no describe una firma, token o mecanismo específico para validar el origen de la petición entrante. No publiques instrucciones adicionales sobre esta validación sin confirmación técnica interna.
La documentación general de APIs de netelip establece para la API SMS un máximo de 3 peticiones por segundo y 120 peticiones por minuto.
| Intervalo | Límite |
|---|---|
| Por segundo | 3 peticiones |
| Por minuto | 120 peticiones |
Cada respuesta incluye cabeceras con el límite máximo y el número de peticiones restantes para cada intervalo:
X-RateLimit-Limit-second X-RateLimit-Remaining-second X-RateLimit-Limit-minute X-RateLimit-Remaining-minute
Cuando se supera uno de los límites, la API devuelve el código HTTP 429 Too Many Requests.
| Código | Nombre | Significado documentado |
|---|---|---|
| 103 | Early Hints | Parámetros erróneos. |
| 200 | OK | Petición realizada correctamente. |
| 401 | Unauthorized | Error de autenticación; comprueba el token. |
| 402 | Payment Required | Saldo insuficiente para el envío de SMS. |
| 404 | Not Found | No se ha encontrado el ID-SMS enviado. |
| 406 | Not Acceptable | Se ha omitido un parámetro obligatorio. |
| 412 | Precondition Failed | Error no reconocido. |
| 429 | Too Many Requests | Se ha superado un límite de peticiones. |
| 500 | Internal Server Error | Problema en los servidores. |
| 503 | Service Unavailable | Servicio temporalmente en mantenimiento. |
- Corrige la petición antes de repetir errores 4xx causados por parámetros, autenticación o saldo.
- Controla las cabeceras de límite para no superar la capacidad permitida.
- Ante un 500 o 503, evita repetir peticiones de forma continuada sin control.
Advertencia oficial. netelip monitoriza la repetición continuada de errores 4xx y 5xx y puede aplicar medidas de seguridad, incluido el bloqueo temporal o permanente del servicio.
La API SMS puede incorporarse a distintos procesos empresariales. En todos los casos, el sistema del cliente detecta el evento y decide el contenido; la API SMS realiza el envío o entrega los datos del mensaje recibido.
Cuando el sistema registra una reserva, puede enviar una petición a la API SMS para comunicar la confirmación. La reserva se crea y mantiene en el sistema del cliente.
Después de registrar una compra, el eCommerce o sistema de gestión puede solicitar el envío de un SMS de confirmación.
El sistema logístico puede lanzar un SMS cuando registra un evento que deba comunicarse al destinatario.
La aplicación de citas puede solicitar el envío de un recordatorio cuando se cumpla la regla definida por el cliente.
Un sistema puede comunicar un horario o un cambio cuando el proceso interno determine que debe enviarse el aviso.
Una aplicación puede generar avisos vinculados a eventos definidos por la organización, respetando los límites de peticiones de la API.
Una plataforma del cliente puede solicitar el envío de comunicaciones comerciales. La gestión de contactos, permisos, campañas y cumplimiento normativo no forma parte de la API documentada.
Un sistema puede convertir un evento interno en una petición de envío de un mensaje breve.
Cuando se dispone de un número compatible y se configura una URL, la aplicación puede recibir date, from, destination y message mediante POST.
El cliente completa una reserva en la aplicación de la empresa.
La aplicación guarda la reserva y determina que debe enviar una confirmación.
La aplicación construye el remitente, el destino y el mensaje.
La aplicación realiza una petición POST a la API SMS de netelip.
netelip devuelve la respuesta XML y el ID-SMS si la petición es correcta.
La aplicación puede guardar el ID-SMS para consultar después el estado.
Envíos a varios destinatarios. La página comercial menciona envíos masivos mediante API, pero la documentación técnica solo define un destination por petición. Una implementación basada en la documentación debe tratar cada destino mediante su petición y respetar los límites establecidos; no existe un endpoint masivo descrito públicamente.
Una cuenta de netelip, el token de seguridad, saldo suficiente para enviar SMS y una aplicación capaz de realizar peticiones HTTPS POST.
https://api.netelip.com/v1/sms/api.php
token, from, destination y message.
En formato internacional, comenzando por 00.
Un máximo de 11 caracteres.
Un máximo de 160 caracteres.
La respuesta correcta se devuelve en XML e incluye el código mostrado, el ID-SMS y remainingbalance.
Realiza una petición POST a status.php con token e id-sms.
OK, ERROR o PENDING.
La documentación técnica de la API no describe programación por fecha y hora. Esa función aparece documentada para el panel privado.
El endpoint técnico documenta un único campo destination. No define una lista de números en la misma petición.
Sí, mediante correo electrónico y/o URL, siempre que el número contratado admita recepción y se configure el destino del SMS.
La documentación pública describe la consulta por ID-SMS, pero no documenta un callback de estados.
| Problema | Comprobación |
|---|---|
| 401 | Verifica que el token sea correcto. |
| 402 | Comprueba que la cuenta tenga saldo suficiente. |
| 404 | Comprueba el ID-SMS utilizado en la consulta. |
| 406 | Revisa que no falte ningún parámetro obligatorio. |
| 429 | Reduce la frecuencia y revisa las cabeceras X-RateLimit. |
| 500 o 503 | No repitas peticiones de forma continuada; vuelve a intentarlo más tarde de forma controlada. |
- Documentación técnica: API SMS v1.0
- Restricciones generales: Documentación de APIs de netelip
- Centro de ayuda: Configuración del servicio de SMS
- Página de servicio: Envío y recepción de SMS
Para cualquier consulta técnica sobre la API SMS o la configuración de tu numeración, abre un ticket desde tu panel privado de cliente.
