API de envío SMS WebService
La API SMS WebService está diseñada para técnicos y clientes que quieran conectar sus aplicaciones con la plataforma de mensajerí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 integració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/
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
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.
Ejemplo XMLdata<?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/
.
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
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/
. 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:
- Descripción, manual y ejemplos de código de la API de envío SMS
- Guía técnica de un proceso de validación o autenticación OTP por SMS
- Todas las versiones y funcionalidades de la API de LabsMobile
- Tutorial primeros pasos de una integración API
- Crea una cuenta de prueba
- Recomendaciones y buenas prácticas en cualquier integración
- Plugins, módulos y extensiones
- ¿Necesitas ayuda? Contacta con nuestros técnicos