Integrações de Saída

🔗 Integrações de Saída

Conecte seus eventos do LoyaltyTree a plataformas externas de marketing, automação e análise. Envie dados em tempo real sobre a atividade do cliente para potencializar campanhas de e-mail, segmentos de clientes, automações e muito mais.

Plataformas Suportadas

O LoyaltyTree suporta o envio de eventos para as seguintes plataformas:

Plataforma	Tipo	O Que Você Precisa
Klaviyo	Marketing por E-mail/SMS	Sua Chave de API Privada do Klaviyo
Omnisend	Marketing por E-mail/SMS	Sua Chave de API do Omnisend
Shopify Flow	Automação do Shopify	Um Manipulador de Gatilho de Flow (criado no Shopify Flow)
Webhook Genérico	Qualquer Endpoint HTTP	Uma URL de webhook que aceita requisições POST

Começando

Passo 1: Navegue até Integrações

Vá para Loja → [Sua Loja] → Integrações → Webhooks de Saída no seu painel de administração.

Passo 2: Adicione uma Nova Integração

Clique no botão + Adicionar Integração. Selecione sua plataforma, dê um nome e escolha quais eventos enviar.

Passo 3: Insira suas Credenciais

Dependendo da plataforma, você precisará fornecer uma chave de API, URL de webhook ou manipulador de gatilho. Todos os dados sensíveis são criptografados antes do armazenamento.

Passo 4: Teste a Conexão

Use o botão Testar no seu cartão de integração para enviar um evento de teste e verificar se tudo está conectado corretamente.

Eventos Suportados (19 no Total)

Você pode assinar cada integração para qualquer combinação desses eventos. Apenas os eventos que você selecionar serão enviados para essa plataforma.

🌱 Eventos de Sementes Ganhas

Acionado quando um cliente ganha sementes através de várias atividades.

Evento	Chave do Evento	Acionado Quando
Sementes – Ganhas – Pedido	`seeds.earned.order`	Cliente ganha sementes de uma compra
Sementes – Ganhas – Visita	`seeds.earned.visit`	Cliente ganha sementes ao visitar a loja
Sementes – Ganhas – Avaliação	`seeds.earned.review`	Cliente ganha sementes ao escrever uma avaliação
Sementes – Ganhas – Referência	`seeds.earned.referral`	Cliente ganha sementes de uma referência bem-sucedida
Sementes – Ganhas – Compartilhamento Social	`seeds.earned.social_share`	Cliente ganha sementes ao compartilhar nas redes sociais
Sementes – Ganhas – Bônus	`seeds.earned.bonus`	Cliente recebe sementes bônus (aniversário, prêmio manual, etc.)

⭐ Eventos de Nível & Avaliação

Evento	Chave do Evento	Acionado Quando
Nível – Alterado	`tier.changed`	Cliente muda para um nível de fidelidade diferente
Avaliação – Enviada	`review.submitted`	Cliente envia uma nova avaliação de produto
Avaliação – Aprovada	`review.approved`	Uma avaliação de produto é aprovada (por IA ou manualmente)
Avaliação – Rejeitada	`review.rejected`	Uma avaliação de produto é rejeitada

🎁 Eventos de Recompensa

Evento	Chave do Evento	Acionado Quando
Cartão Presente – Ganho	`gift_card.earned`	Cliente se qualifica para uma recompensa de cartão presente
Cartão Presente – Reclamado	`gift_card.claimed`	Cliente reclama seu cartão presente
Crédito na Loja – Ganho	`store_credit.earned`	Cliente se qualifica para crédito na loja
Crédito na Loja – Reclamado	`store_credit.claimed`	Cliente reclama seu crédito na loja

🌳 Eventos Ecológicos & de Referência

Evento	Chave do Evento	Acionado Quando
Produto Ecológico – Premiado	`eco_product.awarded`	Cliente resgata sementes por um produto ecológico
Ecológico – Árvore Plantada	`eco.tree_planted`	Uma árvore é plantada para o cliente
Referência – Gerada	`referral.generated`	Cliente gera um link de referência
Referência – Visita	`referral.visit`	Alguém visita a loja através de um link de referência
Referência – Bem-sucedida	`referral.successful`	Um visitante referido faz uma compra

Guias de Configuração da Plataforma

📧 Klaviyo

Klaviyo é uma plataforma de marketing por e-mail e SMS popular entre lojas Shopify. O LoyaltyTree envia eventos para o Klaviyo usando sua API de Eventos (v3), para que você possa construir segmentos, fluxos e campanhas com base na atividade de fidelidade.

Configuração:

No Klaviyo, vá para Configurações → Chaves de API e crie uma Chave de API Privada
No LoyaltyTree, clique em + Adicionar Integração, selecione Klaviyo
Cole sua Chave de API Privada
Selecione quais eventos enviar
Clique em Salvar Integração

Como funciona: O LoyaltyTree cria eventos Klaviyo com o e-mail do cliente como identificador de perfil. Os eventos aparecem como métricas personalizadas (por exemplo, "Sementes Ganhas Pedido", "Nível Alterado") que você pode usar em fluxos e segmentos do Klaviyo. Os valores das sementes são enviados como o valor do evento, para que você possa usá-los em divisões condicionais.

📨 Omnisend

Omnisend é outra plataforma popular de marketing por e-mail e SMS. O LoyaltyTree envia eventos usando a API de Eventos do Omnisend (v5).

Configuração:

No Omnisend, vá para Configurações → Chaves de API e gere uma chave
No LoyaltyTree, clique em + Adicionar Integração, selecione Omnisend
Cole sua Chave de API
Selecione quais eventos enviar
Clique em Salvar Integração

Como funciona: Os eventos são enviados com o e-mail, nome e ID do cliente Shopify. Cada evento inclui todas as propriedades relevantes (valores de sementes, detalhes do pedido, informações do nível, etc.) para que você possa usá-los em fluxos de automação e segmentação do Omnisend.

⚡ Shopify Flow

Shopify Flow é a ferramenta de automação integrada do Shopify. O LoyaltyTree envia eventos diretamente para o Shopify Flow usando a mutação flowTriggerReceive do GraphQL, o que significa que os eventos aparecem como gatilhos dentro dos seus fluxos do Flow — sem necessidade de aplicativos de terceiros.

⚠️ Importante: O Shopify Flow está disponível no plano Basic e acima do Shopify. Você precisa ter o aplicativo Shopify Flow instalado em sua loja.

Configuração:

No seu admin do Shopify, vá para Flow e crie um novo fluxo de trabalho
Adicione um gatilho — use o manipulador de gatilho do aplicativo LoyaltyTree
No LoyaltyTree, clique em + Adicionar Integração, selecione Shopify Flow
Insira o Manipulador de Gatilho do Flow que corresponde ao seu gatilho do Shopify Flow
Selecione quais eventos enviar
Clique em Salvar Integração

Como funciona: Quando um evento assinado ocorre, o LoyaltyTree usa a conexão da API do Shopify da sua loja para enviar os dados do evento diretamente para o Shopify Flow via GraphQL. O payload é achatado em chaves legíveis como "E-mail do cliente", "Tipo de evento", "Quantidade", etc. Você pode então usar esses valores como condições no seu Flow para acionar ações como enviar e-mails, marcar clientes ou criar tarefas.

Exemplos de automações do Shopify Flow:

Marcar clientes quando atingem o nível Ouro
Enviar uma notificação interna no Slack quando uma árvore é plantada
Criar uma tarefa quando uma avaliação é enviada
Adicionar uma nota ao perfil do cliente quando ele ganha um cartão presente

🌐 Webhook Genérico

Envie eventos do LoyaltyTree para qualquer endpoint HTTP. Isso é perfeito para conectar a sistemas personalizados, Zapier, Make (Integromat), n8n ou qualquer outra plataforma que aceite POSTs de webhook.

Configuração:

Obtenha a URL do seu endpoint de webhook na sua plataforma receptora
No LoyaltyTree, clique em + Adicionar Integração, selecione Webhook Genérico
Insira a URL do Webhook
(Opcional) Escolha um método de autenticação e adicione credenciais
(Opcional) Adicione um segredo de webhook para verificação de assinatura HMAC
Selecione quais eventos enviar
Clique em Salvar Integração

Opções de autenticação:

Método	Cabeçalho Enviado	Descrição
Assinatura HMAC	`X-LoyaltyTree-Signature`	SHA-256 HMAC do corpo do payload, assinado com seu segredo de webhook
Token Bearer	`Authorization: Bearer <token>`	Autenticação padrão de token bearer estilo OAuth
X-Token	`X-Token: <token>`	Token simples em um cabeçalho personalizado
Cabeçalho Personalizado	`<seu-cabeçalho>: <token>`	Especifique seu próprio nome de cabeçalho e valor de token

Modelos de Payload Personalizados: Para Webhooks Genéricos, você pode personalizar o formato do payload para cada evento usando variáveis de modelo. Isso permite que você corresponda ao formato exato que seu sistema receptor espera.

Cabeçalhos padrão enviados com cada requisição:

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

Exemplo de Payload de Webhook

Aqui está como um típico evento seeds.earned.order se parece quando entregue a um 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"
}

Todo payload de evento inclui o objeto customer com seu e-mail, nome e ID do cliente Shopify, além de campos de dados específicos do evento.

Referência de Dados do Evento

Abaixo está uma lista detalhada dos campos de dados incluídos com cada tipo de evento.

🌱 seeds.earned.order

amount – Número de sementes ganhas
order_id – ID do pedido Shopify
order_number – Número do pedido legível por humanos
order_total – Valor total do pedido
order_currency – Código da moeda (por exemplo, USD)
balance – Novo saldo de sementes do cliente
tier – Nome do nível atual do cliente

👁️ seeds.earned.visit

amount – Número de sementes ganhas
visit_number – Qual visita foi essa
balance – Novo saldo de sementes do cliente
tier – Nome do nível atual do cliente

✍️ seeds.earned.review

amount – Número de sementes ganhas
product – Objeto com id e title do produto
rating – Avaliação em estrelas (1-5)
has_photos – Se a avaliação inclui fotos
platform – Plataforma da avaliação (por exemplo, "loyaltytree")
balance – Novo saldo de sementes do cliente
tier – Nome do nível atual do cliente

🤝 seeds.earned.referral

amount – Número de sementes ganhas
referral_type – Tipo de referência (por exemplo, "referral_purchase")
referred_customer – Objeto com as informações do cliente referido
balance – Novo saldo de sementes do cliente
tier – Nome do nível atual do cliente

📱 seeds.earned.social_share

amount – Número de sementes ganhas
platform – Plataforma social utilizada (por exemplo, "twitter", "facebook")
share_url – A URL que foi compartilhada
balance – Novo saldo de sementes do cliente
tier – Nome do nível atual do cliente

🎉 seeds.earned.bonus

amount – Número de sementes ganhas
reason – Motivo do bônus (por exemplo, "Bônus de Aniversário")
balance – Novo saldo de sementes do cliente
tier – Nome do nível atual do cliente

📊 tier.changed

old_tier – Nome do nível anterior
new_tier – Nome do novo nível
total_seeds – Total de sementes do cliente ao longo da vida

📝 review.submitted

review_id – Identificador único da avaliação
product – Objeto com id e title do produto
rating – Avaliação em estrelas (1-5)
title – Título da avaliação
body – Texto do corpo da avaliação
photos – Array de URLs de fotos
has_photo – Se a avaliação tem fotos

✅ review.approved

review_id – Identificador único da avaliação
product – Objeto com id e title do produto
rating – Avaliação em estrelas (1-5)
title – Título da avaliação
body – Texto do corpo da avaliação
photos – Array de URLs de fotos
seeds_awarded – Sementes dadas por esta avaliação

❌ review.rejected

review_id – Identificador único da avaliação
product – Objeto com id e title do produto
rating – Avaliação em estrelas (1-5)
rejection_reason – Motivo pelo qual a avaliação foi rejeitada

🎁 gift_card.earned

amount – Valor monetário do cartão presente
currency – Código da moeda
seeds_redeemed – Sementes gastas para ganhar isso
tier – Nível atual do cliente

💳 gift_card.claimed

amount – Valor monetário do cartão presente
currency – Código da moeda
code – O código do cartão presente

💰 store_credit.earned & store_credit.claimed

amount – Valor monetário do crédito na loja
currency – Código da moeda
seeds_redeemed – Sementes gastas (apenas evento ganho)
tier – Nível atual do cliente (apenas evento ganho)

🌳 eco_product.awarded

eco_product_name – Nome do produto ecológico
eco_product_type – Tipo (por exemplo, "árvore", "coral")
seeds_spent – Sementes gastas neste produto

🌲 eco.tree_planted

trees_count – Número de árvores plantadas
project_name – Nome do projeto de reflorestamento
certificate_url – Link para o certificado de plantio

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

referral_code – Código de referência único (gerado apenas)
share_url – URL de referência (gerada apenas)
visitor_id – ID do visitante anônimo (apenas visita)
seeds_awarded – Sementes ganhas (visita & bem-sucedida)
referred_customer – Informações sobre o novo cliente (apenas bem-sucedido)
order_total – Total do pedido do cliente referido (apenas bem-sucedido)

Confiabilidade & Lógica de Repetição

O LoyaltyTree usa uma fila assíncrona para garantir a entrega confiável de eventos. Os eventos nunca são perdidos — se a entrega falhar, o sistema automaticamente tenta novamente com um retrocesso exponencial.

Tentativa de Repetição	Tempo de Espera
1ª repetição	1 minuto
2ª repetição	5 minutos
3ª repetição	30 minutos
4ª repetição	2 horas
5ª repetição (final)	24 horas

Após todas as tentativas serem esgotadas, o evento é marcado como "esgotado" e aparece em seus Registros de Eventos com um botão Tentar Novamente para que você possa tentar manualmente a qualquer momento.

Registros de Eventos

Cada entrega de evento é registrada e visível na seção Registros de Eventos na página de Integrações. Você pode filtrar os registros por:

Conexão – Veja eventos para uma integração específica
Evento – Filtrar por tipo de evento
Cliente – Pesquisar por e-mail ou nome do cliente
Intervalo de Datas – Ver eventos de um período específico

Cada entrada de registro mostra o horário, plataforma, tipo de evento, status e quaisquer mensagens de erro. Eventos falhados incluem um botão Tentar Novamente para reencaminhá-los imediatamente.

Resolução de Problemas

Eventos mostram status "falhou"

Verifique a mensagem de erro nos Registros de Eventos. Causas comuns:

Não foi possível conectar – A URL do webhook pode estar fora do ar ou incorreta
Erro 401/403 – Sua chave de API ou token de autenticação pode ser inválido
Timeout – O servidor receptor está muito lento para responder (timeout de 10 segundos)

Eventos não aparecem no Klaviyo/Omnisend

Certifique-se de que o cliente tenha um endereço de e-mail válido. Tanto o Klaviyo quanto o Omnisend exigem um e-mail para associar o evento. Clientes anônimos sem e-mails não gerarão eventos para essas plataformas.

Gatilho do Shopify Flow não acionando

Verifique se:

O aplicativo Shopify Flow está instalado em sua loja
Seu fluxo de trabalho do Flow está ativo (não pausado)
O manipulador de gatilho no LoyaltyTree corresponde exatamente ao que você configurou no Shopify Flow
Seu plano do Shopify suporta o Flow (Basic ou superior)

Segurança

Todas as chaves de API e tokens são criptografados em repouso usando criptografia AES-256-CBC
Segredos de webhook permitem verificação de assinatura HMAC para que seu endpoint possa verificar se as requisições realmente vieram do LoyaltyTree
Eventos são processados através de uma fila assíncrona — o desempenho da sua loja nunca é impactado pela entrega de integrações
Eventos entregues antigos e registros são automaticamente limpos após 30 dias