SMS API
HTTP GATEWAY
Versión 1.6
Esta API permite el acceso a todas las características de 360nrs usando Json.
[Link] 1
ÚLTIMOS CAMBIOS
Versión 1.2 18/09/2017 Añadidas las funcionalidades para listar, actualizar y eliminar
envíos programados. Corrección de errores
Versión 1.3 07/11/2017 Añadidos parámetros campaignName y tags
Versión 1.4 16/04/2018 Añadidos ejemplos Python, Java y C#
Versión 1.5 19/09/2018 Añadida variable certified para poder enviar SMS como
certificado. Añadida funcionalidad de descarga de certificado.
Versión 1.6 04/10/2018 Añadido parámetro para especificar variables de sustitución.
[Link] 2
ÍNDICE
INTRODUCCIÓN Pág. 4
PLATAFORMA TÉCNICA Pág. 4
Petición de envío de SMS Pág. 5
Parámetros Pág. 5
Ejemplo de petición básica Pág. 7
Ejemplo de petición CURL Pág. 7
Ejemplo de petición PHP Pág. 7
Ejemplo de petición Python Pág. 7
Ejemplo de petición JAVA Pág. 8
Ejemplo de petición C# Pág. 9
Ejemplos de respuesta Pág. 11
Gestión de mensajes programados Pág. 11
Listado Pág. 11
Parámetros Pág. 11
Ejemplos de petición Pág. 11
Ejemplos de respuesta Pág. 11
Actualización Pág. 12
Parámetros Pág. 12
Ejemplos de petición Pág. 12
Ejemplos de respuesta Pág. 12
Borrado Pág. 13
Parámetros Pág. 13
Ejemplos de petición Pág. 13
Ejemplos de respuesta Pág. 13
Gestión de SMS certificados Pág. 14
Descarga certificado PDF Pág. 14
Parámetros Pág. 14
Ejemplos de petición Pág. 14
Ejemplos de respuesta Pág. 14
Ejemplos de respuesta (errores) Pág. 15
Anexo A – Acuse de recibo Pág. 16
Anexo B – Conjunto de caracteres Pág. 17
[Link] 3
INTRODUCCIÓN
La plataforma http server permite al usuario enviar mensajes a través de esta plataforma.
Para poder acceder a sus estadísticas y datos de facturación puede acceder a la web
[Link] con sus datos de usuario.
La comunicación entre el cliente no se realizará a través de ningún API proporcionado por
la Empresa, sino que simplemente se realizará una comunicación HTTP, con algunos
parámetros a la URL indicada.
Este proceso se detalla a continuación.
PLATAFORMA TÉCNICA
Cada petición que se realice tendrá que incluir en la cabecera de la petición http la
autenticación del cliente. Para ello se utiliza la autenticación de acceso básica de HTTP.
La cabecera de autorización se construye combinando la cadena “usuario: contraseña” y
codificándola en base64. A esta cadena se antepone la cadena “Authorization: Basic”
Por ejemplo, para el usuario “miuser” y el password “mipass” la cabecera resultante sería:
Authorization: Basic bWl1c2VyOm1pcGFzcw==
A continuación se detallará las opciones de envío disponibles, la URL a la que se debe
llamar, y los parámetros que admite.
[Link] 4
PETICIÓN ENVÍO DE SMS
URL: [Link]
MÉTODO: POST
PARÁMETROS
Parámetro Tipo Obligatorio Descripción
message string Sí Texto del mensaje. Como
máximo puede tener 160
caracteres si no se especifica
que el mensaje sea multiparte
(ver parámetro 'parts'). El texto
tiene que estar codificado en
UTF-8
to array Sí Número de teléfono móvil
destinatario del mensaje. Debe
incluir el prefijo (Ej: En España
34666666666). Este campo
permite indicar multiples
destinatarios.
from string Sí Texto del Remitente, esta
etiqueta se compondrá de 15
números o 11 caracteres
alfanuméricos.
encoding string No Los posibles valores son "gsm",
"gsm-pt" y "utf-16". El valor "gsm"
para envíos normales con
codificación GSM7 y 160
caracteres por mensaje y el valor
"utf-16 para codificación UCS2
(UTF16) y 70 caracteres por
mensaje. En caso de no
especificarse, el valor por defecto
es "gsm".
scheduleDate string No Fecha de envió del mensaje en
formato UTC. Si se necesita
enviar mensajes programados se
puede especificar la fecha de
envío indicando la fecha en
formato YYYYmmddHHiiss (Ej:
20130215142000 sería el 15 de
febrero de 2013 a las 14:20:00).
En caso de envío inmediato no
se tiene que especificar este
parámetro.
[Link] 5
parts integer No Indica el número máximo de
partes en que se dividirá el
mensaje para su envío. Esta
variable tiene valor 1 por defecto,
por lo que si no se especifica y
se envía un mensaje de mas de
160 caracteres para codificación
gsm, el mensaje fallará. Hay que
tener en cuenta que los
mensajes concatenados solo
pueden tener 153 caracteres por
parte en gsm y 67 caracteres por
parte en utf-16 y que cada parte
se tarifica como un envío. El
servidor solo utilizará el mínimo
de partes necesaria para realizar
el envío del texto aunque el
número de partes especificado
sea superior al necesario. En
caso de que el número de partes
sea inferior al necesario para el
envío del texto, el envío fallará
con el error 105. El número
máximo de partes permitido es
de 8.
notificationUrl string No URL en la que recibir las
notificaciones de entrega.
trans integer No Los valores posibles son 1 y 0.
Con el valor 0 el servidor no
modifica ningún carácter del
mensaje, este es el valor por
defecto. Con el valor 1 el servidor
se encarga de modificar los
caracteres comunes no validos
en GSM7 a caracteres validos
con la siguiente tabla de
traducción: 'á' => 'a', 'í'=>'i', 'ó'=>'o',
'ú'=>'u', 'ç'=>'Ç', 'Á'=>'A', 'Í'=>'I', 'Ó'=>'O',
'Ú'=>'U', 'À'=>'A', 'È'=>'E', 'Ì'=>'I', 'Ò'=>'O',
'Ù'=>'U', 'º' => '', 'ª' => '', 'Õ' => 'O', 'õ' =>
'o', 'â' => 'a', 'ê' => 'e', 'î'=>'i', 'ô'=>'o',
'û'=>'u', 'Â'=>'A', 'Ê'=>'E', 'Î'=>'I', 'Ô'=>'O',
'Û'=>'U', 'ã' => 'a', 'Ã' => 'A'
campaignName String No Nombre de campaña. Si se
especifica se creará una campaña
con el nombre indicado en el
dashboard que contendrá las
estadísticas del envío. Si una
campaña con este nombre ya existe,
las estadísticas de envío se añadirán
a la campaña existente.
[Link] 6
tags array No campaignName es requerido si se
especifica este parámetro. Listado de
tags a añadir a la campaña. Los tags
pueden ser utilizados para filtrar las
estadísticas en el dashboard.
certified boolean No Si se especifica como true el
mensaje se enviará como certificado.
NOTA: Los mensajes certificados
tienen coste adicional.
sub array No array con variables de sustitución
que se aplicarán al mensaje.
EJEMPLO DE PETICIÓN BÁSICA
{"to":["34666555444"],"message":"mensaje de texto","from":"msg"}
Nota: Para generar una URL de baja hay que añadir: {UNSUB_URL} dentro del parámetro
“message”.
VARIABLES DE SUSTITUCIÓN
Es posible indicar variables personalizadas en el cuerpo del mensaje que serán
sustituidas por las variables personalizadas del contacto o por las variables indicadas
en el parámetro “sub”.
Al utilizar el parámetro sub, el array ha de contener tantos elementos como
destinatarios del envío, utilizando el siguiente formato:
{
"from": "TEST",
"to": ["34666555444", "34666555333"],
"message": "Hello {name}",
"sub" : [
{"name": "first contact name"},// variables primer destinatario
{"name": "second contact name"}//variables segundo destinatario
]
}
EJEMPLO DE PETICIÓN CURL
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic
bWl1c2VyOm1pcGFzcw==" -d "{\"to\":[\"34666555444\"],\"message\":\"mensaje de
texto\",\"from\":\"msg\"}" h
ttps://[Link]/api/rest/sms
EJEMPLO DE PETICIÓN PHP
<?php
[Link] 7
$post["to"] = array("34666555444");
$post["message"] = "mensaje de texto";
$post["from"] = "msg";
$post["campaignName"] = "Nombre Campaña";
$user = "miuser";
$password = "mipass";
try {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"[Link]
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post));
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Accept: application/json",
"Authorization: Basic " . base64_encode($user . ":" . $password)));
$result = curl_exec($ch);
var_dump($result);
} catch (Exception $exc) {
echo $exc->getTraceAsString();
}
EJEMPLO DE PETICIÓN PYTHON
import pycurl
import base64
import json
if __name__ == "__main__":
#url API
url ="[Link]
usrPass = "miuser:mipass"
data = [Link]({
"to":["34666555444"],
"from":"msg",
"message":"Mensaje de texto",
"campaignName":"Nombre Campaña"
})
b64Val = base64.b64encode(usrPass)
headers=["Accept:Application/json","Authorization:Basic %s"%b64Val]
c = [Link]()
[Link]([Link], url)
[Link]([Link],headers)
[Link]([Link], 1)
[Link]([Link], data)
[Link] 8
[Link](pycurl.SSL_VERIFYHOST, 0)
[Link](pycurl.SSL_VERIFYPEER, 0)
[Link]()
http_code = [Link](pycurl.HTTP_CODE)
print(http_code)
EJEMPLO DE PETICIÓN JAVA
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
public class ApiSms {
public static void main(String args[]) throws IOException {
String url = "[Link]
URL obj = new URL(url);
HttpsURLConnection con = (HttpsURLConnection) [Link]();
[Link]("POST");
String userpass = "miuser" + ":" + "mipass";
String basicAuth = "Basic " +
[Link].printBase64Binary([Link]("UTF-8"));
[Link]("Authorization", basicAuth);
[Link]("Accept", "application/json");
JSONObject data = new JSONObject();
JSONArray to = new JSONArray();
[Link]("34666555444");
[Link]("to", to);
[Link]("from", "msg");
[Link]("message", "Mensaje de texto");
[Link]("campaignName", "Nombre Campaña");
String jsonText = [Link]();
[Link](true);
try (DataOutputStream wr = new DataOutputStream([Link]())) {
[Link](jsonText);
[Link]();
[Link]();
[Link] 9
BufferedReader in = new BufferedReader(
new InputStreamReader([Link]()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = [Link]()) != null) {
[Link](inputLine);
}
[Link]();
[Link]([Link]());
}
}
EJEMPLO DE PETICIÓN C#
using [Link];
using System;
using [Link];
using [Link];
namespace nrs_api
{
class Program
{
static void Main(string[] args)
{
var httpWebRequest =
(HttpWebRequest)[Link]("[Link]
[Link] = "POST";
[Link] = "application/json";
String username = "miuser";
String password = "mipass";
String encoded =
[Link].ToBase64String([Link]("ISO-8859-1").GetBy
tes(username + ":" + password));
[Link]("Authorization", "Basic " + encoded);
using (var streamWriter = new
StreamWriter([Link]()))
{
string[] to = new string[1];
to[0] = "34666555444";
var from = "msg";
var message = "Mensaje de texto";
var campaignName = "Nombre Campaña";
var data = new
{
[Link] 10
to = to,
from = from,
message = message,
campaignName = campaignName,
};
string json = [Link](data);
[Link](json);
[Link]();
[Link]();
}
var httpResponse = (HttpWebResponse)[Link]();
using
(var streamReader = new StreamReader([Link]()))
{
var result = [Link]();
[Link](result);
[Link]();
}
}
}
}
La clave de acceso (password) y el código del cliente (username) serán proporcionados
por la empresa. Hay que comentar que con objeto de aumentar la seguridad del sistema,
el cliente deberá indicar la IP desde donde se va a conectar, solo se permitirán envíos de
la IP indicada por el cliente.
EJEMPLOS DE RESPUESTA
CÓDIGO ESTADO 202 (ACCEPTED):
[{"accepted":true,"to":"34666555444","id":"102648819"}]
CÓDIGO ESTADO 207 (MULTI-STATUS):
[{"accepted":true,"to":"34626690739","id":"102648820"},{"accepted":false,
"to":"34","error":{"code":102,"description":"No valid recipients"}}]
GESTIÓN DE MENSAJES PROGRAMADOS
LISTADO
Lista todos los envíos programados. Puede filtrarse por tipo (SMS o MAILING) y puede
especificarse un GUID, varios GUID o ningún GUID (para listar todos).
[Link] 11
El contenido del mensaje no se muestra en la lista, a no ser que se especifique un único
GUID.
URL: [Link]
MÉTODO: GET
PARÁMETROS
Parámetro Tipo Obligatorio Descripción
guid integer, array No Identificador del mensaje o
mensajes.
Se le puede pasar un
identificador, un array de
identificadores o ninguno para
mostrarlos todos.
type string No SMS o MAILING
EJEMPLOS DE PETICIÓN
[Link]
[Link]
[Link]
[Link]
[Link]
EJEMPLOS DE RESPUESTA
Con varios GUID o sin GUID:
{"result":[
{"guid":"100","type":"SMS","created_at":"2017-09-18 10:49:12","updated_at":"2017-09-18 10:49:12","scheduled_at":"2017-11-11
10:10:10"},
{"guid":"101","type":"SMS","created_at":"2017-09-18 10:49:12","updated_at":"2017-09-18 10:49:12","scheduled_at":"2017-11-11
10:10:10"},
{"guid":"102","type":"SMS","created_at":"2017-09-18 10:49:12","updated_at":"2017-09-18 10:49:12","scheduled_at":"2017-11-11
10:10:10"}
],"total":3}
Especificando un único GUID:
{"result":{"guid":"100","type":"SMS","content":"Contenido del SMS","created_at":"2017-09-18
10:49:12","updated_at":"2017-09-18 10:49:12","scheduled_at":"2017-11-11 10:10:10"},"total":1}
ACTUALIZACIÓN
Actualiza la fecha de programación un envío, varios envíos o todos los envíos
programados.
Puede filtrarse por GUID y/o tipo.
[Link] 12
CUIDADO: Si no se especifica ningún GUID se actualizarán todos los mensajes
programados.
URL: [Link]
MÉTODO: PUT
PARÁMETROS
Parámetro Tipo Obligatorio Descripción
guid integer, array No Identificador del mensaje o
mensajes.
Se le puede pasar un
identificador, un array de
identificadores o ninguno para
mostrarlos todos.
type string No SMS o MAILING
scheduleDate string Sí Fecha de envío del mensaje en
formato UTC. Si se necesita
enviar mensajes programados se
puede especificar la fecha de
envío indicando la fecha en
formato YYYYmmddHHiiss (Ej:
20130215142000 sería el 15 de
febrero de 2013 a las 14:20:00).
En caso de envío inmediato no
se tiene que especificar este
parámetro.
EJEMPLOS DE PETICIÓN
{"guid": 100, "scheduleDate": "20171011093000"}
{"guid": [100,101], "scheduleDate": "20171011093000"}
{"type": "SMS", "scheduleDate": "20171011093000"}
{"scheduleDate": "20171011093000"}
EJEMPLOS DE RESPUESTA
{"result":true,"updated":1} {"result":true,"updated":2}
BORRADO
Elimina un envío, varios envíos o todos los envíos programados.
Puede filtrarse por GUID y/o tipo.
[Link] 13
CUIDADO: Si no se especifica ningún GUID se borrarán todos los mensajes
programados.
URL: [Link]
MÉTODO: DELETE
PARÁMETROS
Parámetro Tipo Obligatorio Descripción
guid integer, array No Identificador del mensaje o
mensajes.
Se le puede pasar un
identificador, un array de
identificadores o ninguno para
mostrarlos todos.
type string No SMS o MAILING
EJEMPLOS DE PETICIÓN
{"guid": 100} {"guid": [100,101]} {"type": "SMS"}
EJEMPLOS DE RESPUESTA
{"result":true,"deleted":1} {"result":true,"deleted":2}
GESTIÓN DE SMS CERTIFICADOS
DESCARGA CERTIFICADO PDF
URL: [Link]
MÉTODO: GET
PARÁMETROS
Parámetro Tipo Obligatorio Descripción
id string Sí Identificador del mensaje
devuelto en la respuesta a la
llamada a api/rest/sms en el
campo id.
EJEMPLOS DE PETICIÓN
[Link]
EJEMPLOS DE RESPUESTA
Certificado en formato PDF
[Link] 14
[Link] 15
EJEMPLOS DE RESPUESTA
CÓDIGO ESTADO 400 (BAD REQUEST):
{"error":{"code":102,"description":"No valid recipients"}}
{"error":{"code":104,"description":"Text message missing"}}
{"error":{"code":105,"description":"Text message too long"}}
{"error":{"code":106,"description":"Sender missing"}}
{"error":{"code":107,"description":"Sender too long"}}
{"error":{"code":108,"description":"No valid Datetime for send"}}
{"error":{"code":109,"description":"Notification URL incorrect"}}
{"error":{"code":110,"description":"Exceeded maximum parts allowed or incorrect number of parts"}}
{"error":{"code":113,"description":"Invalid coding"}}
{"error":{"code":120,"description":"Invalid GUID"}}
{"error":{"code":121,"description":"Invalid scheduled date"}}
CÓDIGO ESTADO 401 (UNAUTHORIZED):
{"error":{"code":103,"description":"Username or password unknown"}}
{"error":{"code":111,"description":"Not enough credits"}}
CÓDIGO ESTADO 402 (PAYMENT REQUIRED):
{"error":{"code":111,"description":"Not enough credits"}}
CÓDIGO ESTADO 500 (INTERNAL SERVER ERROR):
{"error":{"code":122,"description":"Update error"}}
{"error":{"code":123,"description":"Delete error"}}
[Link] 16
ANEXO A: ACUSES DE RECIBO
Si se desean recibir los acuses de recibo en tiempo real se deberá especificar la variable
“notificationUrl” con la URL del cliente donde quiere que se notifique es estado del envío.
El funcionamiento consiste en especificar en cada petición http la URL donde se desea
que realice una petición de nuestro servidor cuando se reciba una notificación por parte
de la operadora. Para ello el cliente debe disponer de un servidor http capaz de recibir
esas notificaciones.
Nuestro servidor enviará las variables por el método GET tal como el cliente quiera, para
ello en la URL que nos envía tiene que poner el nombre de la variable seguido de un
carácter de escape que contendrá el valor, los caracteres de escape tienen la forma del
carácter “%” seguido de una letra. Este seria un ejemplo de URL:
[Link]
Estos son los caracteres de escape definidos:
%i Identificador de NRS que se entregó cuando se hizo el envío
%d valor del acuse de recibo
%p el remitente del SMS
%P el número de teléfono del receptor del mensaje SMS
%t fecha del envío del mensaje con formato "YYYY-MM-DD HH:MM", e.j., "2015-09-21 14:18"
El valor %d es el que nos devolverá el estado final del envío, los valores posibles son:
1: El mensaje ha sido entregado al destinatario.
2: El mensaje no se ha podido entregar al destinatario.
4: El mensaje ha sido entregado al SMSC, es una notificación intermedia, no un resultado final
16: No se ha podido entregar a la operadora final
Para explicar mejor el proceso, a continuación se da un ejemplo de cómo seria el envío de
un sms y la recepción de su acuse de recibo.
En primer lugar enviamos el sms con la variable notificationUrl donde indicaremos la URL
donde queremos recibir la notificación de entrega, añadiremos a esta URL nuestro
identificador de envío para poder identificar inequívocamente cuando lo recibamos. La url
final para la notificación seria:
[Link]
Por tanto la llamada final que deberíamos hacer para enviar el SMS sería:
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic bWl1c2VyOm1pcGFzcw=="
-d "{\"to\":[\"34666555444\"],\"message\":\"mensaje de
texto\",\"from\":\"TEST\",\"notificationUrl\":\"http:\\/\\/[Link]\\/[Link]?idenvio=7584remitente=%p&tel=%P&estado=
%d\"}" h ttps://[Link]/api/rest/sms
Suponiendo que todos los mensajes puedan ser entregados, recibiremos al script
[Link] tres peticiones con el estado=1, remitente=TEST, idenvio=7584 y el número
de teléfono correspondiente.
[Link] 17
ANEXO B: CONJUNTO DE CARACTERES GSM7
CÓDIGO DE CARACTERES BÁSICO
0x00 0x10 0x20 0x30 0x40 0x50 0x60 0x70
0x00 @ Δ SP 0 ¡ P ¿ p
0x01 £ _ ! 1 A Q a q
0x02 $ Φ " 2 B R b r
0x03 ¥ Γ # 3 C S c s
0x04 è Λ ¤ 4 D T d t
0x05 é Ω % 5 E U e u
0x06 ù Π & 6 F V f v
0x07 ì Ψ ' 7 G W g w
0x08 ò Σ ( 8 H X h x
0x09 Ç Θ ) 9 I Y i y
0x0A LF Ξ * : J Z j z
0x0B Ø ESC + ; K Ä k ä
0x0C ø Æ , < L Ö l ö
0x0D CR æ - = M Ñ m ñ
0x0E Å ß . > N Ü n ü
0x0F å É / ? O § o à
[Link] 18
EXTENSIÓN DEL CONJUNTO DE CARACTERES BÁSICO
ESTOS CARACTERES OCUPAN DOS POSICIONES
0x00 0x10 0x20 0x30 0x40 0x50 0x60 0x70
0x00 |
0x01
0x02
0x03
0x04 ^
0x05 €
0x06
0x07
0x08 {
0x09 }
0x0A FF
0x0B SS2
0x0C [
0x0D CR2 ~
0x0E ]
0x0F \
[Link] 19