Librerías API

by Raul araya v.2017.04.25

Galactus

Una de las funcionalidades más importantes del conjunto de instrucciones para la conectividad que ofrece la plataforma, es el API Client Library vía WebService

La última versión del ACL se llama GALACTUS esta versión permite que los usuarios técnicos puedan interfasar sus sistemas de manera directa con la Plataforma de Servicios Integrados GreyPhillips.

Antes de empezar es importante tener en cuenta algunos conceptos básicos:

Termino Descripción
PSI Plataforma de Servicios Integrados
Dominio Un dominio es la suma de los datos relacionados a un único cliente final que incluye la base de datos, rutas físicas, servicios y acuerdos particulares
ACL API Client Library
GALACTUS Versión del ACL, esta se puso a disposición de los usuarios a partir de Agosto del 2015
GUID Es un valor representado por un conjunto de números, letras y guiones único que representa algo, en su totalidad, por ejemplo, un contacto, una cuenta, una campaña, etc.
COB Nomenclatura para referirse a Continuidad de Negocios, también relacionada a Fail Over y Servidores Espejo.

Los servicios de la plataforma están separados en dos unidades funcionales, e incluso físicas, las cuales son parte de la arquitectura misma y su propósito es administrar dos ámbitos de información que, aunque funcionan en conjunto, existen como componentes separados, estas dos porciones son: 

  1. La gestión de información funcional, por ejemplo, la información de los contactos, la información relacionada a la reporteria, la gestión de otras aplicaciones de la plataforma que no forman parte de este documento y cualquier otra información funcional o información base pasiva relacionada a conceptos COB.
  2. La gestión operativa de las comunicaciones separadas geográficamente por país/región, según sean estas necesarias, por ejemplo, para los SMS, puede que según el país/región exista infraestructura implementada para lograr los propósitos de envíos locales de SMS.

Un ejemplo de estas dos estructuras es cuando un cliente de Costa Rica tiene su base de datos funcional, es decir, su información de contactos, resultados de las campanas hechas en su base de datos en Canadá, pero se utilizan los servidores de envío de SMS implementados en Costa Rica, ambas bases de datos, son en última instancia parte del mismo ambiente protegido del cliente.

Para los propósitos de este documento, el primer vínculo se usa para el registro del contacto en la base de datos y el segundo vínculo sirve a los propósitos específicos de las comunicaciones, es decir, el registro de los envíos en la PSI, aunque al final toda la información estará sincronizada y resguardada bajo el mismo dominio destinado para el cliente.

Las funciones disponibles son

Operación Donde Función Descripción
Contactos acl.asmx SetContact Permite crear contactos
Subir archivo a la base de datos del dominio communicator.asmx SetUploadFiletoDB Permite subir archivos directamente a la base de datos, se usa cuando se agregan los archivos como adjuntos.
Subir archivo físico communicator.asmx SetUploadFiletoPath Permite subir archivos al servidor dentro del dominio, usualmente para referenciarlos dentro de los mensajes como un vínculo que permita la descarga del archivo.
Mensajes communicator.asmx SetMessage Permite crear los mensajes

La relación entre funciones

La relación que existe entre las funciones es importante, debido a que se han estructurado para lograr el mejor rendimiento en la carga de los datos a la plataforma, por ejemplo, si en determinado escenario debe de enviarse un mismo archivo a todos los destinatarios, con las funciones de carga de archivos el proceso se hace una única vez, luego cuando se genera el envío, solamente debe de referenciarse aquellos archivos que se desea que vayan adjuntos o referenciados como vínculos en los mensajes.

Desde que la plataforma es capaz de enviar no solamente mensajes de correo electrónico, sino también SMS, es importante considerar el uso adecuado de la carga de datos a la plataforma, sabiendo el impacto en la utilización de recursos que conlleva una decisión acertada, por ejemplo, si se desea enviar el mismo archivo a todos los contactos, la mejor de las practicas implicaría, hacer la subida del mismo una única vez y luego solamente referenciarlo en la función de envío.

Bases para la utilización del ACL

Toda conexión que se haga a la plataforma debe pasar por las validaciones de seguridad que han sido dispuestas para asegurar que únicamente personas y sistemas autorizados son los que estén tratando de operar dentro de los límites de la plataforma.

Cada cliente final tiene una base de datos independiente dentro de la plataforma, esto con el fin de cumplir con los requerimientos de seguridad que solicitan los estándares de manejo de confidencialidad de la información, haciendo una separación lógica y física de la información, por tal motivo cada cliente final de la plataforma tendrá asignada una llave única de identificación para ese dominio particular.

Usted como programador de la plataforma deberá conocer la llave de identificación que le es asignada para uso de los Web Services, esta llave de identificación es asignada por base de datos, así que no es posible utilizar una llave de identificación de la base de datos para hacer la conexión con otra base de datos distinta.

La llave de identificación necesaria en todas las funcionales del ACL le será entregada por separado para cada base de datos y estas se asignan a cada base de datos en el momento de su creación, la misma puede ser cambiada si existieran sospechas de que la misma está siendo usada sin autorización, por medio de una solicitud al departamento de soporte.

Esta llave corresponde a un dato alfanumérico de 36 caracteres, conocida como GUID o Global Unique Identifier, lo cual la hace virtualmente irrepetible si se genera usando medios electrónicos, excluyendo el evidente copiado y la asignación directa.

Todas las funciones adicionalmente requieren de un usuario y contraseña establecida dentro de cada base de datos, es decir, antes de poder utilizarse las funciones del ACL, usted debe de crear un usuario que quiera que sea el autorizado, para tal interconectividad, en caso de que se quiera más información acerca de cómo crear estos usuarios, puede referirse al Panel de Control de la plataforma y al manual de administración de usuarios.

Una vez que tiene en su poder, tanto la llave de identificación como el usuario y contraseña que se le haya asignado, está listo para integrar el ACL a sus propios proyectos.

Descripción de las funciones

setContact
Campo Descripción Adicionales Obligatoria
strApiKey Llave de identificación del dominio Única por cada dominio Obligatoria
strApiUser Usuario Creado en la plataforma Obligatoria
strApiPassword Contraseña Obligatoria
strContactID Identificación del contacto
strName Nombre
strEmail Correo
strPhone Teléfono
strAddress Dirección
intBirthdayDay Día de cumpleaños
intBirthdayMonth Mes de cumpleaños
intBirthdayYear Año de cumpleaños
intInactive Indicador de Inactivo
strCategoryID Identificador de la categoría a la cual pertenece el contacto Estas pueden ser ninguna, una o más, separando por comas cada identificador
setUploadFileToDB
Campo Descripción Adicionales Obligatoria
strApiKey Llave de identificación del dominio Obligatoria
strApiUser Usuario Obligatoria
strApiPassword Contraseña Obligatoria
strFileName Nombre del archivo
bBuffer
lngOffset
intOverwrite
setUploadFileToPath
Campo Descripción Adicionales Obligatoria
strApiKey Llave de identificación del dominio Obligatoria
strApiUser Usuario Obligatoria
strApiPassword Contraseña Obligatoria
strToVirtualFolder

En caso de que se deje en blanco, el file queda en la carpeta default del dominio.

El valor se puede pasar como:“/Imágenes/Mercadeo”

strFileName
bBuffer
lngOffset
intOverwrite
setMessage
Campo Descripción Adicionales Obligatoria
strApiKey Llave de identificación del dominio Obligatoria
strApiUser Usuario Obligatoria
strApiPassword Contraseña Obligatoria
strType

Los valores posibles son:

  • SMS
  • EMAIL
strSubType

Cuando se usa strType EMAIL:

  • NONE

Cuando se usa strType SMS:

  • NONE
  • ALERT
strDatetime

Esta fecha debe dársele en formato de texto universal para fechas, que se construye como

YYYYMMDD HHmmss

  • 4 Dígitos para el año
  • 2 Dígitos para el mes
  • 2 Dígitos para el día
  • 1 Espacio en blanco
  • 2 Dígitos para la hora usando formato de 24 horas, por ejemplo 17 para las 5:00 PM
  • 2 Dígitos para los minutos
  • 2 Dígitos para los segundos
strTo

Este valor corresponde a la cuenta de correo o el número de teléfono celular según sea el caso indicado en strType.

Para el caso de envíos de correos electrónicos, este valor debe corresponder a los estándares relacionados a la estructura correcta en las cuentas de correo, para el caso de los números de teléfono, este debe corresponder a la estructura de país y numero, por ejemplo, 50660591516, es decir, Costa Rica, al número 60591516

strSubject
strMessage
intPriority La prioridad se define únicamente con 2 valores, 0 para prioridad normal 1 para alta prioridad.
strContactID
strAttachFilesIDs Estos son los valores generados en la función SetUploadFiletoDB, solo los valores generados de esta función son válidos.
strCampaignID Este valor es el identificador relacionado a la campana, es decir, al conjunto de mensajes que deseen agruparse, este valor se obtiene desde la interface de la plataforma, corresponde a un GUID.
strSMTPAccountID Este valor es la llave de identificación de la cuenta que desea usarse para hacer el envío, estas cuentas se crean en el panel de control de la PSI.
strFromAppID Este valor sirve para indicar el aplicativo que está haciendo el registro del mensaje, es de libre asignación y no debe superar los 36 caracteres de longitud.
strTableRef
strRefID

La descripción de escenarios sirve para ejemplificar diferentes situaciones a las que pueden estar expuestos los programadores al momento de hacer la integración con la PSI.

Ejemplo de integración de las funciones del ACL:

  • Escenario de Envío de SMS 
  • Escenario de Envío de Correo Electrónico

Escenario de Envío de SMS

En este primer escenario de envío, que es probablemente el escenario más simple de todos, el ejemplo se centra en hacer un envío sencillo de un SMS a un usuario.

Lo primero que hay que definir es si se desea registro de envíos relacionados al contacto, que puede ser consultado dentro de la plataforma, es decir, todos los envíos que se hagan asociándolos a contactos específicos, pueden ser consultados posteriormente en asociación con la información del contacto, también es posible hacer los envíos sin que tengan ninguna asociación a ningún contacto, esto por supuesto, dependerá del objetivo de los envíos que tenga la organización.

En caso de que se desee hacer envíos sin hacer la asociación con el contacto, por favor pase al siguiente paso de este escenario.

Paso 1:

Agregar o actualizar el contacto, al que se le va a hacer el envío, este paso es previo a hacer el envío propiamente, ya que la plataforma permite llevar registro de los contactos con gran detalle y además todos los envíos quedan asociados a estos contactos siempre que así se establezca por parte del programador.

Para agregar un contacto lo primero que se hace es usar la función SetContact descrita más arriba.

SetContact (‘Llave’,’User1’,’Pass123’,’1893682’,Percival Wallace’,’email@corporacion.com’,’50660591516’,’WA, 123 Well Street’,23,9,0,0,’’)

Con este ejemplo agregaremos a la base de datos DEMO, la cual tiene la llave de identificación única: ‘Llave’, usando el usuario ‘User1’ que tiene una contraseña ‘Pass123’, al contacto, cuyo Id seria ‘1893682’, su nombre seria ‘Percival Wallace’ el cual tiene el correo ‘email@corporacion.com’ y vive en WA, 123 Well Street, cuya fecha de nacimiento es el 23 de septiembre, pero del cual no conocemos el año; además 0 o 1 para indicar si debe quedar inactivo=1 y por último el ID de la categoría, si se desea, la cual se agrega el contacto, de lo contrario vacío.

Se hace esto con todos los contactos que deseemos agregar o actualizar en la base de datos, este paso es totalmente opcional y corresponde al criterio que cada organización tenga.

Una vez que el contacto está en la base de datos, procedemos a agregar por medio de la instrucción de envío el mensaje que deseamos.

Paso 2:

Procedemos entonces a usar la instrucción SetMessage.

SetMessage (‘Llave’,’User1’,’Pass123’,’SMS’,’NONE’,’20150923 140000’,’50660561516’,’’,’En este día tan especial deseamos darle nuestras felicitaciones por su cumpleaños’,0,’1893682’,’’,’’,’’,’AppMercadeo’)

Para los propósitos del ejemplo, estamos agregando un mensaje en la base de datos DEMO, la cual tiene la llave de identificación única para tal base de datos, ‘Llave’, usando el usuario ‘User1’ con contraseña ‘Pass123’, indicando que se trata de un mensaje de texto normal, ya que se indicó en strType el valor ‘SMS’ y en strSubType ‘NONE’, el mensaje se enviara el 23 de setiembre del 2015 a las 2:00PM, el mensaje se enviara al 506 60591516, con el texto “En este día tan especial deseamos darle nuestras felicitaciones por su cumpleaños”, para el caso de los envíos de SMS el texto que va en el campo strSubject se usa para seguimiento y reportería (puede ser igual al mensaje pero no debe exceder los 255 caracteres a diferencia del mensaje), la prioridad se establece como normal al usar el valor 0 y se va a asociar el mensaje al contacto de la base de datos que tenga el Id. 1893682 (opcional), los siguientes campos en el ejemplo se dejan en blanco, ya que no lleva files adjuntos, no se está asociando a una campana en específico, no se está usando una cuenta SMTP por ser mensajes de texto, el ultimo valor sirve como información de referencia para saber que aplicativo ejecuto esta instrucción, lo que resulta útil para casos donde hay diversas aplicaciones como, por ejemplo, el sistema de cobros, los sistemas de operaciones, transporte y otros.

Ejemplo PHP

http://php.greyphillips.com/GPWebServiceSample/