API de envío SMS WebService

La API SMS WebService está diseñada para técnicos y clientes que quieran conectar sus aplicaciones con la plataforma de mensajería SMS de LabsMobile.

Las funcionalidades de la API SMS WebService son:

El envío de mensajes SMS de forma individual o masivo en tiempo real
Envío programado de mensajes SMS
Envío de mensajes SMS Unicode, SMS Concatenados y SMS Certificados
Consulta de saldo de créditos de una cuenta

Esta documentación explica detalladamente el proceso de integración y automatización de estas funcionalidades.

Para iniciar una integración con la API WebService son imprescindibles los siguientes requisitos:

Una cuenta de LabsMobile asociada con un nombre de usuario (correo electrónico de registro). Crea una cuenta aquí.
Token API utilizado como contraseña y generado desde la sección Configuración API de tu cuenta.
URL del de la API SMS WebService y los valores de los parámetros para realizar la petición.

A tener en cuenta

RecomendaciónRecomendamos utilizar nuestra API SMS http/POST porque incluye más funcionalidades, mejora la seguridad y el rendimiento.

La API SMS WebService de LabsMobile es una API SOAP WDSL RPC/encoded con esta URL base: https://api.labsmobile.com/ws/services/LabsMobileWsdl.php

Autenticación

El método de autenticación utilizado en la API WebService se realiza a través de enviar las credenciales (username y tokenapi) en los parámetros de las funciones SOAP.

Configuración y filtros

A continuación se detallan variables de configuración y aspectos de seguridad importantes en una integración con la API de envío SMS WebService:

Dirección IP desde donde se enviarán los mensajes. Si se activa esta opción, sólo se admitirán peticiones de la lista de dirección IPs introducida. Esta funcionalidad es opcional, por defecto se aceptarán mensajes de cualquier IP.
Remitente por defecto (por defecto LABSMOBILE). Sólo algunos operadores permiten la asignación dinámica y con valor alfanumérico del campo remitente.
Límite de mensajes diario, por defecto 100.000 sms/día.
Límite de mensajes por batch, por defecto 10.000 sms/petición.
Filtro por países, para que sólo se procesen mensajes de una lista de países.
Filtro anti-duplicados, para evitar enviar mensajes iguales a un mismo destinatario.

Todos estos parámetros se pueden activar y modificar en la Configuración API y Preferencias de la cuenta.

Importante Se establece un máximo de 10 peticiones por segundo. Malos usos, abusos o un mayor volumen de peticiones provocarán un bloqueo temporal o permanente de la cuenta y/o dirección IP.

Recomendación Recomendamos activar las Recargas automáticas para que siempre existan créditos disponibles en la cuenta y no se interrumpa el servicio de envío SMS.

Envío de mensajes SMS

Petición para el envío de mensajes SMS de forma individual o masiva.

Con esta funcionalidad se pueden enviar mensajes en tiempo real o de forma programada para un día y hora específicos. Además, se pueden añadir otros parámetros como el remitente, etiqueta, identificador, modo simulado, etc.

ENDPOINT

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

PARÁMETROS
Los parámetros o datos se envían en variables de las funciones WebService. A continuación se describen los valores y funcionalidad de todos los parámetros:
client string obsoleto
Identificador de cliente. Parámetro obsoleto y que debe tener valor nulo.
username email obligatorio
Email de nombre de usuario que identifica la cuenta que realiza el envío.
Ejemplo: email@mydomain.com
password string obligatorio
Token API generado en la sección Configuración API de la cuenta.
Ejemplo: lUHia713N5aByua79fU5s1Nlb6ItZ9ioVu

xmldata xml obligatorio

Parámetros básicos y opciones del envío de mensajes SMS. Debe contener un string en formato XML con los elementos que se describen en Elementos XML.

<?xml version="1.0" encoding="utf-8"?>
<sms>
  <recipient>
    <msisdn>34609542312</msisdn>
  </recipient>
  <message>Test message number 1</message>
  <tpoa>Sender name</tpoa>
</sms>

Ampliar todo
ELEMENTOS XML
sms xml obligatorio
Elemento raíz que delimita el inicio y final del formato XML.
recipient xml obligatorio
Incluye los números de los destinatarios.
msisdn string obligatorio
Números de teléfono de los destinatarios a los que se envía el mensaje. Los números deben cumplir el formato internacional E.164 y separados por comas (",") si se incluyen más de un número de destino.
Ejemplo: <msisdn>34609542313</msisdn>
message string obligatorio
Texto del mensaje a enviar. Si se envían SMS estándar sólo son válidos los caracteres del alfabeto GSM 3.38 7bit . Se pueden enviar también SMS Concatenados, SMS Unicode y SMS Certificados con los correspondientes parámetros.
Ejemplo: <message>Hello world!</message>
scheduled YYYY-MM-DD HH:MM:SS
Programación del envío para el día y hora indicados. Si no se especifica este campo, se enviará el mensaje de forma inmediata. Formato: YYYY-MM-DD HH:MM:SS.
Importante: El valor de este campo se debe expresar en el uso horario GMT.
Ejemplo: <scheduled>2012-11-07 17:34:00</scheduled>
tpoa string
Campo remitente del mensaje SMS. Puede tener un valor numérico (longitud máxima 16 dígitos) o alfanumérico (capacidad máxima 11 caracteres).
La asignación y personalización del remitente sólo está disponible en algunos países y operadores. En caso contrario, el remitente será un valor numérico (shortcode o longcode) estático.
Ejemplo: <tpoa>MyBrand</tpoa>
subid string
Identificador de la petición. Longitud máxima de 20 caracteres.
Si no se incluye un valor en el parámetro subid, la plataforma asignará un identificador único de 13 caracteres que se mostrará en el resultado de la petición.
Ejemplo: <subid>5aa3ea8028ce5</subid>
label string
Campo de información libre para identificar y asignar atributos. Longitud máxima de 255 caracteres.
Posibles usos: usuario, aplicación, agrupación o campaña, etc.
Ejemplo: <label>A05-enero-2024</label>
test 0 | 1
Activación del modo simulado de envío para pruebas y monitorización.
Si se asigna un valor 1 a este parámetro, los mensajes no se enviarán a los destinatarios y no se descontará ningún crédito. Los mensajes enviados en modo simulado se podrán consultar en el Histórico y otras herramientas.
Ejemplo: <test>1</test>
ackurl url
Url a la que se enviarán las notificaciones de confirmación de entrega y error de los mensajes enviados.
Se puede establecer una URL por defecto en la Configuración API de la cuenta y en ese caso no es necesario incluir este parámetro.
Ejemplo: <ackurl>https://clientserver.com/receive_ack</ackurl>
clickurl url
Url a la que se enviarán las notificaciones de eventos de click en los enlaces de los mensajes enviados.
Se puede establecer una URL por defecto en la Configuración API de la cuenta y en ese caso no es necesario incluir este parámetro.
Ejemplo: <clickurl>https://clientserver.com/receive_click</clickurl>
shortlink 0 | 1
Activación del reemplazo automático de enlaces.
Si su valor es 1 se reemplazarán todas las Urls del mensaje con un link corto (formato: labsmo.bi/XXXXXXX o dominio personalizado).
Se puede activar esta prestación de forma permanente para todos los mensajes en las Preferencias de la cuenta y en ese caso no es necesario incluir este parámetro.
Ejemplo: <shortlink>1</shortlink>
long 0 | 1
Activación de los SMS Concatenados en esta petición.
Si este campo tiene valor 1 el mensaje puede contener más de 160 caracteres. Más información sobre Cómo calcular el precio de un SMS.
Ejemplo: <long>1</long>
ucs2 0 | 1
Activación de los SMS Unicode en esta petición.
Si este campo tiene valor 1 el mensaje puede contener cualquier carácter, símbolo o emoji. La capacidad se reduce a 70 caracteres y se pueden enviar SMS concatenados y unicode. Más información sobre Cómo calcular el precio de un SMS.
Ejemplo: <ucs2>1</ucs2>
crt email
Envío de un SMS Certificado en esta petición.
Se enviará a la dirección que contenga este parámetro un e-mail con el documento PDF de certificación.
Ejemplo: <crt>info@client.es</crt>
crt_name string
Nombre de la entidad o compañía que envía el SMS certificado. Sólo tiene efecto si se envía conjuntamente con el parámetro crt.
Ejemplo: <crt_name>My Company SL</crt_name>
crt_id string
Identificador fiscal de la entidad o compañía que envía el SMS certificado. Sólo tiene efecto si se envía conjuntamente con el parámetro crt.
Ejemplo: <crt_id>ESB65213332</crt_id>
crt_lang string
Idioma del certificado. Sólo tiene efecto si se envía conjuntamente con el parámetro crt.
Valores: ES EN CA FR DE IT NL PT NL DA SV PL RO EL
Ejemplo: <crt_lang>EN</crt_lang>
nofilter 0 | 1
Si este campo tiene valor 1 no se aplicará el filtro de mensajes duplicados.
Se puede activar o desactivar esta prestación de forma permanente para todos los mensajes en las Preferencias de la cuenta y en ese caso no es necesario incluir este parámetro.
Ejemplo: <nofilter>1</nofilter>
RESULTADO
El resultado de cualquier petición API SMS http/POST se obtiene en formato XML con el elemento raíz <response> y con los siguientes elementos hijos:
code integer
Código identificador que indica si se ha podido procesar la petición de forma exitosa o si se ha producido un error. Posibles valores en la el apartado Errores.
Ejemplo: <code>0</code>
message string
Descripción que indica si se ha podido procesar la petición de forma exitosa o si se ha producido un error. Posibles valores en la el apartado Errores.
Ejemplo: <message>The message element cannot be empty</message>
subid string
Identificador de la petición API.
Ejemplo: <subid>6615686480e47</subid>

Ejemplo en VisualStudio.net

En el entorno VisualStudio.net apartado Solution Explorer hacer click en Add Service Reference e introducir la siguiente url: https://api.labsmobile.com/ws/services/LabsMobileWsdl.php?wsdl.
Es necesario dar un nombre al Namespace, por ejemplo "LabsMobileAPI".

  string resultado = new Client.LabsMobileAPI.SendSMS(
      "priv00x",
      "myUsername",
      "myToken",
  "<?xml version="1.0" encoding="utf-8"?>
      <sms>
          <recipient>
            <msisdn>34609542312</msisdn>
            <msisdn>34609542313</msisdn>
            <msisdn>34609542315</msisdn>
          </recipient>
          <message><![CDATA[This is an example message]]></message>
      </sms>")

  <?xml version="1.0" encoding="utf-8"?>
  <response>
        <code>0</code>
        <message>Message has been successfully sent</message>
        <subid>56fb9baa6bc22</subid>
  </response>

  <?xml version="1.0" encoding="utf-8"?>
  <response>
      <subid>6615686480e47</subid>
      <code>21</code>
      <message>The message element cannot be empty</message>
  </response>

Consulta de saldo

Consulta sobre el número de créditos disponibles de una cuenta.

ENDPOINT

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

PARÁMETROS
username email obligatorio
Email de nombre de usuario que identifica la cuenta que realiza el envío.
Ejemplo: email@mydomain.com
password string obligatorio
Token API generado en la sección Configuración API de la cuenta.
Ejemplo: lUHia713N5aByua79fU5s1Nlb6ItZ9ioVu
RESULTADO
El resultado se obtiene en formato XML con el elemento raíz <response> y con el siguiente elemento hijo:
messages float
Número de créditos disponibles en el saldo de la cuenta.
Ejemplo: <messages>32.45</messages>

Ejemplo en VisualStudio.net

En el entorno VisualStudio.net apartado Solution Explorer hacer click en Add Service Reference e introducir la siguiente url: https://api.labsmobile.com/ws/services/LabsMobileWsdl.php?wsdl. Es necesario dar un nombre al Namespace, por ejemplo "LabsMobileAPI".

  string resultado = new Client.LabsMobileAPI.GetCredit(
      "myUsername",
      "myToken")

  <?xml version="1.0" encoding="utf-8"?>
  <response>
      <messages>9.956954285714286</messages>
  </response>

  <html>
    <head>
      <title>403 Forbidden</title>
    </head>
    <body>
      <h1>403 Forbidden</h1>
    </body>
  </html>

Errores

A continuación se describe la lista completa de códigos que se obtiene en el formato XML de respuesta:

Código XML	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 request
21	The message element cannot be empty
23	There are no recipients
24	Too many recipients
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
35	The account has no enough credit for this sending
39	The value of the scheduled field is not a valid datetime format
41	Scheduled messages cannot be send in test mode

Recursos de soporte

Recomendamos consultes y tengas en cuenta los siguientes recursos de soporte en tu integración:

API de envío SMS WebService

A tener en cuenta

Autenticación

Configuración y filtros

Envío de mensajes SMS

ENDPOINT

PARÁMETROS

client string obsoleto

username email obligatorio

password string obligatorio

xmldata xml obligatorio

ELEMENTOS XML

sms xml obligatorio

recipient xml obligatorio

msisdn string obligatorio

message string obligatorio

scheduled YYYY-MM-DD HH:MM:SS

tpoa string

subid string

label string

test 0 | 1

ackurl url

clickurl url

shortlink 0 | 1

long 0 | 1

ucs2 0 | 1

crt email

crt_name string

crt_id string

crt_lang string

nofilter 0 | 1

RESULTADO

code integer

message string

subid string

Ejemplo en VisualStudio.net

Consulta de saldo

ENDPOINT

PARÁMETROS

username email obligatorio

password string obligatorio

RESULTADO

messages float

Ejemplo en VisualStudio.net

Errores