El problema

En ocasiones es conveniente enviar mensajes de confirmación a terceras personas sobre acciones que se han realizado sobre el sistema en su nombre. Este sería el caso de la atención telefónica para el registro de pedidos, donde es posible cometer errores en la transcripción de la información del cliente que siempre es mejor resolver cuanto antes.

Aunque la comunicación por email es una buena manera de producir esta comunicación, no goza de la inmediatez de los mensajes SMS y en ocasiones puede pasar demasiado tiempo hasta que el cliente pueda revisar su bandeja de entrada y verificar que el registro de su pedido contiene la información que espera.

La mensajería SMS proporciona una solución al problema, puesto que en un elevado número de casos, los clientes realizan su pedido desde el mismo dispositivo en el que pueden recibir mensajes de confirmación.

La solución con Dolibarr MensatekSMS

Dolibarr MensatekSMS es una solución modular que permite el envío de mensajes SMS basados en las propiedades de los objetos estándar de Dolibarr.

Es posible configurar tanto el envío automático de mensajes SMS a los clientes desde los disparadores nativos del sistema (triggers), como el envío manual de mensajes desde las fichas de los distintos objetos que se encuentren configurados.

La solución permite configurar tanto el envío de SMS Masivos como SMS Certificados tanto de forma automática atendiendo a los disparadores nativos de los distintos objetos, como de forma manual desde las fichas correspondientes.

SMS Masivos

Aunque el servicio de Mensatek permite el envío de mensajes personalizados de forma masiva, Dolibarr MensatekSMS implementa el envío de un mensaje al destinatario que coincide con el contacto para el objeto que se trata.

SMS Certificados

Dolibarr MensatekSMS es posible configurar el envío de mensajes SMS con validez legal. Con las mismas aplicaciones que un Burofax o Carta certificada pero mucho más rápido ya que es instantáneo, eficiente y más económico. El servicio proporciona una certificación con validez jurídica del contenido del mensaje, la fecha de envío y la fecha/hora de recepción por parte del destinatario mediante certificaciones de las trazas y acuses de recibo de los operadores de comunicaciones implicados, equiparándose a otros medios telemáticos disponibles en la actualidad como el Burofax o la Carta Certificada. 

Instalación

Versión del Módulo: 1.0
Creador/Licencia: Federico García-Patiño / GPL-v3
Idioma interfaz usuario: Inglés, Español
Ayuda/Soporte: [email protected]
Prerrequisitos:

• Versión min Dolibarr: 16.x

• Versión max Dolibarr: 17.0.2

Instalación (desde Dolibarr v9+)

• Vaya al menú Inicio - Configuración - Módulos - Implemente un módulo externo y envíe el zip

• El módulo o tema está entonces disponible y activable.

Para instalar este módulo (Dolibarr v8-):

• Descargar el archivo del módulo (archivo .zip) desde la web DoliStore.com

• Ponga el archivo en el directorio raíz de Dolibarr.

• Descomprima el zip archivo, por ejamplo usando el comando  unzip module_mensateksms-1.0.zip 

• El módulo está listo para ser activado.

Configuración

Antes de comenzar a utilizar Dolibarr MensatekSMS es necesario completar algunos parámetros que permiten la conectividad con los servicios de Mensatek. A continuación se describen estos parámetros y la utilidad que proporcionan.

Conexión con Mensatek

• URL para la recarga de créditos: crea un acceso directo a la página de Mensatek para la recarga de créditos.
  https://www.mensatek.com/clientes/recarga.php
  
  

• URL del Servicio: url donde se enviarán las peticiones a los servicios de Mensatek para el envío de mensajes SMS y las consultas de créditos
  https://api.mensatek.com/v7/
  

• End Point para envío de mensajes SMS masivos
  EnviarSMS

• End Point para envío de mensajes SMS certificados
  EnviarSMSCERTIFICADO

• End Point para la consulta de créditos disponibles
  GetCreditos

• Usuario de Mensatek: Este dato es necesario y procede de la información del registro de cuenta en Mensatek y puede consultarse en:
  Tus Datos->Configurar Cuenta->Configuración API

• Token de Mensatek: Este dato es necesario y procede de la información del registro de cuenta en Mensatek y puede consultarse en:
  Tus Datos->Configurar Cuenta->Configuración API

Información del emisor de los mensajes

• Nombre del contacto que envía los mensajes: Se corresponde con el nombre que aparecerá en los dispositivos móviles como remitente.

Registro de mensajes enviados

• Activar el registro de mensajes: Al activar esta opción los mensajes quedan registrados con independencia de si se pudo realizar el envío por parte de Mensatek. Los mensajes se registran de forma estructurada aportando información adicional a la disponible en las herramientas de gestión de Mensatek

Formato de mensajes

• ¿Utilizar Unicode?: Por defecto los mensajes se envían en estándar GSM 3.38 que puede tener limitaciones en la presentación de determinados caracteres (p.e emoticonos). Activando esta opción es posible enviar caracteres fuera del estándar GSM 3.38.

Nota: el uso de unicode incrementa el consumo de créditos de Mensatek.

Automatización del envío de mensajes

• Utilizar la configuración de disparadores: Activando esta opción se habilita el uso de la configuración de disparadores que permite capturar los eventos que producen los distintos objetos del sistema (presupuestos, pedidos, envíos, facturas…). Cuando está activada, se verifica si el evento que se ha producido se encuentra en la configuración y en ese caso se envía un mensaje SMS al cliente con la información del objeto en cuestión.

• Disparadores: Este valor representa la estructura que permite filtrar los distintos eventos del sistema.
  
  Nota: Esta configuración se utiliza para el envío automático de mensajes y como criterio para mostrar el botón de envío en las fichas de los distintos objetos del sistema.
  
  Se trata de una estructura JSON que utiliza la comilla simple como delimitador de campos. La configuración para capturar el evento de validación de un pedido sería la siguiente:

{

'commande': {

'key':'Order',

‘contact_phone’:’123456789’.

‘defaulttimetocancel’: -1,

'triggers':{

'ORDER_VALIDATE':{

'SMS_TYPE':0, 

'timetocancel':240, 

'uselink':0

}

}

}

}

donde:

• commande = nombre del atributo “element” de la clase Commande de Dolibarr

• key = Clave de traducción que devuelve el nombre del objeto. En este caso “pedido”

• contact_phone: Número de teléfono para atención a clientes para objetos de este tipo

• defaulttimetocancel: Tiempo de la política de cambios por defecto. Acepta los siguientes valores:

• No se muestra el mensaje

• =0 => El mensaje especifica que no se admiten modificaciones

• >0 => Número de minutos antes de la entrega en el que se admiten cambios.

• triggers: Nombres de los disparadores de Dolibarr representados como propiedades

• ORDER_VALIDATE: nombre del disparador invocado en la validación de un pedido

• SMS_TYPE: 0 = Masivo, 1 = Certificado

• timetocancel: Tiempo de la política de cambios para el evento que representa el disparador. Este valor sobreescribe el tiempo por defecto. Acepta los siguientes valores:

• =0 => No se muestra el mensaje

• El mensaje especifica que no se admiten modificaciones

• >0 => Número de minutos antes de la entrega en el que se admiten cambios.

• uselink: 0=no, 1=sí. Utilizar enlaces abreviados reduce considerablemente el tamaño de los mensajes que se envían

Modo de pruebas

El modo de pruebas proporciona opciones para verificar el correcto funcionamiento del sistema sin incurrir en las consecuencias del uso.

• Número para pruebas: Si este campo está completo los mensajes SMS siempre se enviarán a este número en lugar de al destinatario

• Modo de pruebas: Permite probar los formatos de los mensajes que se envían sin enviar los mensajes al proveedor de servicios (sin consumir créditos). Los resultados de la composición de mensajes pueden consultarse tanto en los eventos asociados a los distintos objetos, como en la sección de registro de mensajes si se encuentra habilitada.

Una vez completada la información de la configuración del módulo puede verificar el correcto funcionamiento del servicio desde la página de configuración, pulsando sobre el botón “PROBAR”:

Pulsando este botón debe aparecer el siguiente formulario en la parte inferior de la página de configuración:

Nota: Tenga en cuenta que las pruebas consumen créditos del proveedor de servicios.

Estructura de los mensajes

La estructura de los mensajes se define en cinco bloques de información que se componen en base a la meta-información de los objetos del sistema y a su contenido teniendo en cuenta propiedades estándar de los objetos. 

Estos bloques son fijos y serían los siguientes:

Saludo

• Parámetros: Utiliza los valores del nombre del cliente $object->thirdparty->name_alias, y en su defecto $object->thirdparty->nom, y el nombre del remitente establecido en la configuración.

• Claves de traducción: trusting_msg

Ejemplo:

Hola [NOMBRE DEL CLIENTE]. Gracias por confiar en VALOR_EN_CONFIGURACIÓN.

Suceso

Representa el suceso que tiene lugar en el sistema.

• Parámetros: Utiliza el valor “key” de la configuración de disparadores para nombrar el objeto (pedido, factura…), y la referencia del objeto en cuestión ($object->ref)

• Claves de traducción:

• Si el origen del mensaje es un disparador: Se forma la clave “MSG_”+[NOMBRE DEL DISPARADOR]

• Si el origen del mensaje no es un disparador utiliza la clave para el mensaje genérico happening_msg

Ejemplo:

Se ha validado un pedido a su nombre con referencia SO2306-0046.

Contenido de los mensajes

El contenido del mensaje se forma añadiendo los valores de distintas propiedades comunes a los objetos de Dolibarr, y dependiendo de si se estableció el uso de un enlace.

Cuando se establece que el contenido utilice un enlace, el contenido del mensaje se resume en un enlace donde los clientes pueden descargar el documento pdf asociado al objeto en cuestión. El uso de enlaces reduce considerablemente el consumo de caracteres en los mensajes, aunque supone un proceso más complejo para hacer accesible la información a los clientes. Adicionalmente, los servicios de Mensatek permiten trazabilidad sobre si un usuario ha realizado o no la descarga del documento.

.

• Si NO se utiliza un enlace abreviado

• Parámetros:

• Fecha/Hora prevista entrega

• Forma de entrega

• Condiciones de pago

• Forma de pago

• Dirección de entrega:

• Líneas de pedido:

• Cantidad

• Etiqueta del producto

• Precio de venta

• Total de líneas de pedido

• Claves de traducción: details_full, y las propias del contexto de los distintos objetos de Dolibarr

Ejemplo:

- Fecha/Hora prevista entrega: 18/06/2023 14:30

- Forma de entrega: Entrega a domicilio

- Condiciones de pago: A la entrega

- Forma de pago: Tarjeta

- Dirección de entrega:

Calle y número de la dirección de entrega

CÓDIGO_POSTAL CIUDAD

- Líneas de pedido:

(Cant.) PRODUCTO 1 = 9,00 €

(Cant.) PRODUCTO 2 = 10,00 €

(Cant.) PRODUCTO 3 = 9,00 €

(Cant.) PRODUCTO 4 = 9,00 €

Total:37,00 €

• Si se utiliza un enlace abreviado

• Parámetros: Documento vinculado al objeto

• Claves de traducción: details_link

Ejemplo:

You can download all your order details at the following link:

(LINK:2:https://…)

Política de cambios

Establece la ocurrencia de un texto en el mensaje donde se especifica el tiempo en el que se admiten cambios sobre el objeto en cuestión.

Los valores que determinan esta parte del mensaje se establecen en la configuración de los disparadores asociados a cada objeto “defaulttimetocancel” y “timetocancel” respectivamente.

• Parámetros: “defaulttimetocancel” y “timetocancel” establecidos en la configuración de los disparadores.

• Claves de traducción: change_policy

Ejemplo:

Remember if you need to make modifications, you can do it up to 4 hour/s and 30 minutes before the agreed time for delivery.

Número de teléfono para incidencias o cambios

Establece la ocurrencia de un texto en el mensaje donde se especifica el número de teléfono de contacto de la empresa para el cliente. Puede adoptar los valores siguientes:

• Parámetros: Número de teléfono por defecto para atención a clientes

• Vacío (o cero)=> no añade la sección al mensaje, -1 => utiliza el número del usuario que envía el mensaje, Número=> Número a utilizar

• Claves de traducción: contact_phone

Ejemplo:

Teléfono de atención a clientes: [NÚMERO].

Traducciones y adaptación del contenido de los mensajes

Si necesita hacer cambios sobre el contenido de los mensajes o en los literales que aparecen en el módulo se encuentran disponibles en Español e Inglés en la carpeta “langs” del módulo MensatekSMS.

Casos de uso

Consulta de créditos

Es posible consultar en todo momento los créditos disponibles para el envío de mensajes desde dos puntos.

Desde el menú de utilidades

Desde la ficha de una clase configurada

El diálogo de confirmación para el envío de un mensaje muestra los créditos disponibles en el momento en el que se muestra.

Consulta de mensajes enviados

En la lista de eventos asociados a un objeto

Cuando se envía un mensaje SMS, el suceso aparece en la lista de eventos asociados al elemento correspondiente (presupuesto, pedido, factura, envío)... con el mismo comportamiento que en cualquier otra acción del usuario.

En el listado de mensajes enviados

Si se activó la opción de registro de mensajes en la configuración, el envío de cada mensaje crea un registro en el que pueden consultarse los mensajes enviados con distintos criterios.

En las herramientas de gestión de Mensatek

Adicionalmente es posible consultar la actividad de envío de mensajes accediendo con las credenciales de cliente a las herramientas de gestión de Mensatek

Para consultar los mensajes enviados debe navegar por el menú de la izquierda hasta las secciones “SMS Masivos”.y “SMS Certificados”.

La consola de administración de Mensatek es completa, y desde ella podrá realizar cualquier operación de envío de mensajes, así como recargar su saldo de créditos, o consultar cualquier información relacionada con su cuenta de cliente (créditos disponibles, facturas).

También puede acceder a información sobre otros servicios disponibles como:

• SMS Contrato

• Email Certificado

• Contratación online

• Sellado de tiempo

• Llamadas de voz

• Verificación de identidades

.

Si usted está interesado en la integración de Dolibarr con otros servicios de Mensatek no puede enviar un email a [email protected] especificando su necesidad concreta.

Envío manual de mensajes

Además de las capacidades de envío automático, es posible realizar envíos manuales. Los envíos manuales pueden realizarse sobre las clases configuradas en el apartado “disparadores”.

Una clase correctamente configurada en la sección “disparadores”, crea automáticamente un botón llamado “Enviar SMS” en la ficha del objeto que se trate.

Pulsando sobre el botón “Enviar SMS” se abre un cuadro de diálogo con información y distintas opciones para el envío:

Donde es posible especificar:

• El teléfono que aparecerá como teléfono de contacto para el cliente:

• -1: usará el teléfono del usuario que realiza el envío y en su defecto el que se encuentre asociado en la configuración

• 0 o vacío: no se incluirá la sección de contacto en el mensaje

• Número de teléfono que se incluirá en la sección de contacto para el mensaje

• Si el mensaje utilizará un enlace para la descarga del documento asociado en lugar de la información del objeto

• Si el envío será certificado o normal

Adicionalmente se ofrece información de utilidad sobre el número de créditos disponibles antes del envío del mensaje y la extensión estimada del mensaje.

El envío manual de mensajes no se corresponde con un evento del sistema, por lo que en este caso el mensaje se compone con la clave de traducción genérica 

Nota: el uso del estándar Unicode o el envío de mensajes certificados alteran los créditos consumidos para el envío de un mensaje.

Información para desarrolladores

Funcionamiento de los enlaces a documentos

Aunque la opción de añadir un enlace en lugar del texto del mensaje con la información del objeto puede reducir considerablemente el consumo de créditos, funcionalmente supone un proceso menos inmediato para el cliente, puesto que debe descargar el documento y después abrirlo dentro del dispositivo para poder acceder al contenido.

El enlace apunta a un recurso local de la instalación del módulo “sms_download.php” con acceso público. La identificación del documento a descargar se incluye como un parámetro “querystring” de nombre “info”, donde viaja la clase del documento a descargar y el identificador del objeto de la clase. Si el documento no se encuentra generado se genera en el momento de producir la descarga.

Para prevenir accesos no autorizados la identificación del objeto se cifra mediante el mecanismo de cifrado estándar de Dolibarr.

Actualmente sólo se encuentra desarrollada la función de descargas para pedidos de clientes, aunque es posible extenderlo facilmente a otros tipos documentales.

Configuración de una nueva clase

Es posible que se quieran enviar tipos de mensajes distintos en función del objeto del sistema que se trate. La configuración del elemento “disparadores” define las propiedades básicas para el envío de mensajes SMS para un tipo de objeto determinado. 

Pedidos de clientes

1. Establecer la configuración en modo de prueba

2. crear una nueva entrada en formato JSON en la sección de configuración “Disparadores” con la siguiente información:
   
   {

'commande':{

'contact_phone':'123456789',

'key':'Order',

'defaulttimetocancel':240,

'triggers':{

'ORDER_VALIDATE':{

'SMS_TYPE':0,

'timetocancel':240,

'uselink':0

}

}

}

}

3. Acceder a la ficha de un envío cualquiera desde el menú Comercial->Pedidos de clientes->Listado

4. Verificar que en la ficha del envío existe el botón “Enviar SMS”

Expediciones (envíos)

5. Establecer la configuración en modo de prueba

6. Sobre la entrada anterior, añadir un nuevo elemento en formato JSON en la sección de configuración “Disparadores” con la siguiente información:
   
   {

'commande':{

'contact_phone':'123456789',

'key':'Order',

'defaulttimetocancel':240,

'triggers':{

'ORDER_VALIDATE':{

'SMS_TYPE':0,

'timetocancel':240,

'uselink':0

}

}

},

‘shipping’: {

'contact_phone':'123456789',

'key':'Sending',

'defaulttimetocancel':240,

'triggers':{

'SHIPPING_VALIDATE': {

'SMS_TYPE':0,

'timetocancel':240,

'uselink':0

}

}

}

}

7. Acceder a la ficha de un envío cualquiera desde el menú Productos->Envíos->Listado

8. Verificar que en la ficha del envío existe el botón “Enviar SMS”

Anexo I: Descargo de responsabilidad

El módulo MensatekSMS ofrece servicio a empresas reales en los contextos de Dolibarr que se indican, sin que se haya detectado ningún problema o efecto adverso derivado de su instalación o de su uso.

La adquisición del módulo incluye su código fuente, y el autor no se hace responsable de ningún efecto que se pudiera atribuir a su instalación o su uso, ni de ninguna modificación que pudiera realizar con posterioridad quien lo adquiere. Las posibles mejoras introducidas por usuarios terceros deben de ser puestas en conocimiento del autor, tanto en su descripción funcional como el código fuente que las materializa.

La adquisición del módulo no implica el compromiso de mantenimiento por parte del autor. Si bien este se compromete a facilitar el resultado de los trabajos evolutivos realizados sobre el módulo durante un plazo de un año desde el momento de su adquisición. 

Si bien se ofrecen posibilidades de contacto con el autor, esto no implica ninguna obligación de que sean atendidas sugerencias de mejora, o de corrección de problemas, aunque se valorará la posibilidad de llevar a cabo. Las actividades necesarias para la incorporación al producto de correcciones o mejoras se tendrán en cuanta en función de la utilidad en cada caso y de sus costes según el criterio discrecional del autor.

Anexo II: Reconocimientos

Sms icons created by Freepik - Flaticon