Usare l'API di Passtastic | Passtastic Help
Passtastic
Explore
Product
Loyalty app
Pricing
Use Cases
Customer Stories
Help
No account yet? Sign up free

Usare l'API di Passtastic

Cosa ti permette di fare l'API

L'API di Passtastic collega i tuoi sistemi — un POS personalizzato, un CRM, un'app interna — direttamente al tuo programma fedeltà. Con essa puoi:

  • Iscrivere clienti ed emettere carte wallet dal tuo flusso di registrazione
  • Aggiungere timbri o punti, e controllare il saldo di un cliente, dalla tua cassa o back office
  • Ricevere notifiche in tempo reale con i webhook — invece di interrogare continuamente l'API, Passtastic invia un evento al tuo sistema nel momento in cui succede qualcosa (un cliente si iscrive, un premio viene riscattato, e altro)
  • Riutilizzare i clienti che hai già — se qualcuno che il tuo sistema iscrive si è già registrato tramite la tua pagina di registrazione, Passtastic lo riconosce tramite email o telefono e aggiunge il tuo riferimento alla carta che ha già, invece di emetterne una seconda

Questo è pensato per attività che creano un'integrazione personalizzata. Se vuoi solo una connessione già pronta, consulta Collega Square POS o Sistemi POS e integrazioni — senza scrivere codice.

L'accesso all'API dipende dal tuo piano. Se non è incluso, vedrai una proposta di upgrade aprendo API e webhook in Impostazioni.

Crea una chiave API

1. Apri Impostazioni, poi API e webhook (in Attività).

2. Nella scheda Chiavi API, clicca su Crea chiave di test per provarla senza rischi, oppure su Crea chiave live quando sei pronto a collegare clienti reali.

3. Assegna un nome alla chiave per sapere in seguito a cosa serve (es. "CRM di produzione").

4. La tua nuova chiave viene mostrata una sola volta, nella finestra La tua nuova chiave API (per una chiave di test: La tua nuova chiave di test). Copiala ora — non potrai più vederla in seguito. Clicca su Copia, oppure su Mostra per rivelarla prima.

Tratta questa chiave come una password. Chiunque la possieda può agire sul tuo account tramite l'API.

5. Conserva la chiave in modo sicuro nel tuo sistema (una variabile d'ambiente, un secrets manager) e inviala come header di autenticazione a ogni richiesta — il formato esatto è nel riferimento tecnico più sotto.

Solo gli admin possono creare o revocare le chiavi API.

Provala prima con una chiave di test

Le chiavi di test funzionano su ogni piano, anche durante la prova gratuita — nessun upgrade necessario. I clienti di test ricevono una vera carta wallet, contrassegnata TEST, e vengono rimossi automaticamente dopo 30 giorni — non devi eliminare nulla a mano.

Segui la Quickstart nella documentazione tecnica con la tua chiave di test: ti guida passo passo nell'iscrivere un cliente di test e aggiungere una carta sul tuo telefono, prima ancora che sia coinvolto un cliente reale.

Quando la tua integrazione funziona dall'inizio alla fine, torna su API e webhook e clicca su Crea chiave live per passare a clienti reali. Le chiavi live sono disponibili da Multi-Sede in su.

Hai perso una chiave o pensi sia stata compromessa?

Le chiavi non vengono mostrate di nuovo dopo la creazione. Se ne hai persa una, o pensi che sia stata esposta, apri Chiavi API e clicca su Revoca — questo la blocca immediatamente — poi creane una nuova e aggiorna la tua integrazione.

Configura un webhook

I webhook permettono al tuo sistema di reagire nel momento in cui succede qualcosa su Passtastic, senza dover continuare a interrogare l'API.

1. Nella scheda Webhook, clicca su Aggiungi endpoint.

2. Inserisci l'URL endpoint — l'indirizzo del tuo sistema che riceverà l'evento (es. `https://tuo-sistema.com/hook`).

3. In Eventi, scegli quali ricevere:

  • Cliente iscritto
  • Saldo aggiornato
  • Livello cambiato
  • Premio riscattato
  • Carta scaduta
  • Carta rinnovata

4. Salva. Il tuo secret di firma viene mostrato una sola volta, nella finestra Secret di firma — copialo ora. Usalo per verificare che una richiesta webhook provenga davvero da Passtastic (il riferimento tecnico spiega come controllare la firma).

Solo gli admin possono creare o modificare i webhook.

Ogni endpoint webhook mostra le sue consegne recenti, così puoi controllare se una chiamata è andata a buon fine o è fallita, e ripetere l'invio di una consegna fallita non appena il tuo sistema torna disponibile, senza aspettare il prossimo evento.

Modificare o disattivare un webhook

Apri l'endpoint e clicca su Modifica per cambiarne URL o eventi, oppure imposta lo stato su Disattivato per mettere in pausa le consegne senza eliminarlo. Clicca su Elimina per rimuoverlo definitivamente.

Dove trovare il riferimento tecnico completo

Questa guida copre il lato dashboard — creare chiavi e webhook. Per endpoint, formati di richiesta/risposta, header di autenticazione, codici di errore ed esempi di codice, consulta la documentazione API completa, oppure vai direttamente al riferimento API per lo schema di richiesta/risposta di ogni endpoint. Puoi raggiungere entrambi in qualsiasi momento anche dai link Leggi la documentazione API e Riferimento API in cima alla pagina API e webhook — il riferimento API si apre in una nuova scheda.

Domande frequenti

Mi serve un POS per usare l'API?
No. L'API serve a collegare i tuoi sistemi — un POS personalizzato, un CRM o un'app. Se preferisci una connessione già pronta, consulta Collega Square POS o Sistemi POS e integrazioni.
La mia integrazione creerà clienti duplicati?
No. Quando il tuo sistema iscrive qualcuno, Passtastic controlla prima se quel cliente esiste già nel tuo account — tramite il riferimento inviato dal tuo sistema, poi tramite email, poi tramite telefono. Se esiste, collega il tuo riferimento alla sua carta esistente invece di emetterne una seconda, così i suoi timbri e punti restano dove sono. Se due clienti condividono la stessa email o lo stesso telefono, Passtastic non indovina tra loro — restituisce un errore che li nomina entrambi, così il tuo sviluppatore può scegliere quello giusto.
Il mio sistema può sapere quando scade la carta di un cliente?
Sì. Se la tua carta ha un periodo di validità (Validità della carta sotto Dettagli della carta nella scheda Configurazione del programma), seleziona Carta scaduta e Carta rinnovata nel tuo webhook: il tuo sistema saprà quando una carta scade e quando viene rinnovata, anche quando la rinnovi in Passtastic. Il tuo sviluppatore può anche leggere la data di scadenza di ogni cliente e rinnovare una carta dal tuo sistema. Per provarlo prima che scada una carta reale, una chiave di test può far scadere subito la carta di un cliente di test. Trovi i dettagli nella documentazione API.
L'accesso all'API è incluso nel mio piano?
L'API è inclusa in Multi-Sede e Gruppi e Brand. Con Sede Singola, API e webhook in Impostazioni mostra una proposta di upgrade al posto delle tue chiavi.
Dove trovo l'ID di una carta?
Apri la scheda Condividi del programma. In Condividi sui Social Media o sul Sito Web vedi il suo link: la parte dopo `/get-pass/` è l'ID della carta. Non copiare l'ID dall'indirizzo della pagina del programma, perché può essere diverso. Il tuo sviluppatore può anche elencare tutte le tue carte e i loro ID tramite l'API (`GET /api/v1/cards`).
Il mio sviluppatore riceve "Missing scope(s): cards:read". Cosa faccio?
La chiave è stata creata prima che l'API potesse elencare le carte. Crea una nuova chiave (Chiavi API → Crea chiave), dalla al tuo sviluppatore, poi usa Revoca sulla vecchia.
Chi può gestire chiavi API e webhook?
Solo gli admin. Editor e visualizzatori non vedranno l'opzione per creare, modificare o revocare una chiave o un webhook.
Posso avere più di una chiave API?
Sì — crea una chiave separata per ogni sistema o ambiente (es. una per il tuo CRM, una per un ambiente di staging), così puoi revocarne una senza interrompere le altre.
Un webhook ha smesso di ricevere eventi: cosa è successo?
Apri l'endpoint e controlla le consegne recenti per il motivo del fallimento (es. il tuo server ha restituito un errore o è andato in timeout). Risolvi il problema dal tuo lato, poi clicca su Ripeti invio sulla consegna fallita per rinviarla.