Especificacion SMS Push TELKIA v2.8

TELKIA
Especificacin, SMSBROKER
HTTP Protocol
TELKIA
Versin: 2.8
Fecha: 02-11-2016

Page 1

Registro de Cambios
Este documento es revisado peridicamente para mantener consistencia con las
actualizaciones del softw are.

Revisin Cambios respecto a versiones
anteriores
1.6 Se aade la funcionalidad de envo push al cliente
de las notificaciones de entrega
2.0 Nueva versin del API. Se incluyen parmetros
nuevos:
- Etiqueta tag definida por el cliente
- Fecha programada de envo
- Periodo de Validez del mensaje
- Modo de Pruebas
2.7 Se aade el parmetro bkid (bulk id) para
identificar a un grupo de SMS
2.8 Se aclara la lista de caracteres alfanumricos
permitidos en el remitente
Proprietary Notice
This document is the property of TELKI A SLU. All information herein is confidential to TELKI A and
must not be copied or disclosed to any third party w ithout the prior w ritten consent of TELKI A.

Page 2

Copyright TELKI A 2009 2016

Page 3

ndice
1 Introduccin ........................................................................................................... 5
1.1 Alcance del Documento ................................................................................................................................ 5
1.1.1 Introduccin a SMSBROKER .................................................................................................................... 5
1.1.2 Requisitos ......................................................................................................................................................... 5
2 Descripcin Tcnica ................................................................................................ 5
2.1 Funcionalidad ................................................................................................................................................... 5
2.2 Parmetros ......................................................................................................................................................... 5
2.2.1 Remitente Alfanumrico (parmetro snr) ........................................................................................ 7
2.2.2 Envo de mensajes programado (parmetro st) ........................................................................... 8
2.2.3 Manejo de mensajes largos (parmetro split) ............................................................................... 8
2.3 Respuesta a la peticin HTTP .................................................................................................................... 8
2.4 Envo de un SMS a mltiples destinatarios .......................................................................................... 9
2.5 Envo de mltiples SMS por POST ......................................................................................................... 10
2.5 Notificacin de Entrega ............................................................................................................................. 11
2.6 Comprobacin de saldo ............................................................................................................................. 12
2.7 Cancelacin de un mensaje programado ........................................................................................... 13
2.8 Cancelacin masiva de mensajes programados .............................................................................. 13
APNDICE ................................................................................................................ 15
Cdigo de ejemplo en PHP ............................................................................................................................... 15
1) Envo de SMS ..................................................................................................................................................... 15
2) Recepcin de Notificaciones de Entrega ............................................................................................... 15
Cdigo de ejemplo en Python ......................................................................................................................... 16
1) Envo de SMS ..................................................................................................................................................... 16

Page 4

1 Introduccin
1.1 Alcance del Documento
1.1.1 Introduccin a SMSBROKER
La plataforma SMSBROKER de TELKIA permite el envo de mensajes SMS a travs del
protocolo HTTP.
Este documento va dirigido a los diseadores de software y programadores que quieran

integrar la capacidad de envio de SMS a su aplicacin.
1.1.2 Requisitos
Para poder enviar SMS es necesario:
Tener una cuenta abierta en TELKIA
Tener crditos suficientes en la cuenta de usuario
El acceso al servicio SMSBROKER est sujeto a la aceptacin de los trminos y condiciones

generales del servicio de TELKIA.
2 Descripcin Tcnica
2.1 Funcionalidad
El envo de datos se realiza a travs del comando GET o POST de HTTP (para el envo de
mensajes binarios solo se permite a travs de un POST). El sistema acepta peticiones en la
siguiente URL:
http://sms.smsbroker.net:11000/api/sendSMS.php
2.2 Parmetros

Se permiten los siguientes parmetros, en cualquier orden:
Parmetros Obligatorios
Nombre del Valor / Formato Ejemplo Descripcin

parmetro
user A lfanumrico Cliente1 I dentificador de la
cuenta de cliente
pw A lfanumrico a7372fe contrasea
dnr [P refijo 34600123456 N umero mvil

I nternacional][0-9] destinatario
snr A lfanumrico M iEmpresa N umero del

Remitente o Texto
A lfanumrico
(OADC). M nimo 4
caracteres. M ximo
11 caracteres

msg Texto UTF-8 Esto es una prueba Contenido del
(max. 160 mensaje
caracteres) (si se

Page 5

activa el parmetro
extended se
permiten hasta 380
caracteres, enviados
como mensajes
concatenados)
Parmetros Opcionales

parmetro
dlr 0 o 1 1 (0 por defecto) Bandera que indica
si se quiere solicitar
una N otificacin de
Entrega (Delivery
Receipt).
0 = N o (por defecto)
1 = S

tag A lfanumrico M i_Referencia Etiqueta con una
(mximo 32 referencia nica
caracteres) generada por el
cliente para
facilitarle el
seguimiento de las
N otificaciones de
Entrega
campaign A lfanumrico Oferta3x2 Etiqueta con una
(mnimo 8 referencia a un
caracteres, identificador de
mximo 64 campaa del cliente.
caracteres) P ermite agrupar
multiples envios
SM S a una campaa.
Si posteriormente
queremos cancelar
todos los SM S
programados de una
campaa, bastar
una nica
instruccin (mdoto
cancelCampaign)
para hacerlo.
st A A A A -M M -DD 2009-11-25 15:20:00 Hora P rogramada de

hh:mm:ss Envio, en el caso de
que no se quiera un
envo inmediato

vp numrico 60 P eriodo de Validez
(Fecha de
expiracin)
expresado en
minutos. Si el SM S
no puede entregarse
antes de la fecha de
expiracin, se
cancelar el envo.
N ota: no todos los
operadores
soportan esta
funcionalidad
dc 1 , 2 o 3 1 Datacoding. I ndica
el tipo de

Page 6

codificacin del
mensaje
1 = normal(por
defecto)
2 = binario
3 = Unicode (admite
acentos y caracteres
especiales, pero
cada carcter ocupa
2 bytes. 1 SM S = 70
caracteres Unicode)
split 1,2 o 3 1 N mero mximo de
SM S en los que se
dividir el mensaje,
en el caso de que su
tamao exceda de
los 160 caracteres
(140 octetos)
Esta opcin permite
el envo de
mensajes largos
como 2 o 3 SM S
concatenados
json 0 o 1 1 (0 por defecto) Bandera que indica
si se desea que la
respuesta del A P I
sea un J SON en
lugar de un XM L
(por defecto)
test 0 o 1 1 (0 por defecto) Bandera que indica
si se esta haciendo
un test de
comunicacin con el
A P I y no se desea
que el SM S se envie
al destinatario.
0 = N o (por defecto)
1 = S
Ejemplo de una peticin http vlida:
http://sms.smsbroker.net:11000/api/sendSMS.php?user=cliente1&pw=555555&d
nr=34123456789&msg=esto+es+una+prueba&snr=miempresa
2.2.1 Remitente Alfanumrico (parmetro snr)

El remitente del SMS puede ser o un numero de telfono o una cadena alfanumrica de un
mximo de 11 caracteres.
Tenga en cuenta que no todos los terminales mviles son capaces de mostrar un remitente
alfanumrico.
La lista de caracteres permitido para el remitente son los siguientes:
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
El uso de cualquier otro carcter no incluido en la lista anterior puede afectar incluso a la
entrega del SMS, o bien el remitente es alterado o incluso la entrega del mensaje puede
fallar.

Page 7

2.2.2 Envo de mensajes programado (parmetro st)

Recomendamos que para el envo de mensajes programados el cliente almacene los
mensajes hasta la fecha y hora programada y los envie a SMSBROKER en ese momento. No
obstante, para aquellos clientes que por su estructura tecnolgica tengan limitaciones
temporales para el acceso a internet pueden utilizar la plataforma SMSBROKER para
almacenar los mensajes hasta la fecha de envo programada.
El formato de la fecha programada es : AAAA-MM-DD hh:mm:ss (CET)
Ejemplo:
st=2011-12-25 19:00:00
2.2.3 Manejo de mensajes largos (parmetro split)

Por defecto los mensajes enviados a travs de Telkia sern truncados a un mximo de 160
caracteres en alfabeto de 7-bit (140 octetos).
Los clientes que deseen enviar mensajes ms largos deben indicar de forma explicita el
numero mximo de SMS en los que se puede dividir un mensaje con el parmetro split. La
longitud mxima de un mensaje es de 459 caracteres, enviando 3 SMS. Telkia aplicar el
coste dependiendo del numero de SMS generados por cada mensaje:
De 0 a 160 caracteres = 1 mensaje

De 161 a 306 caracteres = 2 mensajes
De 307 a 459 caracteres = 3 mensajes
2.3 Respuesta a la peticin HTTP

La llamada HTTP devuelve un fichero XML cuyo formato es como sigue:
Si la peticin ha sido correcta y aceptada por la plataforma SMSBROKER, el

XML ser as:

<?xml version="1.0" encoding="iso-8859-1" ?>
<smsbroker>
<message>
<msgid>2f02b6919a9be9fb680fa57dac14c8ab</msgid>
<dnr>34600123456</dnr>
<status>OK</status >
</message >
</smsbroker>

Donde el tag status puede tener uno de estos valores
- OK: mensaje procesado correctamente

- Error: el mensaje no pudo ser procesado
y "msgid" es un identificador nico de la transaccin
En el caso de un mensaje concatenado y procesado correctamente el

formato sera:

Page 8

<smsbroker>
<message>
<dnr>34600123456</dnr>
</message >
<message>
<msgid>2f02b6919a9be9afe80fa57dac14c8a9</msgid>
<dnr >34600123456</dnr >
<status >OK</status >
</message >
</smsbroker>
En el caso de que la peticin tenga algn error y no pueda ser procesada el

XM L tendra el formato:

<smsbroker>
< message >
<status>Error</ status >
<error>descripcin del error</error>
<errorCode>cdigo de error</ errorCode >
</ message >
</smsbroker>

Donde el tag error contiene una explicacin sobre el motivo por el que no se ha podido
procesar el mensaje.
El tag errorCode puede tener cualquiera de los siguientes valores numricos:
errorCode Descripcin

0 Correcto
-1 N umero de Destino no vlido
-2 Remitente no vlido
-3 Contenido del mensaje no vlido
-10 Sin Saldo. Falta de crdito
-14 Usuario no vlido
-15 Clave incorrecta
-99 Error del sistema
2.4 Envo de un SMS a mltiples destinatarios

Se puede enviar un SMS a mltiples destinatarios en una nica peticin GET, utilizando el
separador , dentro del campo dnr.
Ejemplo de peticin de envo de un SMS a 3 destinatarios:
Ejemplo de una peticin http vlida:

Page 9

http://sms.smsbroker.net:11000/api/sendSMS.php?user=cliente1&pw=555555&d
nr=34610200901, 34610200902, 34610200903&msg=esto+es+una+prueba&snr=
miempresa
Ejemplo de respuesta enviando 3 SM S, con saldo de 2 crditos antes de realizar la

peticin:

<smsbroker>
<message>
<dnr>34600123456</dnr>
</message >
<message>
<dnr >34600123456</dnr >
<status > OK </status >
</message >
<message>
<msgid>-1</msgid>
<dnr >34600123456</dnr >
<status >Error</status >
<error > Low Balance. Please Top Up your Account </error >
<errorCode >-10</ errorCode >
</message >
</smsbroker>
2.5 Envo de mltiples SMS por POST

Se puede enviar un SMS diferentes en una nica peticin POST.
POST http://sms.smsbroker.net:11000/api/sendSMSpost.php HTTP/1.1

<smsbroker>
<user> cliente1</user>
<pw> 555555</pw>
<send>
<dnr>34600000001, 34600000002, 34600000003</dnr>
<snr>MIEMPRESA1</snr >
<msg>Esto es un mensaje de prueba</msg >
</send >
<send>
<dnr>34600000004</dnr>
<msg>Esto es otro mensaje de prueba, programado a las 21h</msg >
<st>2015-12-31 21:00:00</st >
</send >
<send>
<dnr>34600000005,34600000006</dnr>
<msg>y este tambin es un mensaje de prueba</msg >
</send >
</smsbroker>

Page 10

Respuesta obtenida:

<smsbroker>
<message>
<dnr>34600000001</dnr>
</message >
<message>
<dnr >34600000002</dnr >
</message >
<message>
<msgid>2f00f271d856c370280905a616</msgid>
<dnr >34600000003</dnr >
</message >
<message>
<dnr >34600000004</dnr >
</message >
<message>
<dnr >34600000005</dnr >
</message >
<message>
<msgid>-1</msgid>
<dnr >34600000006</dnr >
<status >Error</status >
<error > Low Balance. Please Top Up your Account </error >
<errorCode >-10</ errorCode >
</message >
</smsbroker>
2.5 Notificacin de Entrega

Las notificaciones de entrega se pueden recibir por parte del cliente a travs de una URL de
callback (push).
Cuando el cliente facilita una URL a este efecto, SMSBROKER enva automticamente las
notificaciones de entrega segn se van recibiendo del operador.
El envo de las notificaciones se realizar a una URL del tipo:
http:/ / yourcompany.com/ pushdlr.php
SMSBROKER enviar un fichero XML con el formato descrito a continuacin.

Page 11

Es necesario que la aplicacin del cliente responda a esta peticin http con el cdigo 200 y
adems con el texto OK. En caso contrario , o si la URL no est accesible en ese momento,
se realizarn varios reintentos hasta un mximo de 24 horas.
Su script debe ser capaz de recibir y procesar un fichero XML con esta estructura:

<smsbroker>
<dlr>
<id>2f02b69</id>
<tag>my_ref_1</tag>
<sentdate>2010-12-01 10:00:35</sentdate>
<donedate>2010-12-01 10:00:38</donedate>
<status> REJECTD </status>
</ dlr >
</smsbroker>

Los cdigos de estado de las notificaciones de entrega pueden tener los siguientes valores:
status Descripcin

ACCEPTD El mensaje ha sido aceptado por el
operador. A la espera de posibles
notificaciones de entrega
DELIVRD El mensaje ha sido entregado al terminal
FAILED Ha fallado el intento de entrega
EXPIRED El mensaje ha caducado antes de poder
entregarlo
REJECTED M ensaje rechazado por el SM S-C del
operador
UNDELIV Ha sido imposible entregar el mensaje
DELETED El mensaje ha sido borrado por el SM S-C
UNKNOWN Estado desconocido, normalmente si no se
ha recibido notificacin del SM S-C
transcurridas 24 horas

Las horas indicadas en las notificaciones de entrega estn en referidas a UTC.

2.6 Comprobacin de saldo

Se puede consultar el saldo disponible en las cuentas prepago a travs de la siguiente URL:

http://sms.smsbroker.net:11000/api/balance.php

con los parmetros:

parmetro
cuenta de cliente

Page 12


<smsbroker>
<account>
<balance>2105</balance>
<currency>credits</currency>
</ account >
</smsbroker>

2.7 Cancelacin de un mensaje programado

Se puede cancelar el envio de un mensaje programado antes de su envo, haciendo una
llamada a la siguiente URL:

http://sms.smsbroker.net:11000/api/cancelSMS.php

con los parmetros:

parmetro
cuenta de cliente
msgid A lfanumrico 2f01f24ca546179g577 I dentificador del

mensaje a cancelar
dnr [P refijo 34600123456 N umero mvil

I nternacional][0-9] destinatario del
mensaje a cancelar


<smsbroker>
<message>
<msgid>2f01f24ca546179g577</ msgid >
<dnr>34600123456</dnr>
<status>DELETED</status>
</ message >
</smsbroker>

2.8 Cancelacin masiva de mensajes programados

Se puede cancelar un envio masivo mensajes programados antes de su envo, si a la hora de
hacer la programacin utilizamos el parmetro campaign.

Page 13

Para cancelar todos los SMS programados de una campaa bastar hacer una llamada a la
siguiente URL:
http://sms.smsbroker.net:11000/api/cancelCampaign.php

con los parmetros:

parmetro
cuenta de cliente
campaign A lfanumrico Campaign321 I dentificador del

mensaje a cancelar


<smsbroker>
<message>
< campaign >Campaign321</ campaign >
<count>1322</ count >
<status>DELETED</status>
</ message >
</smsbroker>

Page 14

APNDICE
Cdigo de ejemplo en PHP
1) Envo de SMS
<?
$url =
"http://sms.smsbroker.net:11000/api/sendSMS.php?user=xxxx&pw=xxxxxxxxx&dnr=3460000000&ms
g=mensaje+de+prueba&snr=TELKIA";
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url); // URL to post
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 ); // return into a variable
$xml_string = curl_exec( $ch ); // runs the post
if (curl_errno($ch)) $ok = false;

else {
$ok = true;
curl_close($ch);
}
if($ok) {
$xml = new SimpleXMLElement($xml_string);
if ($xml->xpath('/smsbroker/message')) {
foreach($xml->xpath('/smsbroker/message') as $sms) {
echo "id : " . $sms->msgid ."\n";
echo "dnr : " . $sms->dnr ."\n";
echo "status: " . $sms->status ."\n";
}
} else {
foreach($xml->xpath('/smsbroker') as $resultado) {
$status = $resultado->status;
$error = $resultado->error;
$errorCode = $resultado->errorCode;
echo "Resultado del envio: status: '$status' error: '$error'
errorCode: '$errorCode' \n";
}
}
} else echo "Error ".curl_error($ch)." when posting to url: ".$url;

>
2) Recepcin de Notificaciones de Entrega
<?
// read raw POST data

postData = file_get_contents("php://input");
$ack = "KO";
$xml = simplexml_load_string($postData);
foreach ($xml->dlr as $dr){

$id = $dr->id ;
$sentdate = $dr->sentdate;
$donedate = $dr->donedate;
$status = $dr->status;
$ack = "OK";
}
header('Content-Type: text/plain');
echo $ack;
?>

Page 15

Cdigo de ejemplo en Python

Recomendamos el uso de la librera Requests: HTTP for Humans http://docs.python-
requests.org/en/latest/index.html
1) Envo de SMS

import requests
import json
r = requests.post("http://sms.smsbroker.net:11000/api/sendSMS.php", data={'user':
'USERNAME', 'pw': 'PASSWORD', 'dnr': '3460000000' ,'snr': 'TELKIA','msg': 'Hola, esto es
un SMS de prueba'})
r.raise_for_status()
data=r.json()
#PRINT RESPONSE
print(r.text) #TEXT/HTML
print(r.status_code, r.reason)
count = data['message-count']
print "message count is ",count
if (count > 0):

for message in data['messages']:
print "msg id", message['msgid'], " => status ", message['status']

Page 16

Especificacion SMS Push TELKIA v2.8

Diunggah oleh

Informasi Dokumen

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Especificacion SMS Push TELKIA v2.8

Diunggah oleh

Hak Cipta:

Format Tersedia

TELKIA

Este documento va dirigido a los diseadores de software y programadores que quieran

El acceso al servicio SMSBROKER est sujeto a la aceptacin de los trminos y condiciones

Nombre del Valor / Formato Ejemplo Descripcin

dnr [P refijo 34600123456 N umero mvil

snr A lfanumrico M iEmpresa N umero del

Nombre del Valor / Formato Ejemplo Descripcin

st A A A A -M M -DD 2009-11-25 15:20:00 Hora P rogramada de

Ejemplo de una peticin http vlida:

2.2.1 Remitente Alfanumrico (parmetro snr)

La lista de caracteres permitido para el remitente son los siguientes:

2.2.2 Envo de mensajes programado (parmetro st)

2.2.3 Manejo de mensajes largos (parmetro split)

De 0 a 160 caracteres = 1 mensaje

2.3 Respuesta a la peticin HTTP

Si la peticin ha sido correcta y aceptada por la plataforma SMSBROKER, el

- OK: mensaje procesado correctamente

y "msgid" es un identificador nico de la transaccin

En el caso de un mensaje concatenado y procesado correctamente el

En el caso de que la peticin tenga algn error y no pueda ser procesada el

El tag errorCode puede tener cualquiera de los siguientes valores numricos:

2.4 Envo de un SMS a mltiples destinatarios

Ejemplo de peticin de envo de un SMS a 3 destinatarios:

Ejemplo de una peticin http vlida:

Ejemplo de respuesta enviando 3 SM S, con saldo de 2 crditos antes de realizar la

<?xml version="1.0" encoding="iso-8859-1" ?>

2.5 Envo de mltiples SMS por POST

POST http://sms.smsbroker.net:11000/api/sendSMSpost.php HTTP/1.1

<?xml version="1.0" encoding="iso-8859-1" ?>

<?xml version="1.0" encoding="iso-8859-1" ?>

2.5 Notificacin de Entrega

El envo de las notificaciones se realizar a una URL del tipo:

http:/ / yourcompany.com/ pushdlr.php

SMSBROKER enviar un fichero XML con el formato descrito a continuacin.

<?xml version="1.0" encoding="iso-8859-1" ?>

2.6 Comprobacin de saldo

2.7 Cancelacin de un mensaje programado

msgid A lfanumrico 2f01f24ca546179g577 I dentificador del

dnr [P refijo 34600123456 N umero mvil

2.8 Cancelacin masiva de mensajes programados

campaign A lfanumrico Campaign321 I dentificador del

$xml_string = curl_exec( $ch ); // runs the post

if (curl_errno($ch)) $ok = false;

2) Recepcin de Notificaciones de Entrega

// read raw POST data

foreach ($xml->dlr as $dr){

Cdigo de ejemplo en Python

if (count > 0):

Anda mungkin juga menyukai