Documentación APIs
Bienvenido al centro de documentación de las APIs de Netelip.
Netelip pone a disposición de sus clientes todas sus APIs en un solo punto de
acceso.
https://api.netelip.com
A través de este punto puede conectar con los servicios que dispongan de API y desarrollar su propio software para gestionarlos.
Las APIs de Netelip disponen de 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.
¿Que es una API?
Una API (Application Programming Interface) y en concreto una API web es una aplicación web preparada para comunicarse con otros programas y no apta para humanos ya que la interacción se debe hacer con herramientas adicionales al navegador o con software diseñado para este propósito.
APIs disponibles
Ejemplo de punto de acceso a una API:
https://api.netelip.com/v1/sms/status.php
Todas las APIs están disponibles desde el punto de acceso:
https://api.netelip.com
Para acceder a la API ha de saber la versión,el nombre de esta y el punto de acceso:
https://api.netelip.com/{version}/{apiname}/{endponit}
SMS
Url base:
https://api.netelip.com/v1/sms/
API SMS de Netelip permite conectar sus aplicaciones con la pasarela de envíos SMS M2M (de máquina a máquina) de Netelip.
Actualmente API SMS se encuentra en la versión estable 1.0.
Puede consultar la documentación completa de API SMS v1.0.
FAX
Url base:
https://api.netelip.com/v1/fax/
API Fax de Netelip permite conectar sus aplicaciones con la pasarela de envíos Fax M2M (de máquina a máquina) de Netelip a través de interfaz HTTPS.
Actualmente API FAX se encuentra en la versión estable 1.0.
Puede consultar la documentación completa de API Fax v1.0.
VOICE
Url base:
https://api.netelip.com/v1/voice/
API Voice facilita a tus aplicaciones WEB el control en vivo de tus llamadas de teléfono, tanto entrantes como salientes, permitiéndote realizar acciones sobre estas en función de lo que el emisor o receptor diga o marque en el teclado de su teléfono. Podrás montar fácilmente servicios telefónicos de reservas, gestión de cobros, control de acceso a IVRs, encuestas telefónicas, etc
Actualmente API Voice se encuentra en la versión estable 1.0.
Puede consultar la documentación completa de API Voice v1.0.
Restricciones
Para garantizar la máxima disponibilidad del servicio Netelip aplica distintos criterios de seguridad y restricciones al acceso de sus APIs.
HTTPS
Todas las peticiones de acceso a las APIs de netelip serán a través de https.
Los accesos a http serán redirigidos a https con el consiguiente retardo.
Errores 4xx
Las respuestas de tipo 4xx que devuelve un servidor web son en su mayoría errores provocados por el cliente debidos a una petición mal formada, falta de crédito, etc.
La ejecución continuada de peticiones que provocan errores 4xx en algunos casos se puede considerar un ataque o exploración de vulnerabilidades no autorizado.
Netelip monitoriza los errores de tipo 4xx y se reserva el derecho de aplicar las medidas de seguridad pertinentes. En el caso de repetirse este comportamiento puede derivar en un bloqueo del servicio temporal o permanente.
Errores 5xx
Las repuestas de tipo 5xx que devuelve un servidor web son errores internos debidos a un mal funcionamiento en el servidor o por no poder procesar la petición.
La ejecución continuada de peticiones que provocan errores 5xx en algunos casos se puede considerar un ataque o exploración de vulnerabilidades no autorizado.
Netelip monitoriza los errores de tipo 5xx y se reserva el derecho de aplicar las medidas de seguridad pertinentes. En el caso de repetirse este comportamiento puede derivar en un bloqueo del servicio temporal o permanente.
Límite de peticiones
Netelip aplica límites de peticiones por intervalo de tiempo para asegurar y garantizar que no se realicen usos abusivos o fraudulentos de los servicios.
Límites aplicados:
API | Peticiones/segundo | Peticiones/minuto |
---|---|---|
SMS | 3 | 120 |
FAX | 3 | 120 |
VOICE | 3 | 120 |
En todo momento podrá gestionar sus peticiones y saber cuantas peticiones tiene permitidas.
Las APIs de Netelip devolverán en cada petición los valores límite de peticiones y el número restante de peticiones que quedan por realizar en todos los intervalos definidos.
Estos valores son entregados en cada petición mediante las cabeceras de la respuesta a dicha petición.
Headers: limits
Ejemplo de petición:
curl -I -X POST https://api.netelip.com/v1/sms/status.php
<?php
function get_headers_from_curl_response($response)
{
$headers = array();
$header_text = substr($response, 0, strpos($response, "\r\n\r\n"));
foreach (explode("\r\n", $header_text) as $i => $line)
if ($i === 0)
$headers['http_code'] = $line;
else {
list ($key, $value) = explode(': ', $line);
$headers[$key] = $value;
}
return $headers;
}
$url = "https://api.netelip.com/v1/fax/status.php";
$post = array(
"token" => "69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz",
// resto de valores de la petición
);
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, 1);
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);
$info = curl_getinfo($request);
$headers = get_headers_from_curl_response($response);
echo "Por segundo - límite: ".$headers['X-RateLimit-Limit-second']." por gastar: ".$headers['X-RateLimit-Remaining-second']."\n";
echo "Por minuto - límite: ".$headers['X-RateLimit-Limit-minute']." por gastar: ".$headers['X-RateLimit-Remaining-minute']."\n";
curl_close($request);
?>
#!/usr/bin/env python
# -*- coding: utf-8 -*-
import requests
url = 'https://api.netelip.com/v1/fax/status.php'
data = {
'token' : '69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz',
# resto de valores de la petición
}
response = requests.post(url=url, data=data)
h = response.headers
print("Pet/seg: Max: {} Pendientes: {}".format(h['X-RateLimit-Limit-second'], h['X-RateLimit-Remaining-second']))
print("Pet/min: Max: {} Pendientes: {}".format(h['X-RateLimit-Limit-minute'], h['X-RateLimit-Remaining-minute']))
Ejemplo de respuesta:
curl -I -X POST https://api.netelip.com/v1/sms/status.php
HTTP/1.1 500 Internal Server Error
Content-Type: text/html; charset=UTF-8
...
...
X-RateLimit-Remaining-second: 2
X-RateLimit-Limit-second: 3
X-RateLimit-Remaining-minute: 119
X-RateLimit-Limit-minute: 120
...
...
Por segundo - límite: 3 por gastar: 2
Por minuto - límite: 120 por gastar: 119
Pet/seg: Max: 3 Pendientes: 2
Pet/min: Max: 120 Pendientes: 119
Las APIs de Netelip entregan en cada petición un par de valores en las cabeceras:
X-RateLimit-Limit-{interval}
X-RateLimit-Remaining-{interval}
Donde {interval} es el periodo de tiempo de los valores, si son seguidos por second será por segundo, por minute será por minuto, etc.
Los valores que empiezan con el prefijo X-RateLimit-Limit- son los valores máximos permitidos por intervalo.
Los valores que empiezan con el prefijo X-RateLimit-Remainig- son los valores de peticiones permitidas que quedan por ejecutar por intervalo.
Respuesta
Mensaje de respuesta cuando se excede uno de los límites:
HTTP/1.1 429 Too Many Requests
...
Connection: keep-alive
Content-Length: 37
X-RateLimit-Remaining-second: 0
X-RateLimit-Limit-second: 3
X-RateLimit-Remaining-minute: 114
X-RateLimit-Limit-minute: 120
...
Además de controlar el límite de peticiones en el tiempo las APIs de Netelip devuelven un código 429 de respuesta una vez excedido uno de los límites.