Integración personalizada para recibir datos desde sistemas externos

En Connectif es posible recibir datos desde sistemas externos para hacer uso de información que no es registrada por defecto en la plataforma. Mediante una integración personalizada, podrás sincronizar los datos de tus contactos en función de eventos generados en otras plataformas.

En este artículo, se explica cuáles son los tipos de integración personalizada para recibir datos y cómo crear un evento de este tipo, con un ejemplo de integración con el ERP.

1. Propiedades

Eventos de recepción de datos

• Los eventos de recepción de datos son una potente herramienta  para ampliar y personalizar Connectif según tus propios casos de uso.

• Al crear un nuevo evento de recepción, deberás indicar el contexto: 

  • API pública.

  • Webhook.

  • Web o App móvil.
     

Evento de recepción mediante API pública

Los eventos de recepción mediante API pública son el mecanismo más seguro, ya que requieren de una Clave API. Están diseñados para que los eventos se envíen desde tu servidor a Connectif.

Características y límites:

• El tamaño máximo de un evento es de 512KB.

• Es obligatorio definir un campo email requerido y clave primaria para identificar al contacto.

• Es posible indicar mediante el query string createContact si crear o dar error cuando el contacto al cual pertenece el evento no existe.

• El nodo disparador del workflow generado por un evento de recepción mediante API pública no tendrá contexto web.

• Requieren de validación estricta y no permiten enviar campos que no estén definidos en el evento.

Evento de recepción mediante Webhooks

Los eventos de recepción mediante Webhook son un mecanismo más flexible,  ideales para cuando no se controla el emisor de los datos, por ejemplo utilizar un webhook de una herramienta externa donde no puedo cambiar el formato de los datos emitido o no donde no es posible establecer una cabecera de seguridad con clave API.

Características y límites:

• El tamaño máximo de un evento es de 512KB.

• Es obligatorio definir un campo email requerido y clave primaria para identificar al contacto.

• Siempre crean el contacto en Connectif si no existe.
• Permiten definir JSON Pointer para mapear campos a estructuras complejas. Ideal cuando la información del evento se encuentra en objetos complejos y anidados.
• No dan error de validación en caso de campos desconocidos. De este modo permite mapear solo los campos que nos interesan obviando otros que serán simplemente ignorados.

• El nodo disparador del worfkflow generado por un evento de recepción mediante Webhook no tendrá contexto web.

Evento de recepción mediante Web o App móvil

Los eventos de recepción mediante Web o App móvil permiten enviar eventos directamente desde el lado cliente de tu web o desde tu app móvil. Para ello es necesario utilizar respectivamente el SDK Web o SDK Mobile.

Características y límites:

• Los eventos mediante Web o App no requieren de un campo email obligatorio y clave primaria. Pueden, por lo tanto, enviarse para contactos anónimos o conocidos durante el tracking web o de tu app móvil.

• El nodo disparador del worfkflow generado por un evento de recepción mediante Web o App móvil tendrá contexto web. Tras este nodo es posible utilizar el nodo Mostrar contenido web.
   

2. Cómo funciona la creación de un evento de recepción de datos en Connectif

El proceso de creación de un evento de recepción de datos consta de unos pasos a seguir, independientemente del mecanismo escogido. 

A modo ejemplo, a continuación se muestra cómo sería la creación de un evento de recepción de datos para conectar un ERP con Connectif:

2.1. Creación de la integración personalizada

1. Accede a "Integraciones > Personalizadas" y haz clic sobre  Crear nueva integración.

2. Establece el campo "Nombre" para identificar la integración.

3. (Opcional) Personaliza el color, incluye una descripción o categoriza la integración.

4. Haz clic en  Actualizar.

2.2 Creación y configuración del evento "Recibir Datos"

(En este apartado se va a crear el evento de recepción y a configurar los campos donde se van a almacenar los datos recibidos).

5. En la pestaña Recibir datos, haz clic en  Crear nuevo evento de recepción.

6. En la ventana emergente, escoge el tipo de conexión para el evento y haz clic en Ir al editor. En nuestro ejemplo, vía API pública.

7. Asigna un Nombre y un Alias al evento.

8. Haz clic en   Añadir un nuevo campo para crear un campo de tipo Email, para recoger el correo electrónico del contacto. 

9. Repite la acción indicada en el punto anterior tantas veces como datos quieras recibir. 

10. Haz clic en  Guardar y, en la pantalla de confirmación, haz clic en  Volver al listado de eventos.

2.3. Creación de la Clave API para habilitar la recepción de datos

(En este apartado, se explica cómo generar la dirección para notificar el tipo de evento creado, el endpoint).

10. Dirígete a "Ajustes de tienda > API y accesos IP" y, en Claves API, haz clic en   Crear nueva clave API.

11. En el apartado Eventos personalizados, activa el permiso para Escribir.

12. Guarda la clave API y, en el menú de Claves API, localiza la que acabas de crear y haz clic en el botón para copiarla (señalado en la imagen).

13. Utiliza la clave API para realizar la petición de envío del evento desde tu sistema. 

2.4. Obtención del endpoint de notificación

(En este apartado, se explica cómo generar la dirección para notificar el tipo de evento creado, el endpoint).

14. En la pestaña Recibir datos, haz clic en  Editar.

15. Haz clic en  Copiar URL para recoger en el portapapeles la dirección del endpoint.

2.5. Envío de datos a Connectif

(En este apartado se explica cómo establecer la comunicación con el endpoint y enviar datos).

16. En tu código, pega esta URL junto a la Clave API y el cuerpo de la petición para generar el evento de recepción. En caso de eventos vía Webhook o Web/App, no necesitarás usar la Clave API.

17. Realiza la llamada al endpoint para notificarle los datos del evento.

2.5.1 Ejemplo de envío de datos mediante Postman (Webhook)

Una vez configurado el evento de recepción en Connectif, es posible realizar pruebas de envío de datos utilizando Postman para verificar que la información se recibe correctamente.

Configurar la petición

1. Abre Postman y crea una nueva petición.
2. Selecciona el método POST.
3. Introduce como URL el endpoint generado para el evento de recepción.

Ejemplo:

https://webhook-api.connectif.cloud/{store-id}/custom-events/alias/webhook-event-example

Configurar los encabezados (Headers)

Añade los encabezados necesarios para el envío de datos:

Configurar el cuerpo de la petición (Body)

Selecciona Body > raw > JSON e introduce un payload acorde a los campos definidos en el evento.

Ejemplo:

{
    "email": "john.doe@example.org",
    "phone": "+34666777888",
    "name": "Hi there!"
}

Enviar la petición

Haz clic en Send para realizar la solicitud.

Si la petición se procesa correctamente, el evento será recibido por Connectif y podrá utilizarse en workflows, segmentaciones o procesos de automatización.

Se recomienda verificar la recepción del evento mediante un workflow de prueba o revisando la actividad del contacto asociado a los datos enviados.

Resultado:

La siguiente imagen muestra un ejemplo de una petición realizada correctamente desde Postman y la respuesta devuelta por Connectif.

2.5.2 Ejemplo de envío de datos mediante Postman (API)

Una vez configurado el evento de recepción y creada la API Key, es posible utilizar Postman para comprobar que Connectif recibe correctamente los datos enviados.

Configurar la petición

1. Abre Postman y crea una nueva petición.
2. Selecciona el método HTTP indicado en la documentación del endpoint que vayas a utilizar.
3. Introduce la URL correspondiente al endpoint de la API.

Ejemplo:

https://api.connectif.cloud/custom-events/alias/api-event-example?createContact=true

Configurar los encabezados (Headers)

Añade las credenciales requeridas por el endpoint mediante los encabezados correspondientes.

Sustituye {api_key} por la Key Secret correspondiente.

 Configurar el cuerpo de la petición (Body)

Selecciona Body > raw > JSON e introduce un payload acorde a los campos definidos en el evento.

Ejemplo:

{ 
    "email": "john.doe@example.org", 
    "name": "Hi there!", 
    "phone": "+34666777888" 
}

Enviar la petición

Haz clic en Send para realizar la solicitud.

Si la petición se ha procesado correctamente, la API devolverá una respuesta satisfactoria y los datos quedarán registrados en Connectif según la funcionalidad utilizada.

Resultado:

La siguiente imagen muestra un ejemplo de una petición realizada correctamente mediante API pública utilizando una Clave API con permisos de escritura para eventos personalizados.

2.6. Sincronización de los datos con la información del contacto

(En este apartado se explica cómo sincronizar los datos en Connectif a través de un workflow).

18. Accede a “Workflows”, haz clic en  Crear nuevo workflow y selecciona Crear workflow en blanco.

19. Crea la estructura de tu workflow con el nodo de tipo disparador “Disparador [nombre de tu integración]” y el nodo de tipo acción “Establecer campo”.

20. En el nodo “Disparador Recibir datos de…”, haz clic en  (Editar configuración del nodo).

21. Comprueba que los datos que recoge el nodo "Disparador Recibir datos de...", provenientes del evento en el sistema externo, son los adecuados.

22. Haz clic en  Guardar.

23. En el nodo “Establecer campo”, haz clic en  (Editar configuración del nodo).

24. Relaciona las variables para asignar la información que recoge la integración personalizada a los campos de contacto que correspondan.

25. Haz clic en  Actualizar.

26. En el workflow, haz clic en  Guardar para guardar los cambios y en  Iniciar para activarlo.

2.7. Creación de un Segmento Dinámico Plus de la integración

Con Connectif, podrás crear un Segmento Dinámico Plus para filtrar por las actividades y campos relacionados con las integración personalizada.

Una vez crees un segmento de contactos de la integración personalizada, esta no podrá eliminarse. Además, si alguno de sus campos se está usando como condición de segmentación, tampoco podrá borrarse ni editarse. 

¡Sigue aprendiendo!

Para aprovechar todo el potencial de tu cuenta en Connectif, te recomendamos continuar con los siguientes artículos:

• Integración personalizada para enviar datos, para mandar datos desde Connectif a sistemas o aplicaciones externos.

• Detectar y reaccionar a enlaces web creados fuera de Connectif, para identificar y dar respuesta a los clics en cualquier enlace de tu web.

• Integración con Facebook e Instagram, para gestionar las audiencias de tu cuenta de Facebook Ads con Connectif.

• Formularios integrados, para detectar y recoger en Connectif formularios ya existentes en tu web.