Documentazione

Sendcloud e Klaviyo

Spedizioni con Sendcloud

i-Connect crea l’etichetta su Sendcloud per l’ordine già presente nel tuo account Sendcloud e riporta il numero di tracking sull’ordine PrestaShop. La cosa che aggiunge è il momento giusto per stampare: quando il gestionale ha confermato che la merce c’è.

L’etichetta può partire in quattro modi, configurabili in Impostazioni → Flussi → Spedizioni e tracking:

Modo	Quando parte	Default
Pulsante “Crea etichetta”	dalla pagina dell’ordine in dashboard, quando lo decidi tu	sempre disponibile
Stato del negozio	quando l’ordine PrestaShop entra nello stato che scegli	spento
Evadibile	appena il gestionale dichiara l’ordine evadibile	spento
Dopo il riallineo	quando un ordine parziale è stato riallineato: la merce rimasta parte	spento

1La piattaforma chiede a Sendcloud l’etichetta per quell’ordine, cercandolo per riferimento.
2Il numero di tracking torna sull’ordine PrestaShop; se l’hai scelto, l’ordine passa allo stato indicato in “Dopo l’etichetta, imposta lo stato”.
3Se il flusso marketing è attivo, parte l’evento Klaviyo iConnect Order Shipped.

Mai due etichette per lo stesso ordine

Il momento della richiesta resta registrato sull’ordine. Se un tentativo non ha lasciato un esito certo, la piattaforma non riprova da sola: il pulsante mostra “Etichetta bloccata” e chiede di controllare su Sendcloud prima di crearne un’altra. Un’etichetta doppia è una spedizione pagata due volte.

Impostazione	Cosa fa
Chiavi API	pubblica + segreta, da Impostazioni → Connessioni
Regole di spedizione Sendcloud	applica le shipping rules che hai configurato su Sendcloud
Shipping option code	corriere e servizio da usare, se non li decidono le regole (es. brt:standard)
ID contratto / indirizzo mittente	solo con contratto diretto col corriere o più magazzini
Tracking sull’ordine del negozio	scrive il numero di tracking sull’ordine PrestaShop (attivo)

Eventi Klaviyo

Con la chiave collegata, i-Connect invia a Klaviyo eventi server-side sul profilo del cliente finale (riconosciuto dall’email dell’ordine). Non dipendono da cookie o script sul sito. Le email le costruisci tu, con i tuoi template, come flow che partono da questi eventi.

Collegamento

1Su Klaviyo: Settings → API Keys → Create Private API Key → Custom Key.
2Permessi: Accounts: Read (verifica della connessione), Events: Full Access e Profiles: Full Access (invio degli eventi sul profilo). Senza Accounts: Read la connessione fallisce con un errore 403 “permission_denied”.
3Incolla la chiave in Impostazioni → Connessioni → Klaviyo.
4Attiva Impostazioni → Flussi → Notifiche marketing (Klaviyo): finché è spento nessun evento parte, anche con la chiave collegata.

Gli eventi e i loro campi

Nei template i campi si leggono con {{ event.nome_campo }}. I nomi sono esattamente questi, maiuscole e prefisso iConnect compresi: un flow costruito su “Order Shipped” senza prefisso non partirebbe mai.

Evento	Quando parte	Campi
iConnect Order Shipped	etichetta Sendcloud creata	order_reference, tracking_number, tracking_url, carrier
iConnect Order Modified	ordine parzialmente evadibile: righe mancanti tolte dall’ordine	order_reference, removed_items (reference, name, removed_qty), compensation_amount, compensation_mode, choice_url, choice_expires_at, voucher_code, voucher_months
iConnect Order Cancelled	nessuna riga evadibile: ordine annullato sul negozio	order_reference, refund_amount, payment_method, reason

compensation_mode vale customerChoice quando è il cliente a scegliere fra rimborso e buono (allora choice_url è il link alla pagina di scelta e voucher_code è vuoto), oppure voucher quando il buono è già stato creato (allora c’è voucher_codee il link è vuoto). Filtra il flow su questo campo.
choice_expires_at è in orario UTC: nel testo conviene scrivere “entro N giorni” o formattarlo con un filtro data.
Ogni evento ha un identificativo unico per ordine: Klaviyo scarta i duplicati, quindi un retry non manda due email. Conseguenza da sapere quando provi: rilanciare la verifica sullo stesso ordine non genera un secondo evento.
Le email che riguardano soldi dovuti (scelta del rimborso, ordine annullato) conviene inviarle come transazionali, così arrivano anche ai clienti non iscritti al marketing.

Esempio: il cliente sceglie fra rimborso e buono

1Trigger del flow: metrica iConnect Order Modified, filtro compensation_mode uguale a customerChoice.
2Email: “alcuni prodotti del tuo ordine {{ event.order_reference }} non sono disponibili”, l’elenco con {% for item in event.removed_items %}{{ item.removed_qty }} × {{ item.name }}{% endfor %} e un pulsante verso {{ event.choice_url }}.
3Il cliente sceglie sulla pagina di i-Connect: col buono lo crea il modulo sul negozio (v0.5.0+), col rimborso l’ordine compare nella pagina Rimborsi della dashboard.

Prossimo capitolo: Per il partner BC