Información a Confirmar Antes de Implementar

Para avanzar con la implementación, es necesario confirmar los siguientes puntos:

#	Punto a confirmar	Notas
1	¿Con qué frecuencia se consultará la vista?	Ej: cada 30 minutos, cada 1 hora, tiempo real. Define la frecuencia de ejecución del conector.
2	¿Cuál es el evento a disparar?	El evento debe estar previamente creado en WoowUp.
3	¿Cuál es el identificador principal del usuario?	Puede ser email, documento u otro identificador según la configuración de la cuenta en WoowUp.
4	¿Qué campos se enviarán como metadata del evento?	Cualquier campo adicional de la vista puede incluirse en el objeto metadata.
5	¿El campo de fecha/hora está en UTC o en timezone local?	Necesario para formatear correctamente el datetime del evento.
6	¿Puede haber registros duplicados?	Definir si se ignora el duplicado o se dispara el evento igual.

Flujo de la Integración

Etapa	Componente	Descripción	Responsable
1	Vista SQL	Se exponen los registros a procesar	Integraciones
2	Conector WoowUp	Se detectan registros nuevos y se dispara el evento configurado	WoowUp
3	Automatización	Se detecta el evento y se ejecuta la acción configurada (ej: email transaccional)	WoowUp

Estructura de la Vista

La vista SQL debe exponer como mínimo los siguientes campos:

Campo	Tipo	Descripción
email/document (Obligatorio el ID Hard)	String	Campo que identifica al usuario en WoowUp (email, documento u otro según la cuenta).
datetime	DateTime	Fecha y hora del hecho a registrar. Se mapea al campo datetime del evento.
metadata.campo_metadata_1	String / Number	Campo adicional a enviar como metadata. Puede definirse según el caso de uso.
metadata.campo_metadata_N	String / Number	Se pueden incluir tantos campos de metadata como sea necesario.

ℹ️ Si un registro no contiene el campo identificador del usuario, se omite y no se dispara el evento.

El conector filtra los registros nuevos utilizando el campo createtime con la siguiente lógica:

WHERE createtime >= CURDATE() -- solo registros del día actual
-- o bien, según la frecuencia configurada:
WHERE createtime > '{{ultima_ejecucion}}' -- registros desde la última ejecución

Paso a Paso de Implementación

Paso 1: Creación del evento en WoowUp

El tipo de evento debe existir en la plataforma antes de poder dispararlo. Se crea una única vez mediante la API:


curl -X POST \
https://api.woowup.com/apiv3/events \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
-H 'cache-control: no-cache' \
-d '{
"name": "nombre-del-evento"
}'

ℹ️ El nombre del evento solo acepta caracteres alfanuméricos y guiones ( - ).

¿Donde encuentro mi API_KEY? Podes ver cómo encontrarla haciendo clic acá

Mas información sobre la API de eventos acá

Respuesta esperada:

{
"id": 1234,
"name": "nombre-del-evento",
"createtime": "2024-01-15 10:00:00"
}

Paso 2: Verificación del evento

Se puede confirmar que el evento fue creado correctamente con la siguiente consulta:

curl -X GET \
'https://api.woowup.com/apiv3/events?limit=100&page=0' \
-H 'accept: application/json' \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
-H 'cache-control: no-cache'

Paso 3: Configuración del Conector SQL en WoowUp

Esta tarea deberá planificarse con el equipo de integraciones de Woowup.

Se configura la conexión a la vista SQL con los siguientes parámetros:

Parámetro	Valor
Vista a consultar	A proveer por el equipo de IT
Frecuencia de lectura	Según corresponda
Acción al detectar registro nuevo	Disparar el evento configurado vía API

ℹ️ Si la integración se realiza mediante archivo CSV enviado por SFTP en lugar de conexión SQL directa, referirse a la documentación de integración por CSV

Paso 4: Disparo del evento (POST /user-events)

Por cada registro nuevo detectado en la vista, se ejecuta el siguiente request:

https://api.woowup.com/apiv3/user-events \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
-H 'cache-control: no-cache' \
-d '{
"event": "nombre-del-evento",
"email": "[email protected]",
"document": "12345678",
"datetime": "2024-01-15T14:30:00-03:00",
"metadata": {
"campo_metadata_1": "valor_1",
"campo_metadata_2": "valor_2"
}
}'

⚠️ El campo datetime debe incluir el offset de timezone. Si se envía sin timezone, WoowUp lo interpreta como UTC. Ejemplo para GMT-3: 2024-01-15T14:30:00-03:00

Paso 5: Verificación de eventos disparados

Se pueden consultar los eventos registrados para validar que el disparo fue exitoso:

curl -X GET \
'https://api.woowup.com/apiv3/user-events?event=nombre-del-evento' \
-H 'accept: application/json' \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
-H 'cache-control: no-cache'

Paso 6: Configuración de la Automatización

Este paso debe realizarse en conjunto con su Customer Success.

En el módulo de Automatizaciones de WoowUp, se configura un flujo que se activa al detectarse el evento:

Trigger: Evento = nombre-del-evento
Acción: la que corresponda según el caso de uso (ej: envío de email transaccional, actualización de perfil, etc.)
Los campos enviados en metadata del evento pueden utilizarse dentro de la plantilla de comunicación.

Ejemplos de Uso

Esta integración puede aplicarse a cualquier caso en el que un sistema externo registre un hecho relevante sobre un usuario y se quiera activar una comunicación o automatización en WoowUp a partir de ese momento.

Por ejemplo:

Orden entregada a domicilio
Cuando el sistema logístico registra que un pedido fue entregado en el domicilio del cliente, se dispara el evento ordenEntregada. WoowUp activa automáticamente un email notificando al usuario que su pedido llegó.

Orden lista para retirar en tienda

El cliente compró online con la opción "retiro en tienda". Cuando la sucursal confirma que el producto está disponible, WoowUp avisa al cliente automáticamente.

Garantía extendida por vencer

Este caso anticipa algo que va a pasar: cuando la garantía de un electrodoméstico está por vencer, WoowUp puede avisarle al comprador con anticipación de manera automática.

A continuación se muestra cómo se mapearían los campos de la vista SQL para el caso de uso 'Orden Entregada':

Campo vista SQL	Campo API WoowUp	Valor de ejemplo
email	email	[email protected]
document	document	12345678
datetime	datetime	2024-01-15T14:30:00-03:00
documentNumber	metadata.documentNumber	0001-00012345

¿Qué hacer si el evento no se dispara?

A continuación se describen los casos más frecuentes y cómo verificarlos:

Síntoma	Causa probable	Cómo verificarlo
El evento no aparece en WoowUp	El evento no fue creado previamente en la plataforma	Ejecutar GET /events y confirmar que el nombre coincide exactamente (case sensitive).
Usuario no encontrado	El email o documento no corresponde a ningún usuario existente en WoowUp	Verificar que el usuario exista en la plataforma antes de disparar el evento.
El datetime del evento está desfasado	El campo datetime se envió sin offset de timezone y WoowUp lo interpretó como UTC	Asegurarse de enviar el datetime con el offset correcto. Ej: -03:00 para Argentina.
Se disparan eventos duplicados	La vista no filtra correctamente por createtime o hay registros repetidos	Revisar el filtro aplicado sobre createtime y confirmar que no hay duplicados en la vista.
Parámetros inválidos	El nombre del evento contiene caracteres no permitidos, o falta un campo requerido	Verificar que el nombre del evento solo use alfanuméricos y guiones, y que email o document esté presente.

Integración de eventos por vista SQL