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)
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.
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. 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.
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
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. Puoi raggiungerla in qualsiasi momento anche dal link Leggi la documentazione API in cima alla pagina API e webhook.