API SMS v1.0
Bienvenido a la documentación de la API SMS de Netelip. API SMS de Netelip permite conectar sus aplicaciones con la pasarela de envíos SMS M2M (de máquina a máquina) de Netelip.
Tenemos ejemplos en lenguajes de shell, php y python que pueden ver en el área oscura de la derecha. Puede cambiar el lenguaje de programación de los ejemplos en las pestañas que aparecen arriba a la derecha.
Para conocer todas las APIs disponibles, información general y restricciones aplicadas a su uso consulte "Documentación APIs".
Autentificación
Todos los ejemplos de la documentación se basan en este esqueleto:
# Asegurese de pasar siempre las cabeceras correctamente.
curl -X POST https//api.netelip.com/v1/sms/{endpoint} \
--data "token=69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz"
<?php
$url="https://api.netelip.com/v1/sms/{endpoint}";
$post = array(
"token" => "69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz",
);
$request = curl_init($url);
curl_setopt($request, CURLOPT_POST, 1);
curl_setopt($request, CURLOPT_TIMEOUT, 180);
curl_setopt($request, CURLOPT_POSTFIELDS, $post);
curl_setopt($request, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($request);
if ($response !== false) {
// Manejar datos devueltos por la petición
} else {
// Manejar error de conexión
}
curl_close($request);
?>
#!/usr/bin/env python
import requests
url = 'https://api.netelip.com/v1/sms/{endpoint}'
data = {
'token': '69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz',
}
response = requests.post(url=url, data=data)
if response:
# Manejar datos devueltos por la petición
else:
# Manejar error de conexión
Reemplazar {endpoint} por el punto de entrada correcto.
El token usado es un token de ejemplo no válido.
API SMS de Netelip usa autentificación por token, para obtener su token acceda a 'Token de seguridad' que encontrará en su 'Panel de control' en sección datos personales.
Si todavía no es cliente de netelip puede registrarse en el siguiente enlace.
SMS API de Netelip espera en todas sus peticiones que se autentifique con un token similar a este:
69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz
SMS
Enviar un sms
curl -X POST https//api.netelip.com/v1/sms/api.php \
--data "token=69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz" \
--data "from=anonymous" \
--data "destination=0034666554433" \
--data "message=Esto es un mensaje de prueba"
<?php
$url = "https://api.netelip.com/v1/sms/api.php";
$post = array(
"token" => "69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz",
"from" => "anonymous",
"destination" => "0034666554433",
"message" => "Esto es un mensaje de prueba"
);
$request = curl_init($url);
curl_setopt($request, CURLOPT_POST, 1);
curl_setopt($request, CURLOPT_POSTFIELDS, $post);
curl_setopt($request, CURLOPT_TIMEOUT, 180);
curl_setopt($request, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($request);
if ($response !== false) {
$response_code = curl_getinfo($request, CURLINFO_HTTP_CODE);
switch ($response_code) {
case 200:
echo "Mensaje enviado con exito"
break;
default:
echo "Error"
}
} else {
// Manejar error de conexión
}
curl_close($request);
?>
#!/usr/bin/env python
import requests
url = 'https://api.netelip.com/v1/sms/api.php'
data = {
'token' : '69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz',
'from' : 'anonymous',
'destination': '0034666554433',
'message' : 'Esto es un mensaje de prueba'
}
response = requests.post(url=url, data=data)
if response:
if response.status_code == 200:
print('Mensaje enviado con exito')
else:
print('Error')
else:
# Manejar error de conexión
Los valores usados para los parámetros son solo de ejemplo.
En caso de éxito se devuelve una estructura en XML similar al siguiente:
<?xml version="1.0"?>
<response>
<status>200</status>
<ID-SMS>1573128467.3902</ID-SMS>
<remainingbalance>4.0101</remainingbalance>
</response>
Permite enviar sms a través de la pasarela. Para enviar un SMS se realiza una petición de tipo POST.
En la petición se debe indicar el token de autentificación, el origen, el destino y el contenido del mensaje de texto.
Para más información sobre los parámetros usados consultar el apartado 'Parámetros de las consultas'.
HTTP Request
POST https//api.netelip.com/v1/sms/api.php
Parámetros
Parametro | Tipo | Obligatorio |
---|---|---|
token | string | SI |
from | string | SI |
destination | string | SI |
message | string | SI |
Respuesta
Si la petición se realiza correctamente se devolverá una cadena en formato XML donde se incluye el código HTTP/S correspondiente y el id del mensaje sms.
Consultar los posibles códigos de error para la consulta en el apartado 'Errores'.
Obtener el estado de un sms
curl "https://api.netelip.com/v1/sms/status.php" \
--data "token=69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz" \
--data "id-sms=1573128467.3902"
<?php
$url = "https://api.netelip.com/v1/sms/status.php";
$post = array(
"token" => "69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz",
"id-sms" => "1573128467.3902",
);
$request = curl_init($url);
curl_setopt($request, CURLOPT_POST, 1);
curl_setopt($request, CURLOPT_POSTFIELDS, $post);
curl_setopt($request, CURLOPT_TIMEOUT, 180);
curl_setopt($request, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($request);
$response_code = curl_getinfo($request, CURLINFO_HTTP_CODE);
if ($response !== false) {
echo $response;
}
curl_close($request);
?>
#!/usr/bin/env python
import requests
url = 'https://api.netelip.com/v1/sms/status.php'
data = {
'token' : '69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz',
'id-sms': '1573128467.3902',
}
response = requests.post(url=url, data=data)
if response:
print(response.status_code)
Los valores usados para los parámetros son solo de ejemplo.
Ejemplo de las posibles respuestas.
OK
<?xml version="1.0"?>
<response>
<status>OK</status>
<date>2019-11-07 13:07:49</date>
</response>
ERROR
<?xml version="1.0"?>
<response>
<status>ERROR</status>
<date></date>
</response>
PENDING
<?xml version="1.0"?>
<response>
<status>PENDING</status>
<date></date>
</response>
Permite conocer el estado de entrega de un envío de sms. Para conocer el estado del mensaje SMS enviado se realizará una petición de tipo POST.
En la petición se debe indicar el token de autentificación y el id del mensaje a consultar.
Para más información sobre los parámetros usados consultar el apartado 'Parámetros de las consultas'.
HTTP Request
POST https//api.netelip.com/v1/sms/status.php
Parámetros
Parámetro | Tipo | Obligatorio |
---|---|---|
token | string | SI |
id-sms | string | SI |
Respuesta
Si la petición se realiza correctamente se devolverá una cadena en formato XML indicando el estado de entrega del sms y la fecha en la que fue entregado si es así.
Los posibles estados devueltos son OK, ERROR y PENDING.
Consultar los posibles códigos de error para la consulta en el apartado 'Errores'.
Recepción SMS
Si queremos que nuestro número de teléfono pueda recibir SMS debemos de activarlo en el apartado de numeración telefónica (Configurar los servicios -> Mis números -> Editar un número -> Destino del SMS).
Tenemos la posibilidad de recibir el SMS por correo electrónico y/o en su aplicación, a traves de nuestra API (por URL).
URL de recepción de SMS
Ejemplo de controlador para la recepción de SMS:
# Se puede capturar una petición HTTP con lenguajes scripts como bash, perl, etc.
#
# Pero se recomienda usar lenguajes como php o python para realizar esta tarea
# ya que están orientados a servicios web y puede encontrar más documentación.
#
# Elija el lenguaje php o python en las pestañas superiores para ver el ejemplo
# de un controlador.
#
# Si aún así lo necesita debe configurar correctamente su servidor web para ejecutar
# scripts (CGI).
<?php
$date = $_POST["date"];
$from = $_POST["from"];
$destination = $_POST["destination"];
$message = $_POST["message"];
// Aquí se ejecuta el código que gestiona los datos
?>
#!/usr/bin/env python
import json
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/smsmanager', methods=['POST'])
def controller():
if request.method == 'POST':
sms = {
'date': request.form.get('date'),
'from': request.form.get('from'),
'destination': request.form.get('destination'),
'message': request.form.get('message'),
}
# Aquí se ejecuta el código que gestiona los datos
return jsonify(result='OK')
else:
return jsonify(error='Metodo no permitido')
if __name__ == '__name__':
app.run()
En la recepción de SMS por URL, la información será enviada mediante HTTP POST a la URL indicada.
En la siguiente tabla se indican los parámetros pasados y una breve descripción.
Parámetro | Descripción |
---|---|
date | Fecha en la que se recibe el SMS, con el siguiente formato YYYY-MM-DD HH:II:SS. |
from | Identificador origen del SMS. |
destination | Número de teléfono de netelip en el que se ha recibido el SMS. |
message | Contenido del mensaje. |
Parámetros de las consultas
token
Ejemplo de token:
69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz
Token de seguridad que encontrará en su panel de control, sección datos personales
from
Ejemplo de from anónimo:
anonymous
Ejemplo de from fijo:
951223344
Indica el remitente a usar. El tamaño para el remitente es de 11 caracteres,
en caso de añadir un remitente con más de 11 caracteres, el remitente
aparecerá como "
destination
Ejemplo de móvil español:
0034666554433
Ejemplo de fijo español:
0034951223344
Número de teléfono de destino. El número debe estar escrito en formato internacional con "00" delante.
message
Ejemplo de message:
Esto es un mensaje de prueba.
Contenido del mensaje corto a enviar. El número máximo de caracteres en un mensaje SMS es de 160 caracteres.
id-sms
Ejemplo de id-sms:
1573128467.3902
Identificador del SMS enviado, devuelto en la petición de envío.
Errores
API SMS de Netelip usa los siguientes códigos de error.
Cód. Error | Significado |
---|---|
103 | Early Hints -- Parámetros erroneos. |
200 | OK -- Petición realizada correctamente. |
401 | Unauthorized -- Error de autentificación, compruebe token. |
402 | Payment required -- Saldo insuficiente para el envío sms. |
404 | Not Found -- No encontrado ID del sms enviado. |
406 | Not Acceptable -- Parámetro obligatorio omitido. |
412 | Precondition failed -- Error no reconocido. |
500 | Internal Server Error -- Hemos tenido problema con nuestros servidores, intentelo de nuevo. |
503 | Service Unavailable -- El servicio está temporalmente en mantenimiento. Por favor intentelo más tarde. |