Manual de Integración SMS Inteligente (MAN-PP-03-15) #

Contenido

1. Control de Cambios…………………………………………………………………………………………… 2
2. Introducción…………………………………………………………………………………………………….. 3
3. Envío de Mensajes de Texto (MT)……………………………………………………………………….. 4
   • MT: Web Service Rest tipo GET……………………………………………………………………….. 5
   • MT: Web Service Rest tipo POST……………………………………………………………………… 8
   • MT: Web Service tipo SOAP…………………………………………………………………………… 13
4. Recepción de Mensajes de Texto (MO)………………………………………………………………. 18
   • MO – Web Service Rest tipo POST………………………………………………………………….. 19
5. Tablas de Caracteres Permitidos*……………………………………………………………………… 20
6. Web Service Consulta de Reportes Batch…………………………………………………………… 21
7. Package Report……………………………………………………………………………………………….. 26
8. Servicio de Notificación de Eventos……………………………………………………………………. 29

1.            Control de Cambios #

2.            Introducción #

Para la integración de nuestros clientes a la plataforma SMS Inteligente, contamos con varios APIs que permiten a nuestros aliados el envío y recepción de mensajes de texto, estas tecnologías facilitan una integración rápida y transparente con el fin de potencializar el negocio de nuestros clientes y asociados.

A continuación se detallan cada una de estas tecnologías (API) para un mayor entendimiento de su uso y complejidad.

3.            Envío de Mensajes de Texto (MT) #

La plataforma SMS Inteligente permite la integración para envió de mensajes originados por su plataforma (MT: Mobile Terminated) por medio de varios servicios de integración expuestos:

1. HTTP GET
2. WEB SERVICES (SOAP)

*Para envíos masivos se recomienda utilizar el método 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 continuación son un ejemplo, la ruta de envío debe ser suministrada por su consultor comercial.

3.1.            MT: Web Service Rest tipo GET #

Este API está basado en llamados HTTP GET ideales para transacciones básicas y rápidas hechas por el cliente a una URL. Bajo este esquema los parámetros de la solicitud de envío se adjuntan a la petición HTTP vía GET.

·         Autenticación #

El usuario se autentica por medio de usuario y contraseña codificados (en base 64) en el encabezado “Authorization” bajo el estándar “basic” de la siguiente forma:

·         URL de la petición: #

·         Parámetros: #

Tabla 1 Parámetros HTTP GET

·         Esquema de la respuesta #

{

“status”: 1,

“reason”: “Request Received”, “result”: {

“totalRequest”: 1,

“totalFailed”: 0, “receivedRequests”: [

{

“mobile”: “3118644939”,

“transactionId”: “postT02615L57G3118644939Rm4yx8Psmsi”, “status”: 1,

“reason”: “Request Received”

}

],

“failedRequests”: [],

“dateToSend”: “2018-01-26 14:42:00”,

“timeZone”: “America/Bogota”

}

}

Descripción de la respuesta:

• status: Código del resultado de la solicitud (número)
• reason: Resultado de la solicitud (texto)
• result: Detalle del resultado de la solicitud
  • totalRequest: Total de destinatarios recibidos en la solicitud
  • totalFailed: Total de destinatarios recibidos que NO se enviarán
  • ReceivedRequests: Lista detallada de destinatarios a los que se les enviará el mensaje
    • mobile: Número celular (GSM)
    • transactionId: Código de transacción del mensaje
    • status: Código de la razón de la falla
    • reason: Estado de la transacción/Razón de la falla
  • failedRequests: Lista de detalles de los destinatarios que NO se enviarán
    • mobile: Número celular (GSM)
    • transactionId: Código de transacción del mensaje único por Ej. getT02917L57G3118644939RdrvaxPsmsi
    • status: Código de la razón de la falla
    • reason: Estado de la transacción/Razón de la falla
  • dateToSend: Fecha y hora a la que saldrá el envío
  • timeZone: Zona horaria de la fecha a la que saldrá el envío

·         Código de Respuesta – Status: #

Tabla 2 Parámetros Respuesta HTTP GET

3.2.            MT: Web Service Rest tipo POST #

Este api está basado en llamados HTTP POST hechos por el cliente a una URL, bajo este esquema se encuentran varias funcionalidades adicionales como:

Envíos por lotes de mensajes: Posibilidad de enviar el mismo mensaje a una lista de destinatarios en una misma petición, la respuesta de la petición retorna la información de cada mensaje por lo que se recomiendan lotes de hasta 50 SMS. Permite también el envío de mensajes personalizados por cada destinatario de la petición.

Envíos Tipo Flash: Previa configuración y de acuerdo a la disponibilidad de la tecnología por operador/país, podrá realizar envío de peticiones tipo Flash.

Programación de envíos: Podrá realizar peticiones con un parámetro de fecha/hora en la que realizarán el envío.

URLs Cortas: este servicio permite el envío de URL corta, al usarse en batches podrá enviar el mismo vínculo a todos los destinatarios o una diferente a cada contacto.

CorrelationLabel: Permite añadir un identificador de mensajes que podrá consultar en reportes para agrupar peticiones.

·         Autenticación #

El usuario se autentica por medio de usuario y contraseña codificados (en base 64) en el encabezado “Authorization” bajo el estándar “basic” de la siguiente forma:

Bajo este esquema se debe enviar una petición con la siguiente estructura.

·         URL para consumir el servicio: #

Ejemplo de la petición #

• Content-Type: application/json

·         JSON petición: #

{

“country”: “string”, “dateToSend”: “string”, “message”: “string”, “encoding”: “string”, “messageFormat”: 0, “addresseeList”: [

{

“mobile”: “string”,

“correlationLabel”: “corelation ejemplo”, “url”: “string”

},

{

“mobile”: “string”,

“correlationLabel”: “corelation ejemplo”, “url”: “string”

},

{

“mobile”: “string”,

“correlationLabel”: “corelation ejemplo”, “url”: “string”

}

]

}

·         Parámetros: #

Tabla 3 Parámetros HTTP POST

·         Esquema de la respuesta #

{

“status”: 1,

“reason”: “Request Received”, “result”: {

“totalRequest”: 1,

“totalFailed”: 0, “receivedRequests”: [

{

“mobile”: “3118644939”,

“transactionId”: “postT02615L57G3118644939Rm4yx8Psmsi”, “status”: 1,

“reason”: “Request Received”

}

],

“failedRequests”: [],

“dateToSend”: “2018-01-26 14:42:00”,

“timeZone”: “America/Bogota”

}

}

Descripción de la respuesta: #

• status: Código del resultado de la solicitud (número)
• reason: Resultado de la solicitud (texto)
• result: Detalle del resultado de la solicitud
  • totalRequest: Total de destinatarios recibidos en la solicitud
  • totalFailed: Total de destinatarios recibidos que NO se enviarán
  • ReceivedRequests: Lista detallada de destinatarios a los que se les enviará el mensaje
    • mobile: Número celular (GSM)
    • transactionId: Código de transacción del mensaje
    • status: Código de la razón de la falla
    • reason: Estado de la transacción/Razón de la falla
  • failedRequests: Lista de detalles de los destinatarios que NO se enviarán
    • mobile: Número celular (GSM)
    • transactionId: Código de transacción del mensaje único por Ej. getT02917L57G3118644939RdrvaxPsmsi
    • status: Código de la razón de la falla
    • reason: Estado de la transacción/Razón de la falla
  • dateToSend: Fecha y hora a la que saldrá el envío
  • timeZone: Zona horaria de la fecha a la que saldrá el envío

·         Código de Respuesta – Status: #

Tabla 4 Parámetros Respuesta HTTP POST

3.3.            MT: Web Service tipo SOAP #

Este API está basado en la comunicación de servicios web a través de SOAP, permite además realizar envío de peticiones con las siguientes funcionalidades:

Envíos por lotes de mensajes: Posibilidad de enviar el mismo mensaje a una lista de destinatarios en una misma petición, la respuesta de la petición retorna la información de cada mensaje por lo que se recomiendan lotes de hasta 50 SMS. Permite también el envío de mensajes personalizados por cada destinatario de la petición.

Envíos Tipo Flash: Previa configuración y de acuerdo a la disponibilidad de la tecnología por operador/país, podrá realizar envío de peticiones tipo Flash.

Programación de envíos: Podrá realizar peticiones con un parámetro de fecha/hora en la que realizarán el envío.

URLs Cortas: este servicio permite el envío de URL corta, al usarse en batches podrá enviar el mismo vínculo a todos los destinatarios o una diferente a cada contacto.

CorrelationLabel: Permite añadir un identificador de mensajes que podrá consultar en reportes para agrupar peticiones.

·         WSDL del servicio expuesto: #

·         Autenticación #

La autenticación en este servicio se realiza por medio de Basic Authentication, en el que se deberá enviar el usuario y la contraseña asignada

·         Método Remoto #

Para el envío de mensajes se debe implementar el método getSmsSoapRequest con los siguientes parámetros:

·         Parámetros: #

Tabla 5 Parámetros Petición SOAP

·         XML petición: #

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:hab=”http://habitatclient.service.soapws.core.axesnet.com/“>

<soapenv:Header/>

<soapenv:Body>

<hab:getSmsSoapRequest>

<hab:country>57</hab:country>

<hab:message>Hola esto es una prueba</hab:message>

<hab:encoding></hab:encoding>

<hab:messageFormat></hab:messageFormat>

<hab:dateToSend></hab:dateToSend>

<!–1 o más peticiones para envíos por batch:–>

<hab:addresseeList>

<hab:mobile>3229462890</hab:mobile>

<hab:url></hab:url>

<hab:transactionId></hab:transactionId>

<hab:correlationLabel></hab:correlationLabel>

<hab:message>Hola test 1</hab:message>

</hab:addresseeList>

<hab:addresseeList>

<hab:mobile>3229462890</hab:mobile>

<hab:url></hab:url>

<hab:transactionId></hab:transactionId>

<hab:correlationLabel></hab:correlationLabel>

<hab:message>Hola test 2</hab:message>

</hab:addresseeList>

</hab:getSmsSoapRequest>

</soapenv:Body>

</soapenv:Envelope>

·         XML respuesta envío exitoso (petición batch 2 mensajes): #

<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”>

<SOAP-ENV:Header/>

<SOAP-ENV:Body>

<ns2:getSmsSoapResponse xmlns:ns2=”http://habitatclient.service.soapws.core.axesnet.com/“>

<ns2:status>1</ns2:status>

<ns2:result>

<ns2:failedRequests/>

<ns2:receivedRequests>

<ns2:mobile>3229462890</ns2:mobile>

<ns2:reason>Request Received</ns2:reason>

<ns2:status>1</ns2:status>

<ns2:transactionId>soapT3169L57G3229462890R1cte2Psmsi</ns2:transactionId>

</ns2:receivedRequests>

<ns2:receivedRequests>

<ns2:mobile>3229462890</ns2:mobile>

<ns2:reason>Request Received</ns2:reason>

<ns2:status>1</ns2:status>

<ns2:transactionId>soapT3169L57G3229462890Rn3eiuPsmsi</ns2:transactionId>

</ns2:receivedRequests>

<ns2:totalFailed>0</ns2:totalFailed>

<ns2:totalRequest>2</ns2:totalRequest>

</ns2:result>

<ns2:reason>Request Received</ns2:reason>

</ns2:getSmsSoapResponse>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Descripción de la respuesta: #

• status: Código del resultado de la solicitud (número)
• reason: Resultado de la solicitud (texto)
• result: Detalle del resultado de la solicitud
  • totalRequest: Total de destinatarios recibidos en la solicitud
  • totalFailed: Total de destinatarios recibidos que NO se enviarán
  • ReceivedRequests: Lista detallada de destinatarios a los que se les enviará el mensaje
    • mobile: Número celular (GSM)
    • transactionId: Código de transacción del mensaje
    • status: Código de la razón de la falla
    • reason: Estado de la transacción/Razón de la falla
  • failedRequests: Lista de detalles de los destinatarios que NO se enviarán
    • mobile: Número celular (GSM)
    • transactionId: Código de transacción del mensaje único por Ej. getT02917L57G3118644939RdrvaxPsmsi
    • status: Código de la razón de la falla

• reason: Estado de la transacción/Razón de la falla

• dateToSend: Fecha y hora a la que saldrá el envío
• timeZone: Zona horaria de la fecha a la que saldrá el envío

·         Código de Respuesta – Status: #

Tabla 6 Parámetros Respuesta SOAP

4.            Recepción de Mensajes de Texto (MO) #

Para la integración 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 continuación se detallan y ejemplifica el API ideal para poder guiar su construcción.

4.1.    MO – Web Service Rest tipo POST #

Este api está basado en llamados HTTP POST hechos a una URL del cliente. Bajo este esquema se debe poder enviar una petición con la estructura similar a la siguiente.

·         URL para consumir el servicio: #

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

• Content-Type: application/json

·         Petición Json: #

{

“Mobile”: “12345678”,

“Message”:”Hola esto es una prueba”

}

·         Valores Retornados #

Se espera retorne una línea de texto con los siguientes posibles valores:

{

“Status”: “(http code)”,

“Reason”: “(Descripción del estado de la transacción)”

}

NOTA: En el ejemplo expuesto en el presente documento puede añadirse parámetros de autenticación (Usuario, contraseña, Key) al Web Service para añadir seguridad de acceso.

5.             Tablas de Caracteres Permitidos* #

HTTP GET

Tabla 7 Caracteres Permitidos en el Mensaje Http Get

HTTP POST y SOAP

Tabla 8 Caracteres Permitidos en el Mensaje Post y Soap

• Para que el servicio funcione con algunos caracteres el mensaje XML debe enviarse con codificación ISO- 8859-1, el correcto envío de algunos caracteres puede tener limitantes por operador/país.

*Por limitantes de los operadores, el servicio de SMSi puede no soportar los siguientes caracteres:

£¥&áéíóúàèìòùÁÉÍÓÚÀÈÌÒÙÇØøÅåÆæߤÄÖÑñܧäöü\~€

6.            Web Service Consulta de Reportes Batch #

SMSi ofrece la posibilidad de realizar consultas a su Web Service HTTP POST para consulta de reportes paginados con múltiples filtros NO excluyentes para conocer el estado de las transacciones. El servicio se consume con la siguiente petición

·         Autenticación #

El usuario se autentica por medio de usuario y contraseña codificados (en base 64) en el encabezado “Authorization” bajo el estándar “basic” de la siguiente forma:

·         URL para consumir el servicio: #

• Content-Type: application/json

·         JSON petición: #

{

“filters”: { “clickReport”: true,

“dateToSendFrom”: “2018-01-01 01:00:00”,

“dateToSendTo”: “2018-01-09 01:00:00”,

“externalIdList”: [], “groupName”: “”,

“gsmList”: [],

“land”: “57”, “messageFormatList”: [], “page”: 1, “referenceName”: “”, “rowsPerPage”: 10, “shortCodeList”: [], “transactionIdList”: [], “userNameList”: []

}

}

·         Parámetros: #

Tabla 9 Parámetros HTTP POST Reportes

·         Esquema de la respuesta #

{

“status”: 1,

“reason”: “Request Received”, “result”: {

“reportList”: [

{

“dateIn”: “2017-11-17 09:08:37”,

“dateToSend”: “2017-11-17 09:08:37”,

“clickDateUpdated”: null, “clickCount”: 0,

“totalMessages”: 820281,

“sentMessages”: 0,

“inProcessMessages”: 0,

“failedMessages”: 0,

“canceledMessages”: 0,

“message”: “[GSM][NOMBRE][MENSAJE]”,

“shortCode”: “N/A”,

“transactionId”: “”, “externalId”: “26619831”, “userName”: “jperea”,

“processStatusName”: “ERROR”, “groupName”: ” “,

“referenceName”: “”,

“operatorName”: “Operator Unavailable”, “url”: “”,

“codedUrl”: “”,

“gsm”: “N/A”,

“messageFormatName”: “DEF_SMS_MESS”

}

],

“totalPages”: 130,

“currentPage”: 1

}

}

Descripción de la respuesta:

• status: Código del resultado de la solicitud (número)
• reason: Resultado de la solicitud (texto)
• result: Detalle del resultado de la solicitud
  • reportList: Listado de la información por transacción.
    • dateIn: Fecha/Hora del ingreso de la petición al sistema. Formato yyyy-MM-dd HH:mm:ss.
    • dateToSend: Fecha/Hora del salida de la petición al Formato yyyy-MM-dd HH:mm:ss.
    • clickCount: conteo de clics sobre una URL corta
    • totalMessages: Cantidad de mensajes que ocupan el texto
    • sentMessages: Muestra el total de mensajes en estado enviado que coinciden con el mismo externalId o Id de envío masivo
    • inProcessMessages: Muestra el total de mensajes en estado en proceso que coinciden con el mismo externalId o Id de envío masivo Web.
    • failedMessages: Muestra el total de mensajes en estado fallido que coinciden con el mismo externalId o Id de envío masivo
    • canceledMessages: Muestra el total de mensajes en estado cancelado por el usuario que coinciden con el mismo externalId o Id de envío masivo
    • message: Contenido del SMS
    • shortCode: Código usado como remitente del
    • transactionId: Id único del mensaje (Alfanumérico).
    • externalId: Id de la campaña/envío cargado por masivos mediante la web.
    • userName: Usuario que generó la transacción.
    • processStatusName: Nombre del estado del
    • groupName: Nombre del grupo Web que contiene el número
    • referenceName: Nombre de la campaña/referencia del envío
    • operatorName: Nombre del operador del número celular*.
    • url: Link original enviado mediante URLs
    • codedUrl: Identificador de la URL
    • gsm: Número celular al que se envió el
    • messageFormatName: Tipo de mensaje
  • totalPages: Número total de páginas del
  • currentPage: Página actual del

• El operador celular puede no corresponder al real o mostrarse como genérico en algunos países/operaciones.

·         Código de Respuesta – Status/Reason: #

Tabla 10 Parámetros Respuesta HTTP POST Reportes

7.            Package Report #

El servicio cuenta con un reporte de consulta de estado de paquetes; este tiene el mismo esquema de autenticación.

·         Autenticación #

El usuario se autentica por medio de usuario y contraseña codificados (en base 64) en el encabezado “Authorization” bajo el estándar “basic” de la siguiente forma:

· #

URL para consumir el servicio: #

• Content-Type: application/json

·         JSON petición: #

{

“land”: “”, “packageStateList”: [ “”

],

“packageTypeList”: [ “”

]

}

·         Parameters: #

land: Indicativo del país a buscar. (Obligatorio)

packageStateList: Lista de estados a filtrar; puede tener uno de los siguientes valores. (Opcional)

Tabla 11 Tipo de paquetes disponibles

packageTypeList: Lista de filtros por tipo de paquete; puede usarse uno de los siguientes estados. (Opcional)

·         Respuesta del servicio #

Tabla 12 Estado de paquetes

{

“status”: 1,

“reason”: “Request Received”, “result”: [

{

“totalSpent”: 5236,

“total”: 100000,

“available”: 94764, “state”: “ENABLED”,

“packageType”: “SMS”

},

{

“totalSpent”: 504,

“total”: 10000,

“available”: 9496, “state”: “ENABLED”,

“packageType”: “FLASH”

},

{

“totalSpent”: 0,

“total”: 10000,

“available”: 10000, “state”: “ENABLED”,

“packageType”: “DOC”

}

]

}

·         Código de Respuesta – Status: #

Tabla 13 Parámetros Respuesta HTTP POST

8.            Servicio de Notificación de Eventos #

Este servicio permite el envío de notificaciones de múltiples eventos que ocurren en los productos o servicios de SMS Inteligente, de tal forma que no es necesario solicitar información de forma periódica; en su lugar, el cliente debe publicar un servicio web (WS) en el cuál nuestra plataforma realizará la petición a este WS con toda la información del evento en cuestión. Los eventos enviados pueden ser desde el estado final de un mensaje de texto (SMS), finalización de campañas, hasta un evento de clic realizado a una de nuestras URL corta, entre otros.

1.      WS que debe ser expuesto por el cliente #

a.      Tipo REST #

El servicio expuesto debe aceptar peticiones REST de tipo POST.

b.      Tipo de contenido #

El servicio debe poder recibir información en formato Json, para lo cual se le envía el encabezado “Content-Type”: “application/json”; lo anterior permite el envío del cuerpo como se muestra a continuación.

c.       Cuerpo a recibir: #

El servicio debe poder recibir la siguiente información:

{

“userName”: {{user-name}},

“event”: {{event-name}},

“eventDate”: {{event-date}}, “detail”: {

{{detail-object}}

}

}

Descripción:

• {{user-name}}: [tipo texto] Es el nombre del usuario configurado para recibir notificaciones de
• {{event-name}}: [tipo texto] Es el nombre del evento; este identifica cual es el evento que se recibe en el WS. Este puede ser:
  • SMS_DLR
  • CLICK

• {{event-date}}: [tipo fecha] Esta es la fecha de registro de creación del

evento; su formato es “yyyy-MM-dd’T’HH:mm:ssZ” (ISO8601)

• {{detail-object}}: Este objeto contiene todo el detalle particular del evento, está representado por una lista de pares clave,

Ejemplo evento clic:

{

“userName”: “clienteA”, “event”: “CLICK”, “detail”: {

“clickCount”: 5,

“messageSentDate”: “2018-11-04 12:21:26”, “shortUrl”: “http://aldm.co/nDgsog3423eae”, “destination”: 8714354,

“longUrl”: “http://electroeing.wordpress.com“, “transactionId”: “10056T11412LG3118714354Rn6hj1Pshrturl”, “info”: {

“browser”: “Firefox”, “operativeSystem”: “Linux”, “device”: “Personal computer”, “clickDate”: “2018-12-04 12:52:48”

}

},

“eventDate”: “2018-12-04T12:52:48-0500”

}

·         Parámetros: #

Tabla 14 Parámetros Notificación de evento Clic

Ejemplo evento DLR:

{ “userName”:”ClienteA”, “detail”: {

“processStatus”: ” Entregado al operador”, “messageFormat”: “NORMAL_SMS”, “dateToSend: “2019-04-09 14:09:39”,

“destination”:”3043541901″, “totalMessages”:”1″,

“message”: “Hola, esto es un mensaje de prueba”, “transactionId”:”T3914L593G995809631Rm5uqisdsr”

},

“event”:SMS_DLR,

“eventDate”: “2019-04-09 14:09:39”

}

·         Parámetros: #

Tabla 15 Parámetros Notificación de evento Clic

d.      opciones de seguridad #

El servicio de notificaciones cuenta con la posibilidad de configurar seguridad, de tal forma que el servicio expuesto por el cliente pueda estar protegido; las siguientes son las opciones de configuración

i.             Básica #

En esta configuración, se envía el siguiente encabezado al WS del cliente.

e.      respuesta del WS (posibles estados) #

El WS expuesto por el cliente debe responder a las peticiones el siguiente cuerpo en formato Json

{

“status”: {{status}},

“reason”: {{reason}}

}

1 https://www.base64encode.org/

Descripción:

• {{status}}, {{reason}}: Este es el ID del estado de la petición y su descripción respectivamente;estos puedes contener los siguientes
  • Caso exitoso: 1, “Request Received”
  • Falla en la autenticación: -1, “Authentication Error”
  • Falla interna del servicio expuesto: -5, “Transacction Error”

2.      Requerimientos de configuración #

Datos requeridos para la configuración del servicio se listan a continuación

1. Usuario SMS inteligente

• Solicitarlo al comercial a cargo

1. Sin autenticación
   1. dominio completo del servicio

1. Con autenticación básica
   1. dominio completo del servicio
   2. usuario

• contraseña