API-SMS WebService Interface

Ref. 17041804 - Push SMS, Balance, ACKs.

18 de abril de 2017 v1.12
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

Índice
Página

1 Introducción 3
1.1 Changelog 3

2 Enviar mensajes SMS (MT) 4

2.1 Información necesaria 4
2.2 Envío WebService 4
2.3 Formato XML 4

2.4 Ejemplos en formato XML 7

2.5 Autenticación 7
2.6 Mensajes de respuesta o error 8
2.7 Filtros y seguridad 9

2.8 Caracteres soportados 10

2.9 Cuenta para pruebas y solicitud de cuenta real 10
2.10 Ejemplos de código 10

3 Enviar mensajes concatenados (SMSLong) 11

4 Enviar mensajes UCS2 (SMSUnicode) 12
5 Enviar mensajes certificados (SMSCert) 13
6 Recepción de confirmaciones (ACKs) 14
7 Consulta de confirmaciones (ACKs) 15
8 Recepción de visitas (CLICKs) 16
9 Consulta de créditos 17
10 Consulta de precios 18
10.1 Ejemplos de resultado 18

11 Recomendaciones 19
12 Glosario de términos 21
13 Alfabeto GSM 3.38 7-bit 23

2 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

1 Introducción
Este documento sobre la API-SMS WebService Interface de LabsMobile. Está diseñado para
técnicos y clientes que quieran conectar sus aplicaciones a la plataforma de mensajería
SMS de LabsMobile. La finalidad de la integración es el envío de mensajes SMS (MT o Push
SMS) y las comunicaciones relacionadas (ACKs y consulta de crédito).

Este documento contiene una explicación detallada sobre el proceso de integración. Si tiene
alguna duda o necesita ejemplos de código contacte con su agente habitual LabsMobile o
en:

[email protected]

www.labsmobile.com

1.1 Changelog
v2.09 - 16/01/2016
- Consulta de precios

v2.10 - 16/03/2016
- Recepción de visitas (CLICKs)

v2.11 - 30/03/2016
- Nueva función de consulta de confirmaciones (ACK)
- Reintentos en recepción de confirmaciones (ACK)
- Creación de un subid siempre cuando se ha procesado una petición correctamente.

v2.12 - 18/04/2017
- Información de estado y errores en las confirmaciones ACK.

3 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

2 Enviar mensajes SMS

(MT)
2.1 Información necesaria
Para la integración con la API-SMS HTTP Interface son imprescindibles los siguientes datos
proporcionados por LabsMobile:
• Nombre de usuario y contraseña (figuran en el email de registro)
• URL específica: http://api.labsmobile.com/ws/services/LabsMobileWsdl.php

Opcionalmente puede comunicar a LabsMobile los siguientes parámetros:

• Dirección IP desde donde se enviarán los mensajes. Por razones de seguridad la
plataforma de mensajería sólo admitirá mensajes de esta/s IP/s. Esta funcionalidad en
opcional, por defecto no se activa esta opción y se aceptarán mensajes de cualquier IP.
• Remitente por defecto (default TPOA, por defecto es LABSMOBILE si no se indica lo
contrario).
• Límite de mensajes diario, por defecto a 50.000 sms/día.
• Límite de mensajes por batch, por defecto a 10.000 sms/envío.

IMPORTANTE: Todos estos parámetros se asignarán con los valores por defecto a todas la
cuentas.

2.2 Envío WebService

El envío de mensajes SMS a través de la API-SMS WebService Interface se realiza con
llamadas SOAP WDSL a:

http://api.labsmobile.com/ws/services/LabsMobileWsdl.php

A la función Send y con las variables:

username: xsd:string
password: xsd:string
xmldata: xsd:string

2.3 Formato XML

Los parámetros y contenido del envío se enviarán en una variable del WebService con
nombre ‘XmlData’ y en formato XML: xmldata = ‘<sms>...’

La variable ‘XmlData’ debe estar codificada en UTF-8. De igual forma todos las respuestas y
mensajes enviados desde la plataforma LabsMobile estarán codificados con el mismo juego
de caracteres (UTF-8). A continuación se presenta un ejemplo de formato XML para un envío
simple. También se presentan todos los TAGS y opciones disponibles.

<?xml version=”1.0” encoding=”UTF-8”?

><sms><recipient><msisdn>34609542312</msisdn></recipient>
<message>Test message number 1</message><tpoa>Sender name</tpoa></sms>

4 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

Nombre Descripción

sms Obligatorio. Delimita el inicio y final de un mensaje.

recipient Obligatorio. Delimita los destinatarios del mensaje.

msisdn Obligatorio. Tag que incluye un número móvil destinatario. El número

debe contener el código de país sin ‘+’ ó ‘00’.

Por ejemplo: 34609033162.

Cada cuenta cliente tiene un máximo de msisdn por envío. Consulte

las condiciones de su cuenta para saber este límite.

message Obligatorio. Mensaje a enviar. La longitud máxima es de 160

caracteres. Sólo son válidos los caracteres del alfabeto GSM 3.38 7bit
que se encuentra al final de este documento.

tpoa Opcional. Remitente del envío. Puede tener un valor numérico (longitud
máxima 14 dígitos) o alfanumérica (capacidad máxima 11 caracteres).
La plataforma de envío asigna un remitente por defecto si no se incluye
este tag en el formato xml.

Al incluir un número móvil como remitente, el receptor del mensaje

podrá responder desde su móvil fácilmente con “Reply”.

El remitente sólo se puede definir en algunos países debido a las

restricciones de los operadores. En caso contrario el remitente será un
valor numérico aleatorio.

subid Opcional. Identificador del mensaje que se incluye en los ACKs

(confirmaciones de entrega). Es un identificador único del envío por
parte del cliente API. Tiene una longitud máxima de 20 caracteres.

label Opcional. Identifica el mensaje para fines estadísticos. WebSMS y

otras aplicaciones utilizan este campo para agrupar y contabilizar el
mensaje. Capacidad máxima de 255 caracteres.

Información típica de este campo: usuario que ha realizado el envío,

aplicación o módulo, etc…

test Opcional. Si su valor es 1 el envío se considera de prueba. No se

enviará a la red GSM y por tanto no se recibirá en los dispositivos
móviles. No obstante, estos mensajes se pueden consultar en las
herramientas on-line de consulta. La finalidad de este tag es la de
realizar pruebas de integración sin un coste asociado. Las
confirmaciones operator y handset no se recibirán.

Ejemplo: <test>1</test>

5 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

Nombre Descripción

ackurl Opcional. URL a la que se enviarán las notificaciones de confirmación

de entrega de mensajes SMS. En la sección preferencias de la
aplicación WebSMS se puede configurar el valor de ackurl por defecto
para todos los casos sin tener que informar este tag en cada envío.

Ejemplo: <ackurl>http://clientserver.com/
receive_ack.php</ackurl>

shortlink Opcional. Si su valor es 1 se remplazará la primera URL del mensaje

con un link corto de LabsMobile (formato: http://lm0.es/XXXXX). Las
estadísticas de visitas al link (clicks) se podrán ver en la aplicación
WebSMS o se pueden recibir con el tag clickurl.

Ejemplo: <shortlink>1</shortlink>

clickurl Opcional. URL a la que se enviarán las notificaciones de eventos click

en los links que se marquen para su seguimiento con el tag shortlink.
En la sección preferencias de la aplicación WebSMS se puede
configurar el valor de clickurl por defecto para todos los casos sin
tener que informar este tag en cada envío.

Ejemplo: <clickurl>http://clientserver.com/
receive_click.php</clickurl>

scheduled Opcional. El mensaje se enviará en la fecha y hora indicada por este

campo. Si no se especifica este campo se enviará el mensaje de forma
inmediata. Formato: YYYY-MM-DD HH:MM:SS.

Ej. <scheduled>2012-11-07 17:34:00</scheduled>

IMPORTANTE: el valor de este campo se debe expresar en el uso

horario GMT.

long Opcional. Si este campo esta presente en el envío y tiene valor 1, el

campo message puede contener hasta 459 caracteres. Cada 153
caracteres se considerará un mensajes (a cobrar) y el destinatario
recibirá un único mensaje concatenado. Ej. <long>1</long>

IMPORTANTE: esta opción sólo está disponible en algunos países

debido a las restricciones de los operadores.

crt Opcional. Si este campo esta presente en el envío se considerará el

mensaje como mensaje SMS certificado. Se enviará a la dirección que
contenga este tag un e-mail con el documento de certificación del
envío adjunto. Ejempo: <crt>[email protected]</crt>

IMPORTANTE: esta opción sólo está implementada en algunos países.

ucs2 Opcional. Si este campo esta presente en el envío y tiene valor 1, el

mensaje puede contener cualquier carácter del alfabeto UCS-2. En
este caso la capacidad del mensaje es de 70 caracteres y se pueden
enviar concatenados hasta una capacidad máxima de 500 caracteres.
Ej. <ucs2>1</ucs2>

6 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

Nombre Descripción

nofilter Opcional. Si este campo tiene valor 1, la plataforma no aplicará los

filtros de mensajes duplicados.

IMPORTANTE: Los tags sms, recipient, msisdn y message son obligatorios. Envíos que no
contengan alguno de estos campos generarán el error correspondiente. De igual forma
generarán error los campos msisdn y message vacíos.

2.4 Ejemplos en formato XML

Envío de mensaje con confirmación de entrega handset:

<?xml version=”1.0” encoding=”UTF-8”?>

<sms>
<recipient>
<msisdn>34609542312</msisdn>
</recipient>
<message>Test message number 1</message>
<acklevel>handset</acklevel>
<ackurl>http://clientserver.com/receive_ack.php</ackurl>
</sms>

Envío de mensaje múltiple de prueba con identificación subid y label:

<?xml version=”1.0” encoding=”UTF-8”?>

<sms>
<recipient>
<msisdn>34609542312</msisdn>
<msisdn>34609542313</msisdn>
<msisdn>34609542315</msisdn>
</recipient>
<test>1</test>
<message>Test message number 1</message>
<subid>L-203</subid>
<label>[from]=websms;[user]=admin
[campaign]=salesJanuary
</label>
</sms>

2.5 Autenticación
La autenticación de la cuenta se realiza con las variables username y password de la
llamada al WebService. Esta es la descripción de cada uno de estas variables:

Nombre Descripción

username Obligatorio. Identifica a la cuenta que realiza el envío. Tiene

formato de cuenta de e-mail y corresponde con el nombre de
usuario (login) para acceder a la aplicación WebSMS.

7 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

Nombre Descripción

password Obligatorio. Contraseña asignada a la cuenta. Al crear la cuenta

se envía esta contraseña a la dirección de e-mail que corresponde
al username.

2.6 Mensajes de respuesta o error

Toda petición o llamada HTTP será verificada por la plataforma de mensajería. Tanto si la
petición es correcta como si se encuentra un error se devolverá un mensaje XML con el
código correspondiente al resultado de la verificación. La única excepción es si se produce
un fallo de autenticación (HTTP 401 Unauthorized) o si se realiza la petición desde una IP no
válida (HTTP 403 Forbidden).

Este es el formato del mensaje XML de respuesta a una petición:

<?xml version=”1.0” encoding=”UTF-8”?>

<response>
<code>[Numeric code]</code>
<message>[Description]</message>
</response>

Si la petición se realiza de forma correcta la respuesta siempre contendrá un campo subid

que identificará al envío. Ejemplo:

<?xml version=”1.0” encoding=”UTF-8”?>

<response>
<code>0</code>
<message>Message has been successfully sent</message>
<subid>56fb9baa6bc22</subid>
</response>

Esta es la lista completa de códigos de respuesta:

Código Descripción

0 Message has been successfully sent

10 Missing XML data in request

11 Badly formed XML in request

20 The message element must be present in the XML

21 The message element cannot be empty

22 Message too long. There is a limit of 160 7-bit characters

23 There are no recipients

24 Too many recipients

25 TPOA is exceeding max length

26 TPOA change is not allowed for this account

8 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

Código Descripción

27 This message contained one or more invalid character(s)

28 Subid is exceeding maximum length

30 There was an error while sending the message

31 AckLevel has been given but missing AckUrl

32 AckUrl has been given but missing AckLevel

33 An unknown value for AckLevel has been given. Allowed values

are gateway, operator or handset.

34 Label field too long

35 The account has no enough credit for this sending

36 Msisdn format [number] is not allowed

37 The account has reach the maximum messages per day

38 There was an error while sending the message to this MSISDNs

39 The value of the Scheduled field is not a valid datetime format

40 The username cannot send scheduled messages

41 Scheduled messages cannot be send in test mode

2.7 Filtros y seguridad

Como se puede ver en los códigos de error y en la sección de Autenticación, existen
diversas medidas de seguridad en el envío para prevenir usos indebidos:
• Autenticación de usuario y contraseña
• Lista de IPs de origen aceptadas
• Posibilidad de encriptación de los datos enviados/recibidos (HTTPS)
• Máximo de número por batch o envío.
• Máximo número de mensajes enviados por día.
• Filtro de mensajes duplicados.
• Crédito de la cuenta en caso de ser una cuenta prepago.

Todos estos parámetros varían en función de la cuenta. Consulte el apartado

PREFERENCIAS de su cuenta WebSMS para saber los valores de estos filtros o póngase en
contacto con su agente LabsMobile.

IMPORTANTE: El filtro de mensajes duplicados bloqueará (no enviará) mensajes con el mismo
texto y remitente enviados al mismo número dentro de una misma hora. Por tanto, sólo se enviará el
primer mensaje y los duplicados (mismo texto) quedarán marcados como duplicados y no se
enviarán. Los mensajes duplicados son visibles en el BUSCADOR de la aplicación WebSMS.

9 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

2.8 Caracteres soportados

La plataforma de mensajería LabsMobile soporta el alfabeto estándar GSM (GSM 3.38 7-bit).
Por tanto, los campos mensaje (<message>) y remitente (<tpoa>) deben contener sólo
caracteres de este alfabeto. El último capítulo de este documento contiene una lista
completa del alfabeto GSM.

Los mensajes enviados con caracteres no soportados serán devueltos con el

correspondiente mensaje de error. Desde LabsMobile aconsejamos sustituir algunos de
estos caracteres por otros sí permitidos manteniendo el significado del mensaje. A
continuación se presenta un ejemplo:
$message = ‘Subs chars áíóúçÑ’;
$ko = array(‘á’,’í’,’ó’,’ú’,’ç’,’Ñ’);
$ok = array(‘a’,’i’,’o’,’u’,’Ç’,’ñ’);
$message = str_replace($ko, $ok, $message);
echo $message;
// output: ‘Subs chars aiouÇñ’

2.9 Cuenta para pruebas y solicitud de cuenta

Puede solicitar una cuenta propia siguiendo los pasos para crear una cuenta en
www.labsmobile.com. Seguidamente recibirá un e-mail con los detalles de la cuenta
(usuario/contraseña). Esta cuenta se podrá utilizar a través de la aplicación on-line (WebSMS
– http://websms.labsmobile.com) o en cualquiera de las interfaces de SMSAPI (POST, GET,
Mail y WebService).

Durante el proceso de integración dispone del tag test para envíos de prueba. Serán envíos
simulados que NO se enviarán al móvil indicado y que son útiles para realizar las primeras
pruebas sin ningún coste. Los envíos de prueba no devolverán acuses de recibo (ACK) y se
podrán consultar en la aplicación WebSMS en el módulo BUSCADOR.

2.10 Ejemplos de código

En el siguiente enlace: http://www.labsmobile.com/es/api/code encontrarás los ejemplos de
código en diferentes lenguajes y tecnologías.

También puedes ponerte en contacto con nosotros si tienes cualquier duda o pregunta:
[email protected] ó +34 93 100 35 65.

10 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

3 Enviar mensajes concatenados

(SMSLong)
Los mensajes SMSLong son mensajes SMS con un tamaño superior a 160 caracteres. Estos
mensajes se facturarán como varios mensajes (cada 153 caracteres) pero el destinatario
recibirá el mensajes como un único mensaje. Consulte la web de LabsMobile para saber
más acerca de este tipo de mensajes.

IMPORTANTE: Los mensajes concatenados tienen una capacidad máxima de hasta 459
caracteres. SMSLong sólo está disponible en algunos países debido a las restricciones de los
operadores.

El proceso de envío es el mismo pero se debe añadir el tag long al formato XML. Todos los
envíos con este tag serán tratados como mensajes SMSLong. Los demás tags son válidos y
tienen las mismas características. Un ejemplo de formato XML para un envío SMSLong sería:

<?xml version=”1.0” encoding=”UTF-8”?>

<sms>
<recipient>
<msisdn>34609542312</msisdn>
</recipient>
<message>Test message SMSLong. This is a very long
message that could reach 459 chars. The output message will be a
unique message and the final user will read this text as one
single message.</message>
<long>1</long>
<tpoa>SenderName</tpoa>
</sms>

11 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

4 Enviar mensajes UCS2

(SMSUnicode)
Los mensajes SMSUnicode son mensajes SMS con caracteres que no están reconocidos por
el alfabeto estándar GSM. Estos mensajes se facturarán como mensajes normales (cada 70
caracteres) pero el destinatario recibirá el mensajes como un único mensaje. Consulte la
web de LabsMobile para saber más acerca de este tipo de mensajes.

IMPORTANTE: Los mensajes UCS2 tienen una capacidad máxima de hasta 500 caracteres.
SMSUnicode sólo está disponible en algunos países debido a las restricciones de los operadores.

El proceso de envío es el mismo pero se debe añadir la variable ucs2 y long si el mensaje
contiene más de 70 caracteres. Todos los envíos con la variable ucs2 serán tratados como
mensajes SMSUnicode. Las demás variables son válidas y tienen las mismas características.
Un ejemplo de llamada para un envío SMSUnicode sería:

<?xml version=”1.0” encoding=”UTF-8”?>

<sms>
<recipient>
<msisdn>34609542312</msisdn>
</recipient>
<message>Аликанте приглашает</message>
<ucs2>1</ucs2>
<tpoa>SenderName</tpoa>
</sms>

12 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

5 Enviar mensajes certificados

(SMSCert)
Los mensajes SMSCert son mensajes SMS con una certificación de envío y recepción. Estos
mensajes tienen la particularidad que generan un documento PDF que verifica el envío y la
recepción del mensaje. Consulte la web de LabsMobile para saber más acerca de este tipo
de mensajes.

IMPORTANTE: Los mensajes concatenados tienen una capacidad técnica de hasta 750 caracteres.
SMSCert sólo está implementada en algunos países.

El proceso de envío es el mismo pero se debe añadir el tag crt al formato XML. Todos los
envíos con este tag serán tratados como mensajes SMSCert. Los demás tags son válidos y
tienen las mismas características. Un ejemplo de formato XML para un envío SMSCert sería:

<?xml version=”1.0” encoding=”UTF-8”?>

<sms>
<recipient>
<msisdn>34609542312</msisdn>
</recipient>
<message>Test message SMSCert</message>
<crt>[email protected]</crt>
<tpoa>SenderName</tpoa>
</sms>

13 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

6 Recepción de confirmaciones
(ACKs)
Un cliente de la API-SMS HTTP Interface de LabsMobile puede solicitar la recepción de
confirmaciones de entrega en su sistema de forma asíncrona. Mediante los tags subid y
ackurl del formato XML se pueden recibir notificaciones HTTP/GET para cada número móvil
incluido en el envío. Existen los siguientes niveles:
• gateway: cuando el mensaje se envía a la red GSM.
• operator: cuando el operador final se responsabiliza de la entrega.
• handset: cuando el móvil recibe el mensaje.
• error: se ha producido un error en la entrega del mensaje. El campo status=ko y el
campo desc especifica el tipo de error.

IMPORTANTE: es posible que algunos operadores o rutas no tengan disponible alguno de los
niveles de confirmación de entrega.

La confirmación handset no se recibirá si existe alguna incidencia temporal con el móvil

como falta de cobertura/batería o buzón de entrada.

Las confirmaciones de entrega se recibirán en la URL indicada en el tag ackurl y tendrá el

siguiente formato:

?acklevel=[gateway|operator|handset|error]&msisdn=…&status=[ok|
error]&desc=…&subid=…&timestamp=YYYY-MM-DD%20HH:MM:SS

Variable Valores

acklevel gateway, operator, handset, error

status ok, ko

desc REJECTD, EXPIRED, DUPLICATED, UNDELIV, UNKNOWN

IMPORTANTE: la variable timestamp contiene horas en GMT ó UTC, y por tanto se debe modificar
para adaptarlas a la zona horaria u hora local de cada cliente.

IMPORTANTE: Si la llamada HTTP/GET genera error (estados HTTP 4xx o 5xx) se reintentará 5
veces la entrega de la confirmación ACK en los siguientes intervalos: 30s, 5m, 30m, 6h, 1d.

14 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

7 Consulta de confirmaciones
(ACKs)
La consulta de estado a través de la API-SMS WebService Interface se realiza con llamadas
SOAP WDSL a:

http://api.labsmobile.com/ws/services/LabsMobileWsdl.php

A la función GetAck con las variables:

username: xsd:string
password: xsd:string
subid: xsd:string
msisdn: xsd:string

El resultado tendrá el siguiente formato:

<?xml version="1.0" encoding="UTF-8"?>

<response>
<subid>X</subid>
<msisdn>X</msisdn>
<status>X</status>
<credits>X</credits>
<desc>X</desc>
<timestamp>X</timestamp>
</response>

Los posibles estados son:

Estado Descripción

processed Mensaje procesado.

test Mensaje enviado en modo simulado con la variable

test activada.

error Error en la entrega del mensaje. El campo desc

especifica el tipo de error: REJECTD, EXPIRED,
DUPLICATED, UNDELIV, UNKNOWN.

gateway Mensaje entregado a la red GSM.

operator Mensaje recibido por el operador local al destintario.

handset Mensaje entregado al dispositivo.

IMPORTANTE: la variable timestamp contiene horas en GMT ó UTC y por tanto se debe modificar
para adaptarlas a la zona horaria u hora local de cada cliente.

15 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
18/04/2017 - v1.12 [email protected]

8 Recepción de visitas
(CLICKs)
Un cliente de la API-SMS HTTP Interface de LabsMobile puede solicitar la recepción de
forma asíncrona de visitas a la url que se marque como shortlink en un mensaje. Mediante
los tags subid, shortlink y clickurl del formato XML se pueden recibir notificaciones HTTP/
POST JSON para cada visita.

Para recibir estas notificaciones de visitas es necesario que el mensaje contenga el tag
shortlink y que su valor sea 1. Cuando se produzca una visita o click en el shortlink que
remplazará a la url original se notificará via llamada HTTP/POST JSON con los datos de la
visita.

La url de destino de la notificación se puede especificar en cada envío con el tag clickurl o
se puede establecer una url por defecto para todos los envíos en las Preferencias de
WebSMS.

Este es el contenido de una notificación de visita:

Content-Type: application/json
Accept: application/json

{
"ip" : "XXX.XXX.XXX.XXX",
"useragent" : "…",
"subid" : "…",
"msisdn" : "…",
"timestamp" : "YYYY-MM-DD HH:mm:SS"
}

IMPORTANTE: la variable timestamp contiene horas en GMT ó UTC, y por tanto se debe modificar
para adaptarlas a la zona horaria u hora local de cada cliente.

16 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

9 Consulta de créditos
La consulta de créditos a través de la API-SMS WebService Interface se realiza con llamadas
SOAP WDSL a:

http://api.labsmobile.com/ws/services/LabsMobileWsdl.php

A la función GetCredit con las variables:

username: xsd:string
password: xsd:string

El resultado de esta consulta es un XML con este formato:

<?xml version="1.0" encoding=“UTF-8"?>

<response>
<messages>X</messages>
</response>

IMPORTANTE: La plataforma de envío monitoriza las llamadas a este servicio y no permite

(bloquea) accesos constantes. Recomendamos hacer una consulta de crédito sólo cuando es
necesario: antes y/o después de realizar un envío o al mostrar las propiedades de la cuenta
cliente.

17 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

10 Consulta de precios
La consulta de los créditos que consume cada envío simple según el país de destino se
realiza con llamadas SOAP WDSL a:

http://api.labsmobile.com/ws/services/LabsMobileWsdl.php

A la función GetPrices con las variables:

username: xsd:string
password: xsd:string
countries: xsd:string
format: xsd:string

La variable countries puede contener el valor ALL para obtener los datos de todos los
países o especificando los códigos ISO de los países en concreto.

El formato del resultado puede ser en CSV (por defecto), XML o JSON.

10.1 Ejemplos de resultado

CSV

FR,33,France,1.114
DE,49,Germany,1.8

XML

<?xml version="1.0" encoding="UTF-8"?>

<prices>
<country>
<isocode>FR</isocode>
<prefix>33</prefix>
<name>France</name>
<credits>1.114</credits>
</country>
<country>
<isocode>DE</isocode>
<prefix>49</prefix>
<name>Germany</name>
<credits>1.8</credits>
</country>
</prices>

JSON

{"FR":{"isocode":"FR","prefix":"33","name":"France","credits":1.114},"DE":
{"isocode":"DE","prefix":"49","name":"Germany","credits":1.8}}

18 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

11 Recomendaciones
En esta sección se presentan 10 puntos a comprobar en toda integración para asegurar que
todo envío a nuestra plataforma de envío SMS se realice sin problemas. En los manuales de
integración se explican en detalle todas las posibilidades y errores posibles. No obstante,
estas son las 10 causas más comunes de error y recomendamos su verificación.

Campos obligatorios. Los campos mensaje, msisdn (teléfonos de destino) y los

correspondientes a la autenticación (usuario y contraseña) son obligatorios.

Longitud del mensaje. El contenido del mensaje de texto debe tener un valor no nulo y no
sobrepasar los 160 caracteres que es el límite máximo de un SMS estándar (459 para
SMSLong).

Teléfonos válidos. Los teléfonos deben tener un formato numérico y precedidos con el
código de país. Para el envío a móviles españoles los móviles siempre empezarán por 346 o
347 y ocho dígitos más.

Capacidad del remitente. El campo remitente (TPOA) tiene una capacidad máxima de 16
dígitos o de 11 caracteres alfanuméricos. Los caracteres permitidos con letras y números
([A-Z|a-z|0-9]).

Caracteres no válidos en mensaje. El campo mensaje debe contener sólo caracteres del
alfabeto GSM 3.38 7-bit que se encuentra en todos los manuales. Recomendamos realizar la
conversión de algunos caracteres no soportados y la no posibilidad de otros caracteres no
soportados o reemplazables.

"á" => "a"

"í" => "i"
"ó" => "o"
"ç" => "Ç"
"¡" => "!"
"`" => "'"

Versión y codificación XML. Todas las tecnologías, excepto HTTP/GET, utilizan XML como
lenguaje de definición de los parámetros del SMS. Se debe especificar la versión y el
alfabeto de codificación en la primera línea. Además de comprobar que corresponda con la
codificación real de envío para evitar errores de caracteres no válidos y escapar los
caracteres reservados:
< => &lt;
> => &gt;
& => &amp;
" => &quot;
' => &apos;

Filtro de mensajes duplicados. Nuestra plataforma filtra los mensajes duplicados:

mensajes SMS con el mismo contenido enviados al mismo número dentro de la misma hora.
La plataforma de LabsMobile no cobrará ni enviará los mensajes duplicados. Estos
mensajes se podrán ver en la aplicación WebSMS etiquetados como duplicados.

19 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

Pruebas. Durante el periodo de integración es posible realizar envíos con el parámetro test
activado. De esta forma se pueden realizar todo tipo de pruebas sin coste y verificar el
resultado en la aplicación WebSMS.

Límites de tráfico. Las cuentas LabsMobile tienen un límite por batch (mensajes en un
mismo envío, 10.000 por defecto) y un límite de SMS por día (50.000 por defecto). Si deseas
modificar estos límites ponte en contacto con nosotros.

Seguridad. Una vez completada la integración básica recomendamos aplicar medidas de

seguridad adicionales como el filtro por IP o la encriptación HTTPS.

20 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

12 Glosario de términos
XML

Son las siglas de eXtensible Markup Language. Es un metalenguaje extensible de etiquetas

desarrollado por W3C. Es una manera de definir lenguajes para una necesidad en concreto.
La SMSAPI de LabsMobile utiliza XML para definir el formato de un mensaje SMS en las
tecnologías http/POST, SMTP (e-mail) y WebService.

MSISDN

Significa Mobile Station Integrated Services Digital Network e identifica a una suscripción en
la red GSM o UMTS. Es decir, identifica la suscripción y corresponde con el número de
teléfono de la tarjeta SIM. Tiene una longitud máxima de 15 dígitos y se compone por el
código de país y el número del abonado (en España 34 y 9 dígitos más).

ACK

Las notificaciones ACK son las confirmaciones de entrega o acuse de recibo de los
mensajes enviados por la plataforma de mensajería LabsMobile. Se notifica el momento
exacto en el mensaje SMS cambia de estado.

Existen tres tipos de notificaciones ACK:

• gateway: momento en el que el mensaje ha sido validado y enviado a la red GSM.
• operator: momento en el que el operador local acepta el mensaje y se responsabiliza de
su entrega.
• handset: momento en el que el mensaje llega al dispositivo móvil. Esta notificación ACK
no se producirá si el móvil: es un móvil válido, esta apagado o fuera de cobertura, tiene
el buzón de mensajes lleno o si se encuentra en periodo de portabilidad.

MT

Los mensajes SMS-MT (Short message Mobile Terminated) son los que tienen como destino
un dispositivo móvil. En esta documentación todos los mensajes enviados desde la
plataforma LabsMobile se consideran SMS-MT.

MO

Los mensajes SMS-MO (Short message Mobile Originated) son los enviados desde un
dispositivo móvil.

El destino puede ser por ejemplo un número asociado con la plataforma de mensajería
LabsMobile y que ésta pueda redirigir el mensaje (vía WebSMS, SMS, e-mail, http/GET, http/
POST, WebService, etc.).

UTF-8

Es un juego de caracteres que puede representar cualquier carácter Unicode. Incluye todos
los símbolos utilizados en los lenguajes latinos y anglosajones.

21 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

Este juego de caracteres (charset) es el que utiliza la plataforma LabsMobile y el que se

debe utilizar en las comunicaciones con la SMSAPI.

GSM

Es el sistema global para las comunicaciones móviles (GSM, proviene del francés Groupe
Spécial Mobile). Sobre esta tecnología de alcance internacional se envían todos los
mensajes SMS a los dispositivos móviles.

TPOA

Corresponde con el origen del mensaje o remitente. El TPOA (Transmission Path Originating
Address) en un mensaje entre dos móviles siempre contiene el número móvil del emisor pero
con la plataforma de mensajería de LabsMobile puede tener cualquier valor respetando los
máximos de tamaño (16 dígitos si es numérico o 11 caracteres si es alfanumérico).

Normalmente contiene el nombre de la empresa que envía el mensaje o el número que

quiera recibir la respuesta (InCode, SMSPremium o MSISN).

SSL

El protocolo criptográfico SSL (Secure Sockets Layer) asegura una comunicación segura a
través de Internet. En todas las comunicaciones con la SMSAPI y la aplicación WebSMS se
puede utilizar este protocolo para asegurar la privacidad y no vulnerabilidad de la
autenticación de cuenta.

API

Significa Application Programming Interface y establece las reglas y especificaciones para

comunicar con la plataforma de mensajería de LabsMobile desde cualquier aplicación. Se
han desarrollado funciones desde varias tecnologías estándar (http/POST, http/GET,
WebService, e-Mail) para facilitar la integración con cualquier Web, portal, CRM, aplicación
Desktop, etc.

http/GET

HTTP es el protocolo de comunicación entre páginas web. La plataforma de mensajería de

LabsMobile acepta llamadas http/GET para enviar mensajes. Este tipo de invocación GET
envía los parámetros en la misma URL.

http/POST

HTTP es el protocolo de comunicación entre páginas web. La plataforma de mensajería de

LabsMobile acepta llamadas http/POST para enviar mensajes. Este tipo de invocación POST
envía los parámetros de la invocación en el cuerpo de la petición y no en la URL.

WebService

Un servicio web o WebService es un conjunto de protocolos y estándares para el

intercambio de datos entre aplicaciones. La plataforma de mensajería de LabsMobile ha
publicado WebService para el envío de mensajes con todas las opciones disponibles.

22 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

13 Alfabeto GSM 3.38 7-bit

A continuación se presenta una lista de los caracteres incluidos en el alfabeto estándar GSM
03.38 7-bit soportado por la plataforma LabsMobile en los campos mensaje y remitente para
mensajes SMS.

Hex Descripción Caracter ISO-8859-1

0x00 COMMERCIAL AT @ 64

0x01 POUND SIGN £ 163

0x02 DOLLAR SIGN $ 36

0x03 YEN SIGN ¥ 165

0x04 LATIN SMALL LETTER E WITH GRAVE è 232

0x05 LATIN SMALL LETTER E WITH ACUTE é 233

0x06 LATIN SMALL LETTER U WITH GRAVE ù 249

0x07 LATIN SMALL LETTER I WITH GRAVE ì 236

0x08 LATIN SMALL LETTER O WITH GRAVE ò 242

0x09 LATIN CAPITAL LETTER C WITH CEDILLA Ç 199

0x0A LINE FEED 10

0x0B LATIN CAPITAL LETTER O WITH STROKE Ø 216

0x0C LATIN SMALL LETTER O WITH STROKE ø 248

0x0D CARRIAGE RETURN 13

0x0E LATIN CAPITAL LETTER A WITH RING ABOVE Å 197

0x0F LATIN SMALL LETTER A WITH RING ABOVE å 229

0x10 GREEK CAPITAL LETTER DELTA Δ

0x11 LOW LINE _ 95

0x12 GREEK CAPITAL LETTER PHI Φ

0x13 GREEK CAPITAL LETTER GAMMA Γ

0x14 GREEK CAPITAL LETTER LAMBDA Λ

0x15 GREEK CAPITAL LETTER OMEGA Ω

0x16 GREEK CAPITAL LETTER PI Π

0x17 GREEK CAPITAL LETTER PSI Ψ

23 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

Hex Descripción Caracter ISO-8859-1

0x18 GREEK CAPITAL LETTER SIGMA Σ

0x19 GREEK CAPITAL LETTER THETA Θ

0x1A GREEK CAPITAL LETTER XI Ξ

0x1B ESCAPE TO EXTENSION TABLE

0x1B0A FORM FEED* 12

0x1B14 CIRCUMFLEX ACCENT* ^ 94

0x1B28 LEFT CURLY BRACKET* { 123

0x1B29 RIGHT CURLY BRACKET* } 125

0x1B2F REVERSE SOLIDUS (BACKSLASH) * \ 92

0x1B3C LEFT SQUARE BRACKET* [ 91

0x1B3D TILDE* ~ 126

0x1B3E RIGHT SQUARE BRACKET* ] 93

0x1B40 VERTICAL BAR* | 124

164
0x1B65 EURO SIGN* €
(ISO-8859-15)
0x1C LATIN CAPITAL LETTER AE Æ 198

0x1D LATIN SMALL LETTER AE æ 230

0x1E LATIN SMALL LETTER SHARP S (German) ß 223

0x1F LATIN CAPITAL LETTER E WITH ACUTE É 201

0x20 SPACE 32

0x21 EXCLAMATION MARK ! 33

0x22 QUOTATION MARK " 34

0x23 NUMBER SIGN # 35

0x25 PERCENT SIGN % 37

0x26 AMPERSAND & 38

0x27 APOSTROPHE 39

0x28 LEFT PARENTHESIS ( 40

0x29 RIGHT PARENTHESIS ) 41

24 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

Hex Descripción Caracter ISO-8859-1

0x2A ASTERISK * 42

0x2B PLUS SIGN + 43

0x2C COMMA , 44

0x2D HYPHEN-MINUS - 45

0x2E FULL STOP . 46

0x2F SOLIDUS (SLASH) / 47

0x30 DIGIT ZERO 0 48

0x31 DIGIT ONE 1 49

0x32 DIGIT TWO 2 50

0x33 DIGIT THREE 3 51

0x34 DIGIT FOUR 4 52

0x35 DIGIT FIVE 5 53

0x36 DIGIT SIX 6 54

0x37 DIGIT SEVEN 7 55

0x38 DIGIT EIGHT 8 56

0x39 DIGIT NINE 9 57

0x3A COLON : 58

0x3B SEMICOLON ; 59

0x3C LESS-THAN SIGN < 60

0x3D EQUALS SIGN = 61

0x3E GREATER-THAN SIGN > 62

0x3F QUESTION MARK ? 63

0x40 INVERTED EXCLAMATION MARK ¡ 161

0x41 LATIN CAPITAL LETTER A A 65

0x42 LATIN CAPITAL LETTER B B 66

0x43 LATIN CAPITAL LETTER C C 67

0x44 LATIN CAPITAL LETTER D D 68

25 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

Hex Descripción Caracter ISO-8859-1

0x45 LATIN CAPITAL LETTER E E 69

0x46 LATIN CAPITAL LETTER F F 70

0x47 LATIN CAPITAL LETTER G G 71

0x48 LATIN CAPITAL LETTER H H 72

0x49 LATIN CAPITAL LETTER I I 73

0x4A LATIN CAPITAL LETTER J J 74

0x4B LATIN CAPITAL LETTER K K 75

0x4C LATIN CAPITAL LETTER L L 76

0x4D LATIN CAPITAL LETTER M M 77

0x4E LATIN CAPITAL LETTER N N 78

0x4F LATIN CAPITAL LETTER O O 79

0x50 LATIN CAPITAL LETTER P P 80

0x51 LATIN CAPITAL LETTER Q Q 81

0x52 LATIN CAPITAL LETTER R R 82

0x53 LATIN CAPITAL LETTER S S 83

0x54 LATIN CAPITAL LETTER T T 84

0x55 LATIN CAPITAL LETTER U U 85

0x56 LATIN CAPITAL LETTER V V 86

0x57 LATIN CAPITAL LETTER W W 87

0x58 LATIN CAPITAL LETTER X X 88

0x59 LATIN CAPITAL LETTER Y Y 89

0x5A LATIN CAPITAL LETTER Z Z 90

0x5B LATIN CAPITAL LETTER A WITH DIAERESIS Ä 196

0x5C LATIN CAPITAL LETTER O WITH DIAERESIS Ö 214

0x5D LATIN CAPITAL LETTER N WITH TILDE Ñ 209

0x5E LATIN CAPITAL LETTER U WITH DIAERESIS Ü 220

0x5F SECTION SIGN § 167

26 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

Hex Descripción Caracter ISO-8859-1

0x60 INVERTED QUESTION MARK ¿ 191

0x61 LATIN SMALL LETTER A a 97

0x62 LATIN SMALL LETTER B b 98

0x63 LATIN SMALL LETTER C c 99

0x64 LATIN SMALL LETTER D d 100

0x65 LATIN SMALL LETTER E e 101

0x66 LATIN SMALL LETTER F f 102

0x67 LATIN SMALL LETTER G g 103

0x68 LATIN SMALL LETTER H h 104

0x69 LATIN SMALL LETTER I i 105

0x6A LATIN SMALL LETTER J j 106

0x6B LATIN SMALL LETTER K k 107

0x6C LATIN SMALL LETTER L l 108

0x6D LATIN SMALL LETTER M m 109

0x6E LATIN SMALL LETTER N n 110

0x6F LATIN SMALL LETTER O o 111

0x70 LATIN SMALL LETTER P p 112

0x71 LATIN SMALL LETTER Q q 113

0x72 LATIN SMALL LETTER R r 114

0x73 LATIN SMALL LETTER S s 115

0x74 LATIN SMALL LETTER T t 116

0x75 LATIN SMALL LETTER U u 117

0x76 LATIN SMALL LETTER V v 118

0x77 LATIN SMALL LETTER W w 119

0x78 LATIN SMALL LETTER X x 120

0x79 LATIN SMALL LETTER Y y 121

0x7A LATIN SMALL LETTER Z z 122

27 / 28
 API-SMS WebService Interface T. 34 93 100 35 65
30/03/2016 - v1.11 [email protected]

Hex Descripción Caracter ISO-8859-1

0x7B LATIN SMALL LETTER A WITH DIAERESIS ä 228

0x7C LATIN SMALL LETTER O WITH DIAERESIS ö 246

0x7D LATIN SMALL LETTER N WITH TILDE ñ 241

0x7E LATIN SMALL LETTER U WITH DIAERESIS ü 252

0x7F LATIN SMALL LETTER A WITH GRAVE à 224

* Caracteres que se codifican con dos bytes y que ocupan dos espacios dentro de un SMS.

28 / 28