Manual de Integración SMS Inteligente

Table of Contents

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
  4. Recepción de Mensajes de Texto (MO)………………………………………………………………. 18
  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 #

VersiónFechaDescripción de la ModificaciónResponsable (s)
 

1

 

01/09/2014

 

Actualización general del manual de integración sobre VPN

 

Ivens Zambrano

 

2

 

08/10/2014

Actualización parámetros en petición POST y SOAP 

Hader Ceron

 

3

 

05/11/2014

Ajuste en la versión y los métodos disponibles 

Ivens Zambrano

 

4

 

25/01/2016

Ajuste en la versión y los métodos disponibles 

Daniel Valero

 

5

 

02/05/2016

 

Actualización tipo de conexión

 

Daniel Gómez

 

6

 

07/Julio/2016

 

Inclusión ejemplos Recepción de mensajes

 

Daniel Gómez

 

7

 

16/01/2017

Actualización Caracteres por tipo de integración 

Daniel Gómez

 

8

 

01/09/2017

 

Actualización Método Post Flash

 

Daniel Gómez

 

9

 

04/12/2017

 

Actualización Métodos de Consulta

 

Daniel Gómez

 

10

 

29/01/2018

 

Actualización método REST

 

Daniel Gómez

 

11

 

09/02/2018

Actualización Cambios en WS tipo Rest MT y Reports 

Daniel Gómez

 

12

 

11/09/2018

Inclusión Saltos de línea correlationLabel en integraciones MT POST 

Daniel Gómez

 

13

 

09/01/2019

 

Actualización Cambios en WS Reports

 

Daniel Gómez

 

14

 

03/02/2020

 

Actualización Notificador de Eventos DLR y nueva URL WS SMS

Daniel Gómez Víctor Amarillo

 

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: #

 

ParámetroDescripciónObligatoriedad
UsuarioUsuario de las credenciales creadas para el cliente.Obligatorio
ContraseñaContraseña asignada para el cliente.Obligatorio
NumeroCelularDestinatario del mensaje (número celular o GSM sin prefijos)Obligatorio
CódigoPaísCódigo Internacional asignado para el paísObligatorio
MensajeTexto del mensaje; no debe tener caracteres que afecten la URL de la petición.Obligatorio
 

Formato

Tipo de mensaje a enviar, puede ser: SMS normal (1)

SMS Flash (2) – Requiere configuración previa.

 

Opcional

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: #

 

CÓDIGODESCRIPCIÓNNIVEL
1Petición recibida con éxitoGeneral/Detallado
-1Error de autenticaciónGeneral
-2Ruta no configuradaDetallado
-3Número celular inválidoDetallado
-4Crédito insuficienteGeneral
-5Error interno de la transacciónGeneral/Detallado
-6URL a acortar inválidaDetallado
-7Fecha de envío inválidaGeneral
-8Petición con formato inválidoGeneral
-9Usuario bloqueado por intentos fallidosGeneral
-10Código de país inválidoGeneral
-11Mensaje del cuerpo inválidoGeneral
-12ID de transacción InválidaDetallado

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: #

 

ParámetroDescripciónObligatoriedad
UsuarioUsuario de las credenciales creadas para el cliente.Obligatorio
ContraseñaContraseña asignada para el cliente.Obligatorio
Código PaísCódigo Internacional asignado para el paísObligatorio
 

 

 

 

Mensaje

Texto del mensaje; no debe tener caracteres que afecten la URL de la petición.

 

Nota: para incluir Saltos de Línea* en los mensajes, use la etiqueta <br>.

*Esta funcionalidad no está disponible en todos los operadores/países, por favor valide con su asesor

comercial la disponibilidad de la llegada del salto de línea en su destino de SMS.

 

 

 

 

Obligatorio

 

Formato

Tipo de mensaje a enviar, puede ser: 

Opcional

SMS normal (1)
SMS Flash (2) – Requiere configuración previa.
 

 

 

 

 

AdresseeList

Lista de destinatarios del mensaje:

Encoding: Tipo de codificación en la que se recibe el texto del mensaje (ej: GSM7)

 

Opcional

Mobile: Destinatario del mensaje (número celular o GSM)Obligatorio
URL: Dirección que se desea mandar al servicio para que sea acortada y agregada en el mensaje.Opcional
CorrelationLabel: Identificador de correlación de cada mensaje en la petición, úselo para poder agrupar y

asociar transacciones en reportes.

 

Opcional

 

 

dateToSend

Fecha y hora en la que se desea enviar el mensaje; el formato de la fecha DEBE ser “yyyy-MM-dd HH:mm:ss”. La zona horaria asignada a la fecha es la del país de destino; si no se envía, se asume que es un mensaje inmediato. 

 

Opcional

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: #

 

CÓDIGODESCRIPCIÓNNIVEL
1Petición recibida con éxitoGeneral/Detallado
-1Error de autenticaciónGeneral
-2Ruta no configuradaDetallado
-3Número celular inválidoDetallado
-4Crédito insuficienteGeneral
-5Error interno de la transacciónGeneral/Detallado
-6URL a acortar inválidaDetallado
-7Fecha de envío inválidaGeneral
-8Petición con formato inválidoGeneral
-9Usuario bloqueado por intentos fallidosGeneral
-10Código de país inválidoGeneral
-11Mensaje del cuerpo inválidoGeneral
-12ID de transacción InválidaDetallado

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: #

 

ParámetroDescripciónObligatoriedad
UsuarioUsuario de las credenciales creadas para el cliente.Obligatorio
ContraseñaContraseña asignada para el cliente.Obligatorio
Código PaísCódigo Internacional asignado para el paísObligatorio
 

Mensaje

 

Texto del mensaje; no debe tener caracteres que afecten la URL de la petición.

 

Obligatorio

 

 Nota: para incluir Saltos de Línea* en los mensajes, use la etiqueta <br>.

*Esta funcionalidad no está disponible en todos los operadores/países, por favor valide con su asesor comercial la disponibilidad de la llegada del salto de línea

en su destino de SMS.

 
 

Formato

Tipo de mensaje a enviar, puede ser: SMS normal (1)

SMS Flash (2) – Requiere configuración previa.

 

Opcional

 

 

 

 

 

AdresseeList

Lista de destinatarios del mensaje:

Encoding: Tipo de codificación en la que se recibe el texto del mensaje (ej: GSM7)

 

Opcional

Mobile: Destinatario del mensaje (número celular o GSM)Obligatorio
URL: Dirección que se desea mandar al servicio para que sea acortada y agregada en el mensaje.Opcional
CorrelationLabel: Identificador de correlación de cada mensaje en la petición, úselo para poder agrupar y

asociar transacciones en reportes.

 

Opcional

 

 

dateToSend

Fecha y hora en la que se desea enviar el mensaje; el formato de la fecha DEBE ser “yyyy-MM-dd HH:mm:ss”. La zona horaria asignada a la fecha es la del país de destino; si no se envía, se asume que es un mensaje inmediato. 

 

Opcional

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: #

 

CÓDIGODESCRIPCIÓNNIVEL
1Petición recibida con éxitoGeneral/Detallado
-1Error de autenticaciónGeneral
-2Ruta no configuradaDetallado
-3Número celular inválidoDetallado
-4Crédito insuficienteGeneral
-5Error interno de la transacciónGeneral/Detallado
-6URL a acortar inválidaDetallado
-7Fecha de envío inválidaGeneral
-8Petición con formato inválidoGeneral
-9Usuario bloqueado por intentos fallidosGeneral
-10Código de país inválidoGeneral
-11Mensaje del cuerpo inválidoGeneral
-12ID de transacción InválidaDetallado

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

@0AOao
!1BPbp
2CQcq
$3DRdr
4ESes
(5FTft
)6GUgu
*7HVhv
+8IWiw
,9JXjx
=KYky
.;LZlz
:[M m 
 ]N n 

Tabla 7 Caracteres Permitidos en el Mensaje Http Get

 

HTTP POST y SOAP

@0APap
!1BQbq
2CRcr
$3DSds
4ETet
(5FUfu
)6GVgv
*7HWhw
+8IXix
,9JYjy
=KZkz
.#L/l%
:;M{m 
[]O}o 

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: #

 

ParámetroDescripciónObligatoriedad
UsuarioUsuario de las credenciales creadas para el cliente.Obligatorio
ContraseñaContraseña asignada para el cliente.Obligatorio
clickReportIndica si se desea generar un reporte que cuente la información de acceso a una URL corta enviada; esto

es un reporte detallado y lo hace por cada destinatario. Posibles valores: “true” o “false”

Opcional
dateToSendFromFecha inicial del rango temporal a buscar.Obligatorio
dateToSendToFecha final del rango temporal a buscar.Obligatorio
externalIdListEs una lista de ID por campaña (agrupado de transacciones) que se generan por envíos masivos

Web.

Opcional
groupNameFiltra los envíos por un nombre de un grupo que se tenga en la plataforma web.Opcional
gsmListUna lista de números celular por los cuales buscar.Opcional
landCódigo del país sobre el cual realizar la búsqueda.Obligatorio
messageFormatListUna lista para filtrar por formato de mensaje enviado por su número que corresponde a:

1  – SMS Normal

2  – SMS Flash 3 – SMSDocs

Opcional
PageNúmero de la página a traer; este parámetro va de la mano con “rowsPerPage”.Obligatorio
rowsPerPageCantidad de registros a traer en la consulta.Obligatorio
referenceNameBuscar un envío por nombre de campañaOpcional
shortCodeListFiltrar por una lista de códigos cortosOpcional
transactionIdListEs una lista de ID único que se genera al recibir la

petición y se retorna al consumir el WS REST; este busca ese detallado.

Opcional
userNameListUna lista de los nombres de los usuarios por los que se desea filtrar el reporte; retorna un detallado.Opcional

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: #

 

CÓDIGODESCRIPCIÓNNIVEL
1Petición recibida con éxitoGeneral/Detallado
-1Error de autenticaciónGeneral
-2Ruta no configuradaDetallado
-3Número celular inválidoDetallado
-4Crédito insuficienteGeneral
-5Error interno de la transacciónGeneral/Detallado
-6URL a acortar inválidaDetallado
-7Fecha de envío inválidaGeneral
-8Petición con formato inválidoGeneral
-9Usuario bloqueado por intentos fallidosGeneral
-10Código de país inválidoGeneral
-11Mensaje del cuerpo inválidoGeneral
-12ID de transacción InválidaDetallado

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)

 

EstadoDescripción
SMSPaquete de mensajes corrientes.
FLASHPaquete de mensajería tipo flash
DOCPaquete de mensajería con archivos adjuntos

Tabla 11 Tipo de paquetes disponibles

 

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

 

EstadoDescripción
ENABLEDPaquete en estado normal y listo para ser consumido.
DISABLEDPaquete deshabilitado manualmente.
EXPIREDPaquete con fecha de expiración posterior a la actual.
FINISHEDPaquete consumido en su totalidad.

 

 

·         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: #

 

CÓDIGODESCRIPCIÓNNIVEL
1Petición recibida con éxitoGeneral/Detallado
-1Error de autenticaciónGeneral
-2Ruta no configuradaDetallado
-3Número celular inválidoDetallado
-4Crédito insuficienteGeneral
-5Error interno de la transacciónGeneral/Detallado
-6URL a acortar inválidaDetallado
-7Fecha de envío inválidaGeneral
-8Petición con formato inválidoGeneral
-9Usuario bloqueado por intentos fallidosGeneral
-10Código de país inválidoGeneral
-11Mensaje del cuerpo inválidoGeneral
-12ID de transacción InválidaDetallado

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: #

 

ParámetroDescripción
clickCountContiene el número total de clics efectuados sobre la URL
messageSentDateFecha y hora del envío de la transacción con la URL
shortUrlURL acortada por el servicio y enviada a través de la notificación.
destinationContiene el destinatario de la URL.
longUrlLink original al que redirige la URL corta del servicio.
transactionIdIdentificador único de la transacción en plataforma.
InfoContiene el detalle del evento reportado:

 

“browser”: Navegador desde el que cual se accedió a la URL corta. “operativeSystem”: Sistema Operativo del dispositivo desde el cual se accedió a la URL corta.

“device”: Tipo de dispositivo desde el cual se accedió a la URL corta. “clickDate”: Fecha hora del evento clic notificado: AAAA-MM-DD hh:mm:ss

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: #

 

ParámetroDescripción
processStatusContiene el nombre del estado de la transacción:

·         Entregado al operador

·         No enviado

·         Cancelado

·         Expirado

·         Operador fallido

·         Lista negra

·         Número inválido

·         Operador NO disponible

·         Lista negra por servicio

·         Fallido por enrutamiento con operador NO disponible

·         Ruta NO configurada

·         Reintento a otra ruta por servicio

·         Calendario no permitido por el operador

·         Mensaje Limitado por el operador

·         Entregado al operador, pendiente confirmación entrega al móvil

 

NOTA: Los estados “Entregado al Operador” y “Entregado al operador, pendiente confirmación entrega la móvil”, reflejan transacciones exitosas que consumen créditos de la bolsa habilitada, si luego de 24 horas de la

transacción no se tiene un DLR que las modifique serán consideradas como exitosas.

messageFormatEs el tipo de mensaje enviado:

·         NORMAL_SMS,

·         FLASH_SMS,

·         DOC_SMS,

·         DOC_BUILDER,

·         DOC_SMS_2,

·         DOC_SMS_4;

 

dateToSendEs la fecha de envío de la transacción.
destinationContiene el destinatario de la transacción.
totalMessagesCantidad de mensajes de texto consumidos por la transacción.
messageContenido del mensaje.
transactionIdIdentificador único de la transacción en plataforma.

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}}

}

 

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

Powered by BetterDocs

Leave A Comment

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.