Integraciones salientes

🔗 Integraciones Salientes

Conecta tus eventos de LoyaltyTree a plataformas externas de marketing, automatización y análisis. Envía datos en tiempo real sobre la actividad del cliente para potenciar campañas de correo electrónico, segmentos de clientes, automatizaciones y más.

Plataformas Soportadas

LoyaltyTree admite el envío de eventos a las siguientes plataformas:

Plataforma	Tipo	Lo Que Necesitas
Klaviyo	Marketing por Email/SMS	Tu Clave API Privada de Klaviyo
Omnisend	Marketing por Email/SMS	Tu Clave API de Omnisend
Shopify Flow	Automatización de Shopify	Un Manejador de Disparador de Flow (creado en Shopify Flow)
Webhook Genérico	Cualquier Endpoint HTTP	Una URL de webhook que acepte solicitudes POST

Comenzando

Paso 1: Navega a Integraciones

Ve a Tiendas → [Tu Tienda] → Integraciones → Webhooks Salientes en tu panel de administración.

Paso 2: Agrega una Nueva Integración

Haz clic en el botón + Agregar Integración. Selecciona tu plataforma, dale un nombre y elige qué eventos enviar.

Paso 3: Ingresa Tus Credenciales

Dependiendo de la plataforma, necesitarás proporcionar una clave API, URL de webhook o manejador de disparador. Todos los datos sensibles están encriptados antes de ser almacenados.

Paso 4: Prueba la Conexión

Usa el botón Probar en tu tarjeta de integración para enviar un evento de prueba y verificar que todo esté conectado correctamente.

Eventos Soportados (19 en Total)

Puedes suscribir cada integración a cualquier combinación de estos eventos. Solo los eventos que selecciones serán enviados a esa plataforma.

🌱 Eventos de Semillas Ganadas

Se activa cuando un cliente gana semillas a través de diversas actividades.

Evento	Clave del Evento	Se Activa Cuando
Semillas – Ganadas – Pedido	`seeds.earned.order`	El cliente gana semillas de una compra
Semillas – Ganadas – Visita	`seeds.earned.visit`	El cliente gana semillas al visitar la tienda
Semillas – Ganadas – Reseña	`seeds.earned.review`	El cliente gana semillas al escribir una reseña
Semillas – Ganadas – Referido	`seeds.earned.referral`	El cliente gana semillas de un referido exitoso
Semillas – Ganadas – Compartir en Redes Sociales	`seeds.earned.social_share`	El cliente gana semillas al compartir en redes sociales
Semillas – Ganadas – Bonificación	`seeds.earned.bonus`	El cliente recibe semillas de bonificación (cumpleaños, premio manual, etc.)

⭐ Eventos de Nivel & Reseña

Evento	Clave del Evento	Se Activa Cuando
Nivel – Cambiado	`tier.changed`	El cliente se mueve a un nivel de lealtad diferente
Reseña – Enviada	`review.submitted`	El cliente envía una nueva reseña de producto
Reseña – Aprobada	`review.approved`	Una reseña de producto es aprobada (por IA o manualmente)
Reseña – Rechazada	`review.rejected`	Una reseña de producto es rechazada

🎁 Eventos de Recompensa

Evento	Clave del Evento	Se Activa Cuando
Tarjeta de Regalo – Ganada	`gift_card.earned`	El cliente califica para una recompensa de tarjeta de regalo
Tarjeta de Regalo – Reclamada	`gift_card.claimed`	El cliente reclama su tarjeta de regalo
Crédito de Tienda – Ganado	`store_credit.earned`	El cliente califica para crédito de tienda
Crédito de Tienda – Reclamada	`store_credit.claimed`	El cliente reclama su crédito de tienda

🌳 Eventos Ecológicos & de Referido

Evento	Clave del Evento	Se Activa Cuando
Producto Ecológico – Otorgado	`eco_product.awarded`	El cliente canjea semillas por un producto ecológico
Ecológico – Árbol Plantado	`eco.tree_planted`	Se planta un árbol para el cliente
Referido – Generado	`referral.generated`	El cliente genera un enlace de referido
Referido – Visita	`referral.visit`	Alguien visita la tienda a través de un enlace de referido
Referido – Exitoso	`referral.successful`	Un visitante referido realiza una compra

Guías de Configuración de Plataforma

📧 Klaviyo

Klaviyo es una plataforma de marketing por correo electrónico y SMS popular entre las tiendas de Shopify. LoyaltyTree envía eventos a Klaviyo utilizando su API de Eventos (v3), para que puedas construir segmentos, flujos y campañas basadas en la actividad de lealtad.

Configuración:

En Klaviyo, ve a Configuraciones → Claves API y crea una Clave API Privada
En LoyaltyTree, haz clic en + Agregar Integración, selecciona Klaviyo
Pega tu Clave API Privada
Selecciona qué eventos enviar
Haz clic en Guardar Integración

Cómo funciona: LoyaltyTree crea eventos de Klaviyo con el correo electrónico del cliente como identificador de perfil. Los eventos aparecen como métricas personalizadas (por ejemplo, "Semillas Ganadas Pedido", "Nivel Cambiado") que puedes usar en flujos y segmentos de Klaviyo. Las cantidades de semillas se envían como el valor del evento, para que puedas usarlas en divisiones condicionales.

📨 Omnisend

Omnisend es otra plataforma popular de marketing por correo electrónico y SMS. LoyaltyTree envía eventos utilizando la API de Eventos de Omnisend (v5).

Configuración:

En Omnisend, ve a Configuraciones → Claves API y genera una clave
En LoyaltyTree, haz clic en + Agregar Integración, selecciona Omnisend
Pega tu Clave API
Selecciona qué eventos enviar
Haz clic en Guardar Integración

Cómo funciona: Los eventos se envían con el correo electrónico, nombre e ID de cliente de Shopify del cliente. Cada evento incluye todas las propiedades relevantes (cantidades de semillas, detalles del pedido, información del nivel, etc.) para que puedas usarlas en flujos de automatización y segmentación de Omnisend.

⚡ Shopify Flow

Shopify Flow es la herramienta de automatización integrada de Shopify. LoyaltyTree envía eventos directamente a Shopify Flow utilizando la mutación flowTriggerReceive de GraphQL, lo que significa que los eventos aparecen como disparadores dentro de tus flujos de Flow — no se necesitan aplicaciones de terceros.

⚠️ Importante: Shopify Flow está disponible en el plan Básico de Shopify y superior. Necesitas tener instalada la aplicación Shopify Flow en tu tienda.

Configuración:

En tu administración de Shopify, ve a Flow y crea un nuevo flujo de trabajo
Agrega un disparador — usa el manejador de disparador de la aplicación LoyaltyTree
En LoyaltyTree, haz clic en + Agregar Integración, selecciona Shopify Flow
Ingresa el Manejador de Disparador de Flow que coincide con tu disparador de Shopify Flow
Selecciona qué eventos enviar
Haz clic en Guardar Integración

Cómo funciona: Cuando ocurre un evento suscrito, LoyaltyTree utiliza la conexión API de Shopify de tu tienda para enviar los datos del evento directamente a Shopify Flow a través de GraphQL. La carga útil se aplana en claves legibles por humanos como "Correo electrónico del cliente", "Tipo de evento", "Cantidad", etc. Luego puedes usar estos valores como condiciones en tu Flow para activar acciones como enviar correos electrónicos, etiquetar clientes o crear tareas.

Ejemplos de automatizaciones de Shopify Flow:

Etiquetar clientes cuando alcancen el nivel Oro
Enviar una notificación interna de Slack cuando se planta un árbol
Crear una tarea cuando se envía una reseña
Agregar una nota al perfil del cliente cuando ganen una tarjeta de regalo

🌐 Webhook Genérico

Envía eventos de LoyaltyTree a cualquier endpoint HTTP. Esto es perfecto para conectar con sistemas personalizados, Zapier, Make (Integromat), n8n, o cualquier otra plataforma que acepte POSTs de webhook.

Configuración:

Obtén la URL de tu endpoint de webhook de tu plataforma receptora
En LoyaltyTree, haz clic en + Agregar Integración, selecciona Webhook Genérico
Ingresa la URL del Webhook
(Opcional) Elige un método de autenticación y agrega credenciales
(Opcional) Agrega un secreto de webhook para la verificación de firma HMAC
Selecciona qué eventos enviar
Haz clic en Guardar Integración

Opciones de Autenticación:

Método	Encabezado Enviado	Descripción
Firma HMAC	`X-LoyaltyTree-Signature`	SHA-256 HMAC del cuerpo de la carga útil, firmado con tu secreto de webhook
Token Bearer	`Authorization: Bearer <token>`	Autenticación estándar de token bearer estilo OAuth
X-Token	`X-Token: <token>`	Token simple en un encabezado personalizado
Encabezado Personalizado	`<tu-encabezado>: <token>`	Especifica tu propio nombre de encabezado y valor de token

Plantillas de Carga Útil Personalizadas: Para Webhooks Genéricos, puedes personalizar el formato de la carga útil para cada evento utilizando variables de plantilla. Esto te permite igualar el formato exacto que tu sistema receptor espera.

Encabezados estándar enviados con cada solicitud:

Content-Type: application/json
User-Agent: LoyaltyTree/1.0
X-LoyaltyTree-Event: <event_type>
X-LoyaltyTree-Timestamp: <ISO timestamp>

Ejemplo de Carga Útil de Webhook

A continuación se muestra cómo se ve un evento típico seeds.earned.order cuando se entrega a un Webhook Genérico:

{
  "event": "seeds.earned.order",
  "timestamp": "2026-02-06T14:30:00.000Z",
  "customer": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "display_name": "Jane Smith",
    "shopify_customer_id": "7891234567890"
  },
  "amount": 50,
  "order_id": "6012345678901",
  "order_number": "1042",
  "order_total": "89.99",
  "order_currency": "USD",
  "balance": 350,
  "tier": "Silver"
}

Cada carga útil de evento incluye el objeto customer con su correo electrónico, nombre e ID de cliente de Shopify, además de campos de datos específicos del evento.

Referencia de Datos de Eventos

A continuación se muestra una lista detallada de los campos de datos incluidos con cada tipo de evento.

🌱 seeds.earned.order

amount – Número de semillas ganadas
order_id – ID del pedido de Shopify
order_number – Número de pedido legible por humanos
order_total – Monto total del pedido
order_currency – Código de moneda (por ejemplo, USD)
balance – Nuevo saldo de semillas del cliente
tier – Nombre del nivel actual del cliente

👁️ seeds.earned.visit

amount – Número de semillas ganadas
visit_number – Qué visita fue esta
balance – Nuevo saldo de semillas del cliente
tier – Nombre del nivel actual del cliente

✍️ seeds.earned.review

amount – Número de semillas ganadas
product – Objeto con id y title del producto
rating – Calificación en estrellas (1-5)
has_photos – Si la reseña incluye fotos
platform – Plataforma de reseña (por ejemplo, "loyaltytree")
balance – Nuevo saldo de semillas del cliente
tier – Nombre del nivel actual del cliente

🤝 seeds.earned.referral

amount – Número de semillas ganadas
referral_type – Tipo de referido (por ejemplo, "referral_purchase")
referred_customer – Objeto con la información del cliente referido
balance – Nuevo saldo de semillas del cliente
tier – Nombre del nivel actual del cliente

📱 seeds.earned.social_share

amount – Número de semillas ganadas
platform – Plataforma social utilizada (por ejemplo, "twitter", "facebook")
share_url – La URL que se compartió
balance – Nuevo saldo de semillas del cliente
tier – Nombre del nivel actual del cliente

🎉 seeds.earned.bonus

amount – Número de semillas ganadas
reason – Razón de la bonificación (por ejemplo, "Bonificación de cumpleaños")
balance – Nuevo saldo de semillas del cliente
tier – Nombre del nivel actual del cliente

📊 tier.changed

old_tier – Nombre del nivel anterior
new_tier – Nuevo nombre del nivel
total_seeds – Total de semillas de por vida del cliente

📝 review.submitted

review_id – Identificador único de la reseña
product – Objeto con id y title del producto
rating – Calificación en estrellas (1-5)
title – Título de la reseña
body – Texto del cuerpo de la reseña
photos – Array de URLs de fotos
has_photo – Si la reseña tiene fotos

✅ review.approved

review_id – Identificador único de la reseña
product – Objeto con id y title del producto
rating – Calificación en estrellas (1-5)
title – Título de la reseña
body – Texto del cuerpo de la reseña
photos – Array de URLs de fotos
seeds_awarded – Semillas otorgadas por esta reseña

❌ review.rejected

review_id – Identificador único de la reseña
product – Objeto con id y title del producto
rating – Calificación en estrellas (1-5)
rejection_reason – Por qué se rechazó la reseña

🎁 gift_card.earned

amount – Valor monetario de la tarjeta de regalo
currency – Código de moneda
seeds_redeemed – Semillas gastadas para ganar esto
tier – Nivel actual del cliente

💳 gift_card.claimed

amount – Valor monetario de la tarjeta de regalo
currency – Código de moneda
code – El código de la tarjeta de regalo

💰 store_credit.earned & store_credit.claimed

amount – Valor monetario del crédito de tienda
currency – Código de moneda
seeds_redeemed – Semillas gastadas (solo evento ganado)
tier – Nivel actual del cliente (solo evento ganado)

🌳 eco_product.awarded

eco_product_name – Nombre del producto ecológico
eco_product_type – Tipo (por ejemplo, "árbol", "coral")
seeds_spent – Semillas gastadas en este producto

🌲 eco.tree_planted

trees_count – Número de árboles plantados
project_name – Nombre del proyecto de reforestación
certificate_url – Enlace al certificado de plantación

🔗 referral.generated, referral.visit & referral.successful

referral_code – Código de referido único (solo generado)
share_url – URL de referido (solo generado)
visitor_id – ID de visitante anónimo (solo visita)
seeds_awarded – Semillas ganadas (visita & exitoso)
referred_customer – Información sobre el nuevo cliente (solo exitoso)
order_total – Total del pedido del cliente referido (solo exitoso)

Confiabilidad & Lógica de Reintento

LoyaltyTree utiliza una cola asíncrona para garantizar la entrega confiable de eventos. Los eventos nunca se pierden — si la entrega falla, el sistema reintenta automáticamente con retroceso exponencial.

Intento de Reintento	Tiempo de Espera
1er reintento	1 minuto
2do reintento	5 minutos
3er reintento	30 minutos
4to reintento	2 horas
5to reintento (final)	24 horas

Después de que se agoten todos los reintentos, el evento se marca como "agotado" y aparece en tus Registros de Eventos con un botón de Reintentar para que puedas reintentarlo manualmente en cualquier momento.

Registros de Eventos

Cada entrega de evento se registra y es visible en la sección de Registros de Eventos en la página de Integraciones. Puedes filtrar los registros por:

Conexión – Ver eventos para una integración específica
Evento – Filtrar por tipo de evento
Cliente – Buscar por correo electrónico o nombre del cliente
Rango de Fechas – Ver eventos de un período de tiempo específico

Cada entrada de registro muestra la hora, plataforma, tipo de evento, estado y cualquier mensaje de error. Los eventos fallidos incluyen un botón de Reintentar para volver a ponerlos en cola de inmediato.

Solución de Problemas

Los eventos muestran estado "fallido"

Verifica el mensaje de error en los Registros de Eventos. Causas comunes:

No se pudo conectar – La URL del webhook puede estar caída o ser incorrecta
Error 401/403 – Tu clave API o token de autenticación pueden ser inválidos
Tiempo de espera – El servidor receptor es demasiado lento para responder (tiempo de espera de 10 segundos)

Eventos no aparecen en Klaviyo/Omnisend

Asegúrate de que el cliente tenga una dirección de correo electrónico válida. Tanto Klaviyo como Omnisend requieren un correo electrónico para asociar el evento. Los clientes anónimos sin correos electrónicos no generarán eventos para estas plataformas.

El disparador de Shopify Flow no se activa

Verifica que:

La aplicación Shopify Flow esté instalada en tu tienda
Tu flujo de trabajo de Flow esté activo (no pausado)
El manejador de disparador en LoyaltyTree coincida exactamente con lo que configuraste en Shopify Flow
Tu plan de Shopify soporte Flow (Básico o superior)

Seguridad

Todas las claves API y tokens están encriptados en reposo utilizando encriptación AES-256-CBC
Los secretos de webhook permiten la verificación de firma HMAC para que tu endpoint pueda verificar que las solicitudes realmente provienen de LoyaltyTree
Los eventos se procesan a través de una cola asíncrona — el rendimiento de tu tienda nunca se ve afectado por la entrega de integración
Los eventos y registros entregados antiguos se eliminan automáticamente después de 30 días