Integrazioni in uscita

🔗 Integrazioni in Uscita

Collega i tuoi eventi di LoyaltyTree a piattaforme esterne di marketing, automazione e analisi. Invia dati in tempo reale sull'attività dei clienti per alimentare campagne email, segmenti di clienti, automazioni e altro ancora.

---

Piattaforme Supportate

LoyaltyTree supporta l'invio di eventi alle seguenti piattaforme:

Piattaforma	Tipo	Cosa Ti Serve
Klaviyo	Marketing Email/SMS	La tua Chiave API Privata Klaviyo
Omnisend	Marketing Email/SMS	La tua Chiave API Omnisend
Shopify Flow	Automazione Shopify	Un Trigger Handle di Flow (creato in Shopify Flow)
Webhook Generico	Qualsiasi Endpoint HTTP	Un URL webhook che accetta richieste POST

---

Iniziare

---

Eventi Supportati (19 Totali)

Puoi iscrivere ogni integrazione a qualsiasi combinazione di questi eventi. Solo gli eventi che selezioni saranno inviati a quella piattaforma.

🌱 Eventi Semi Guadagnati

Attivato quando un cliente guadagna semi attraverso varie attività.

Evento	Chiave Evento	Attivato Quando
Semi – Guadagnati – Ordine	seeds.earned.order	Il cliente guadagna semi da un acquisto
Semi – Guadagnati – Visita	seeds.earned.visit	Il cliente guadagna semi visitando il negozio
Semi – Guadagnati – Recensione	seeds.earned.review	Il cliente guadagna semi scrivendo una recensione
Semi – Guadagnati – Referral	seeds.earned.referral	Il cliente guadagna semi da un referral riuscito
Semi – Guadagnati – Condivisione Sociale	seeds.earned.social_share	Il cliente guadagna semi condividendo sui social media
Semi – Guadagnati – Bonus	seeds.earned.bonus	Il cliente riceve semi bonus (compleanno, premio manuale, ecc.)

⭐ Eventi di Livello & Recensione

Evento	Chiave Evento	Attivato Quando
Livello – Cambiato	tier.changed	Il cliente passa a un diverso livello di fedeltà
Recensione – Inviata	review.submitted	Il cliente invia una nuova recensione del prodotto
Recensione – Approvata	review.approved	Una recensione del prodotto è approvata (da AI o manualmente)
Recensione – Rifiutata	review.rejected	Una recensione del prodotto è rifiutata

🎁 Eventi di Ricompensa

Evento	Chiave Evento	Attivato Quando
Carta Regalo – Guadagnata	gift_card.earned	Il cliente si qualifica per una ricompensa in carta regalo
Carta Regalo – Richiesta	gift_card.claimed	Il cliente richiede la propria carta regalo
Credito Negozio – Guadagnato	store_credit.earned	Il cliente si qualifica per credito negozio
Credito Negozio – Richiesto	store_credit.claimed	Il cliente richiede il proprio credito negozio

🌳 Eventi Eco & Referral

Evento	Chiave Evento	Attivato Quando
Prodotto Eco – Assegnato	eco_product.awarded	Il cliente riscatta semi per un prodotto eco
Eco – Albero Piantato	eco.tree_planted	Un albero è piantato per il cliente
Referral – Generato	referral.generated	Il cliente genera un link di referral
Referral – Visita	referral.visit	Qualcuno visita il negozio tramite un link di referral
Referral – Riuscito	referral.successful	Un visitatore referito effettua un acquisto

---

Guide di Configurazione della Piattaforma

📧 Klaviyo

Klaviyo è una piattaforma di marketing email e SMS popolare tra i negozi Shopify. LoyaltyTree invia eventi a Klaviyo utilizzando la loro API Eventi (v3), quindi puoi costruire segmenti, flussi e campagne basati sull'attività di fedeltà.

Come funziona: LoyaltyTree crea eventi Klaviyo con l'email del cliente come identificatore del profilo. Gli eventi appaiono come metriche personalizzate (ad es. "Semi Guadagnati Ordine", "Livello Cambiato") che puoi utilizzare nei flussi e segmenti di Klaviyo. Gli importi dei semi vengono inviati come valore dell'evento, quindi puoi usarli in split condizionali.

📨 Omnisend

Omnisend è un'altra popolare piattaforma di marketing email e SMS. LoyaltyTree invia eventi utilizzando la API Eventi Omnisend (v5).

Come funziona: Gli eventi vengono inviati con l'email, il nome e l'ID cliente Shopify del cliente. Ogni evento include tutte le proprietà rilevanti (importi dei semi, dettagli dell'ordine, informazioni sul livello, ecc.) in modo da poterle utilizzare nei flussi di automazione e segmentazione di Omnisend.

⚡ Shopify Flow

Shopify Flow è lo strumento di automazione integrato di Shopify. LoyaltyTree invia eventi direttamente a Shopify Flow utilizzando la mutazione flowTriggerReceive GraphQL, il che significa che gli eventi appaiono come trigger all'interno dei tuoi flussi di Flow — nessuna app di terze parti necessaria.

Come funziona: Quando si verifica un evento iscritto, LoyaltyTree utilizza la connessione API Shopify del tuo negozio per inviare i dati dell'evento direttamente in Shopify Flow tramite GraphQL. Il payload è appiattito in chiavi leggibili come "Email cliente", "Tipo evento", "Importo", ecc. Puoi quindi utilizzare questi valori come condizioni nel tuo Flow per attivare azioni come inviare email, etichettare clienti o creare attività.

Esempi di automazioni Shopify Flow:

• Etichetta i clienti quando raggiungono il livello Oro
• Invia una notifica interna su Slack quando un albero è piantato
• Crea un'attività quando una recensione è inviata
• Aggiungi una nota al profilo cliente quando guadagnano una carta regalo

 

🌐 Webhook Generico

Invia eventi di LoyaltyTree a qualsiasi endpoint HTTP. Questo è perfetto per collegarsi a sistemi personalizzati, Zapier, Make (Integromat), n8n, o qualsiasi altra piattaforma che accetta POST webhook.

Opzioni di autenticazione:

Metodo	Intestazione Inviata	Descrizione
Firma HMAC	X-LoyaltyTree-Signature	SHA-256 HMAC del corpo del payload, firmato con il tuo segreto webhook
Bearer Token	Authorization: Bearer <token>	Autenticazione standard con token bearer in stile OAuth
X-Token	X-Token: <token>	Token semplice in un'intestazione personalizzata
Intestazione Personalizzata	<your-header>: <token>	Specifica il tuo nome di intestazione e valore del token

Modelli di Payload Personalizzati: Per i Webhook Generici, puoi personalizzare il formato del payload per ogni evento utilizzando variabili di modello. Questo ti consente di abbinare il formato esatto che il tuo sistema di ricezione si aspetta.

Intestazioni standard inviate con ogni richiesta:

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

---

Esempio di Payload Webhook

Ecco come appare un tipico evento seeds.earned.order quando viene consegnato a un Webhook Generico:

{
  "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"
}

Ogni payload di evento include l'oggetto cliente con la propria email, nome e ID cliente Shopify, oltre ai campi di dati specifici dell'evento.

---

Riferimento Dati Evento

Di seguito è riportato un elenco dettagliato dei campi dati inclusi con ogni tipo di evento.

---

Affidabilità & Logica di Riprova

LoyaltyTree utilizza una coda asincrona per garantire una consegna affidabile degli eventi. Gli eventi non vengono mai persi — se la consegna fallisce, il sistema riprova automaticamente con un backoff esponenziale.

Tentativo di Riprova	Tempo di Attesa
1° riprova	1 minuto
2° riprova	5 minuti
3° riprova	30 minuti
4° riprova	2 ore
5° riprova (finale)	24 ore

Dopo che tutti i tentativi di riprova sono esauriti, l'evento viene contrassegnato come "esaurito" e appare nei tuoi Log degli Eventi con un pulsante Riprova in modo da poterlo riprovare manualmente in qualsiasi momento.

Log degli Eventi

Ogni consegna di evento è registrata e visibile nella sezione Log degli Eventi nella pagina delle Integrazioni. Puoi filtrare i log per:

• Connessione – Vedi eventi per una specifica integrazione
• Evento – Filtra per tipo di evento
• Cliente – Cerca per email o nome del cliente
• Intervallo di Date – Visualizza eventi di un periodo di tempo specifico

Ogni voce di log mostra l'ora, la piattaforma, il tipo di evento, lo stato e eventuali messaggi di errore. Gli eventi falliti includono un pulsante Riprova per rimetterli immediatamente in coda.

 

---

Risoluzione dei Problemi

---

Sicurezza

• Tutte le chiavi API e i token sono crittografati a riposo utilizzando la crittografia AES-256-CBC
• I segreti webhook abilitano la verifica della firma HMAC in modo che il tuo endpoint possa verificare che le richieste provengano realmente da LoyaltyTree
• Gli eventi vengono elaborati tramite una coda asincrona — le prestazioni del tuo negozio non sono mai influenzate dalla consegna dell'integrazione
• Eventi e log consegnati vecchi vengono automaticamente ripuliti dopo 30 giorni