API di Zestly: guida introduttiva

L'API di Zestly permette al tuo gestionale, alla tua agenzia o a chi sviluppa per te di leggere e usare il programma fedeltà da fuori dall'admin: vedere il saldo di un cliente, dare o togliere punti, riscattare un premio, leggere i numeri di «Analisi». È inclusa in ogni piano e la attivi da solo, senza chiedere al supporto.

La documentazione tecnica completa è in inglese: README.md e openapi.json.

1. Crea una chiave

In Zestly apri Sviluppatori.
In Chiavi API scegli Crea una chiave.
Dai un nome che ti dica chi la usa (es. «Gestionale» o «Agenzia Rossi»).
Scegli i permessi: solo quelli che servono. Una chiave «solo lettura» è proposta di partenza.
Se la chiave serve per un periodo limitato, metti una scadenza.
Copia la chiave e consegnala in modo sicuro: la vedi una sola volta. Zestly ne conserva solo un'impronta (hash) e non potrà mostrartela di nuovo.

Puoi avere fino a 20 chiavi attive (durante le 24 ore di una rotazione, una in più).

Una chiave appartiene al negozio, non a chi l'ha creata: se quella persona non lavora più con te, la chiave continua a funzionare finché non la revochi. La colonna «Creata da» ti dice chi l'ha fatta.

2. Cosa non fare

Non mettere mai la chiave nel tema, in una pagina web o in un'app: chiunque la vedrebbe. La chiave va usata solo dal server di chi integra.
Non usare la stessa chiave per tutto: una chiave per ogni integrazione, così puoi revocarne una senza fermare le altre.

3. I permessi

Permesso	Cosa consente
Leggere i membri e i saldi	elenco membri, scheda del membro, attività, premi
Iscrivere ed escludere membri	iscrizione, esclusione, riammissione
Dare e togliere punti	rettifiche del saldo, azioni personalizzate
Riscattare e stornare premi	riscatti per conto del cliente, storni
Leggere il programma	regole, premi, livelli, abbonamenti
Leggere gli inviti	inviti e codici invito
Cambiare il livello VIP	blocco e sblocco del livello
Concedere e revocare abbonamenti	«Concedi o estendi», «Revoca»
Leggere le analisi	i totali di «Analisi» per periodo
Leggere il registro modifiche (con gli id dei clienti)	il registro modifiche, che dice di quale cliente è ogni modifica
Annullare le modifiche ai membri	«Annulla» del registro modifiche, per le modifiche ai membri (quelle al programma le annulli tu in Zestly)
Proporre modifiche al programma (le applichi tu)	proposte di nuove regole e premi o di modifiche, che applichi tu dopo l'anteprima

4. Ruota, revoca, metti in pausa

Ruota: crea una chiave nuova con gli stessi permessi; la vecchia funziona ancora 24 ore (il tempo di sostituirla). Se la chiave è finita nelle mani sbagliate, scegli Ruota e revoca subito: la vecchia si ferma all'istante, e quello che chi l'ha trovata ha inviato non può bloccare le chiamate della chiave nuova.
Revoca: la chiave smette di funzionare all'istante.
Metti in pausa l'API: tutte le chiamate del negozio vengono rifiutate finché non la riattivi (utile se qualcosa non va e vuoi fermare tutto in un clic).

Se disinstalli Zestly, tutte le chiavi vengono revocate: dopo una nuova installazione ne crei di nuove.

5. Il registro chiamate

In Sviluppatori › Registro chiamate vedi le chiamate degli ultimi 7 giorni: ora, chiave, operazione, esito, durata e, in caso di errore, il codice. Con «Solo errori» trovi subito cosa non va. Delle chiamate rifiutate prima di essere eseguite (limite superato, API in pausa, permesso mancante) compare la prima di ogni minuto per chiave: un'integrazione che insiste non riempie il registro. Nel registro non ci sono mai gli id dei clienti né i dati inviati.

6. Le modifiche restano tue

Ogni modifica fatta con una chiave compare nel Registro modifiche con l'autore «API · nome della chiave», e si annulla come le tue. Le chiavi create, ruotate e revocate e la pausa dell'API compaiono anche loro nel registro.

7. Niente doppi punti

Ogni operazione che scrive (dare punti, riscattare, concedere un abbonamento…) porta una chiave di idempotenza scelta da chi integra, una per operazione (per esempio «crm-recensione-48213»). Se la stessa richiesta arriva due volte — un timeout, un nuovo tentativo — Zestly risponde come la prima volta e non muove mai i punti due volte. Le chiavi di idempotenza di un'integrazione non si scontrano mai con quelle di un'altra.

8. Privacy

L'API usa solo l'id cliente di Shopify e i numeri: non restituisce mai nomi, email o telefoni. Quando un cliente viene cancellato, Zestly cancella anche le righe del registro chiamate che lo riguardano.

9. Webhook: Zestly avvisa il tuo sistema

In Zestly › Sviluppatori › Webhook aggiungi un endpoint: l'indirizzo https del tuo sistema (o di chi sviluppa per te) e gli eventi che vuole ricevere — punti, premi, livelli VIP, inviti, abbonamenti — o «Tutti gli eventi». Zestly gli invia una richiesta firmata a ogni evento, pochi secondi dopo.

Il segreto (whsec_…) si vede una volta sola, quando aggiungi l'endpoint: serve a chi sviluppa per verificare che le richieste vengano da Zestly. «Ruota il segreto» ne crea uno nuovo (per 24 ore valgono entrambi).
«Invia un evento di prova» manda subito un evento di prova e ti dice se il tuo sistema ha risposto.
Se il tuo sistema non risponde, Zestly riprova 8 volte in circa 45 ore (quasi 2 giorni). Se per 3 giorni non riesce mai, disattiva l'endpoint, ti scrive un'email e lo segnala in «Da verificare»; gli eventi restano in attesa. Quando hai sistemato, premi «Riattiva»: partono gli eventi in attesa e quelli non riusciti degli ultimi 30 giorni. Se invece il tuo sistema risponde 410 («non esiste più»), Zestly disattiva subito l'endpoint e non tiene da parte eventi.
Consegne: lo storico degli ultimi 30 giorni, con «Riprova» per una consegna non riuscita.
Privacy: le richieste contengono l'id cliente di Shopify e i numeri, mai nomi o email; i codici sconto dei premi sì, per poterli mandare al cliente (per esempio via SMS). Gli indirizzi li scegli tu: Zestly non invia nulla a indirizzi interni o privati. Quando cancelli un cliente, i tuoi endpoint ricevono «Cliente cancellato» per cancellarlo anche loro.

10. Shopify Flow: automazioni senza codice

Shopify Flow è gratuito sui piani a pagamento. Con Zestly installato, Flow riceve 8 trigger Zestly (punti guadagnati, premio ottenuto, livello VIP cambiato, vicino al livello successivo, punti in scadenza, invito riuscito, abbonamento attivato, abbonamento scaduto) e 5 azioni Zestly (dare e togliere punti, completare un'azione personalizzata, premiare una recensione, regalare un premio). In Flow i loro nomi sono in inglese («Points earned», «Give points»…). Non servono chiavi: Flow e Zestly si riconoscono da soli.

Recensioni: crea in Regole la regola «Lascia una recensione» (punti, bonus foto e video; già limitata a una recensione premiata per prodotto e a 5 recensioni ogni 30 giorni per cliente, limiti che puoi cambiare), poi in Flow collega il trigger della tua app di recensioni all'azione «Reward a review» e spunta «Ho collegato Shopify Flow»: solo allora i clienti vedono che le recensioni danno punti. Una recensione premia una volta sola.
Recensioni oneste: ogni recensione onesta riceve gli stessi punti, positiva o negativa. Non esiste un voto minimo e non va aggiunto in Flow: le regole sulle recensioni (la direttiva Omnibus in Europa, la norma FTC 16 CFR 465 negli Stati Uniti) vietano gli incentivi legati al giudizio. Puoi invece premiare solo le recensioni pubblicate, approvate o di acquirenti verificati.
Niente cicli: se un flusso dà un premio quando «Reward issued» parte, aggiungi la condizione «Source non è flow», altrimenti il premio dato fa ripartire il flusso. Se la stessa azione parte più di 10 volte in un minuto per lo stesso cliente, Zestly la rifiuta.
Niente doppi punti: se Flow ripete un'azione, Zestly la applica una volta sola.
Un trigger parte una volta sola: se Shopify non risponde, Zestly non lo ripete (meglio un flusso perso che un premio doppio); se Shopify è solo occupato, Zestly lo invia poco dopo. Se Flow rifiuta lo stesso trigger 3 volte di fila per tutto il negozio, lo trovi in «Da verificare».
Sviluppatori › Shopify Flow ti dice quali trigger usano i tuoi flussi attivi.

La guida completa, in inglese, è in flow.md.