Está en la página 1de 13

ALDEAMO

Manual de Integracin
SMS Inteligente
www.aldeamo.com
Contenido
1. Control de Cambios ......................................................................................................... 2
2. Introduccin .................................................................................................................... 3
3. Envo de Mensajes de Texto (MT) ................................................................................... 4
3.1. MT: Webservice Rest tipo GET ................................................................................. 5
3.2. MT: Webservice tipo SOAP ....................................................................................... 6
3.3. MT: Webservice Rest tipo POST ............................................................................... 8
4. Recepcin de Mensajes de Texto (MO) .......................................................................... 9
4.1. MO - Webservice Rest tipo GET ............................................................................. 10
4.2. MO - Webservice Rest tipo POST ........................................................................... 10
4.3. MO - Webservice tipo SOAP ................................................................................... 11
5. Tablas de Caracteres Permitidos* ................................................................................. 12

www.aldeamo.com 1
1. Control de Cambios

Cambio Autor Fecha

Ivens Zambrano 01/Septiembre/2014


Actualizacin general del
manual de integracin de
sobre VPN

Hader Ceron 08/Octubre/2014


Actualizacin parmetros
en peticion POST y SOAP

Ivens Zambrano 05/Noviembre/2014


Ajuste en la version y los
mtodos disponibles

Daniel Valero 25/Enero/2016


Ajuste en la versin y los
mtodos disponibles

Daniel Gmez 02/Mayo/2016


Actualizacin tipo de
conexin

Inclusin ejemplos Daniel Gmez 07/Julio/2016


Recepcin de mensajes

Daniel Gmez 16/Enero/2017


Actualizacin Caracteres
por tipo de integracin

www.aldeamo.com 2
2. Introduccin
Para la integracin de nuestros clientes a la plataforma SMS Inteligente, contamos con
varios APIs que permiten a nuestros aliados el envo y recepcin de mensajes de texto, estas
tecnologas facilitan una integracin rpida y transparente con el fin de potencializar el
negocio de nuestros clientes y asociados.

A continuacin se detallan cada una de estas tecnologas (API) para un mayor


entendimiento de su uso y complejidad.

www.aldeamo.com 3
3. Envo de Mensajes de Texto (MT)

La plataforma SMS Inteligente permite la integracin para envi de mensajes originados por
su plataforma (MT: Mobile Terminated) por medio de varios servicios de integracin
expuestos:
A. HTTP GET
B. WEB SERVICES (SOAP)

*Para envos masivos se recomienda utilizar el mtodo HTTP POST para evitar cargas
masivas en el servidor que pueden causar fallas en el funcionamiento del servicio.
*Las URL o IP:Puerto que se listan a continuacin son un ejemplo, la ruta de envo debe ser
suministrada por su consultor comercial.

www.aldeamo.com 4
3.1. MT: Webservice Rest tipo GET
Este API est basado en llamados HTTP GET hechos por el cliente a una URL. Bajo este
esquema los parmetros de la solicitud de envo se adjuntan a la peticin HTTP va GET.

URL para consumir el servicio:


http(s)://{IP}:{puerto}/smsr/r/hcws/smsSendGet/{username}/{password}/{mobile}/{count
ry}/{message}/{operator}

Parmetros:

Parmetro Descripcin
username Usuario asignado al cliente para el envo.
password Contrasea asignada.
mobile Telfono del destino.
country Cdigo internacional del pas.
message Texto del mensaje a ser enviado.
operator (Opcional) Operador del nmero, en caso que sea portado.
Valores permitidos
Tigo:57-tigo
Movistar: 57-movistar
Claro: 57-claro
Comcel: 57-avantel
Tabla 1. Parmetros HTTP GET

Valores Retornados
Se retornar una lnea de texto con los siguientes posibles valores:

-1|LdapException: Ldap authentication error


-2|User doesn't exists
-3|User doesn't have accounts
-4|Invalid operator
-5|Invalid mobile number
-6|The user doesn't have available messages to send
-7|InfraestructureException: Message send error

Cualquier nmero mayor que cero (0), representa un identificador nico de la peticin,
lo cual indica que la transaccin fue exitosa.

{id_mensaje}|Message sent.

Ej: 123456|Message sent.

www.aldeamo.com 5
3.2. MT: Webservice tipo SOAP
Este api est basado en la comunicacin de servicios web a travs de SOAP.

WSDL del servicio expuesto:


http(s)://{IP}:{puerto}/sms/sms.wsdl

Mtodo Remoto
Para el envo de mensajes se debe implementar el mtodo SmsSendSoap con los siguientes

Parmetros:

Parmetro Descripcin

username Usuario asignado al cliente para el envo.


password Contrasea asignada.
mobile Telfono del destino.
country Cdigo internacional del pas.
message Texto del mensaje a ser enviado.
operator (Opcional) Operador del nmero, en caso que sea portado.
Valores permitidos:
Tigo:57-tigo
Movistar: 57-movistar
Claro: 57-claro
Comcel: 57-avantel
Tabla 4. Parmetros SOAP
XML peticin:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:hab="http://habitatclient.service.soapws.core.com/">
<soapenv:Header/>
<soapenv:Body>
<hab:smsSendSoap>
<username>{username}</username>
<password>{password}</password>
<country>{country}</country>
<mobile>{mobile}</mobile>
<message>{message}</message>
<operator>{operator}</operator>
</hab:smsSendSoap>
</soapenv:Body>
</soapenv:Envelope>

www.aldeamo.com 6
XML respuesta envo exitoso:
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:smsSendSoapResponse
xmlns:ns2="http://habitatclient.service.soapws.core.com/">
<return>{id_mensaje}|Message sent</return>
</ns2:smsSendSoapResponse>
</S:Body>
</S:Envelope>

XML respuesta error:


<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:smsSendSoapResponse
xmlns:ns2="http://habitatclient.service.soapws.core.com/">
<return>{codigo}|{descripcion}</return>
</ns2:smsSendSoapResponse>
</S:Body>
</S:Envelope>

Cdigos retornados en caso de excepcin:

-1|LdapException: Ldap authentication error


-2|User doesn't exists
-3|User doesn't have accounts
-4|Invalid operator
-5|Invalid mobile number
-6|The user doesn't have available messages to send
-7|InfraestructureException: Message send error

www.aldeamo.com 7
3.3. MT: Webservice Rest tipo POST
Este api est basado en llamados HTTP POST hechos por el cliente a una URL. Bajo este
esquema se debe enviar una peticin con la siguiente estructura.

URL para consumir el servicio:


http://{ip}:{port}/smsr/r/hcws/smsSendPost/

Content-Type: application/xml
XML peticin:
<?xml version="1.0" encoding="ISO-8859-1"?>
<sending>
<authentication>
<username>${username}</username>
<password>${password}</password>
</authentication>
<country>${country}</country>
<recipients>
<sms>
<mobile>${mobile}</mobile>
<message>${message}</message>
<operator></operator>
</sms>
</recipients>
</sending>

Valores Retornados
Se retornar una lnea de texto con los siguientes posibles valores:

-1|LdapException: Ldap authentication error


-2|User doesn't exists
-3|User doesn't have accounts
-4|Invalid operator
-5|Invalid mobile number
-6|The user doesn't have available messages to send
-7|InfraestructureException: Message send error

Cualquier nmero mayor que cero (0), representa un identificador nico de la peticin, lo
cual indica que la transaccin fue exitosa.

www.aldeamo.com 8
4. Recepcin de Mensajes de Texto (MO)
Para la integracin de nuestra plataforma SMS Inteligente hacia Web Services expuestos
por nuestros clientes en el proceso de entrega de mensajes originados por los usuarios
desde sus celulares (MO: Mobile Originated), se sugiere generar un servicio web en alguno
de los API que se describen en el presente documento.
A continuacin se detallan y ejemplifican cada una de estas tecnologas (API) para poder
guiar su construccin.

www.aldeamo.com 9
4.1. MO - Webservice Rest tipo GET
Este API est basado en llamados HTTP GET hechos por Aldeamo a una URL del cliente. Bajo
este esquema los parmetros de la solicitud de envo se adjuntan a la peticin HTTP va GET.

URL para consumir el servicio:


http://{ip}:{port}//sms_in/<mensaje>/<numero>/

Valores Retornados
Se espera retorne una lnea de texto con los siguientes posibles valores:

1 | Transaccin exitosa
0 | Error

4.2. MO - Webservice Rest tipo POST


Este api est basado en llamados HTTP POST hechos por Aldeamo a una URL del cliente.
Bajo este esquema se debe poder enviar una peticin con la estructura similar a la siguiente.

URL para consumir el servicio:


http://{ip}:{port}/sms_in/smsPost/

Content-Type: application/xml
XML peticin:
<?xml version="1.0" encoding="ISO-8859-1"?>
<sending>
<recipients>
<sms>
<mobile>${mobile}</mobile>
<message>${message}</message>
</sms>
</recipients>
</sending>

Valores Retornados
Se espera retorne una lnea de texto con los siguientes posibles valores:
1 | Transaccin exitosa
0 | Error

www.aldeamo.com 10
4.3. MO - Webservice tipo SOAP
Este api est basado en la comunicacin de servicios web a travs de SOAP.

WSDL del servicio expuesto:


http(s)://{IP}:{puerto}/sms_in/sms.wsdl

XML peticin:
Se espera poder realizar una peticin de entrega de mensajera con parmetros similares a
los siguientes:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:hab="http://XXXXXXX/">
<soapenv:Header/>
<soapenv:Body>
<hab:smsSoap>
<mobile>{mobile}</mobile>
<message>>{message}</message>
</hab:smsSoap>
</soapenv:Body>
</soapenv:Envelope>

XML respuesta envo exitoso:


<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:smsResponse
xmlns:ns2="http://habitatclient.service.soapws.core.axesnet.com/">
<return>1 |Transaccion exitosa</return>
</ns2:smsResponse>
</S:Body>
</S:Envelope>

Cdigos retornados en caso de excepcin:


1 | Transaccin exitosa
0 | Error

NOTA: En cualquiera de los ejemplos expuestos en el presente documento puede aadirse


parmetros de autenticacin (Usuario, contrasea, Key) al Web Service para aadir
seguridad de acceso.
www.aldeamo.com 11
5. Tablas de Caracteres Permitidos*
HTTP GET
@ 0 A O a o
! 1 B P b p
" 2 C Q c q
$ 3 D R d r
' 4 E S e s
( 5 F T f t
) 6 G U g u
* 7 H V h v
+ 8 I W i w
, 9 J X j x
- = K Y k y
. ; L Z l z
: [ M m
] N n
Tabla 2. Caracteres Permitidos Mensaje

HTTP POST y SOAP


@ 0 A P a p
! 1 B Q b q
" 2 C R c r
$ 3 D S d s
' 4 E T e t
( 5 F U f u
) 6 G V g v
* 7 H W h w
+ 8 I X i x
, 9 J Y j y
- = K Z k z
. # L / l %
: ; M { m
[ ] O } o
Tabla 5. Caracteres Permitidos en el Mensaje
* Para que el servicio funcione con algunos caracteres el mensaje XML debe enviarse con
codificacin ISO-8859-1, el correcto envo de algunos caracteres puede tener limitantes
por operador/pas.

*Por limitantes de los operadores, el servicio de SMSi NO soporta los siguientes


caracteres: &\~
www.aldeamo.com 12