Integrazioni con software esterni

Funzionalità riservata al piano ULTRA.

Le integrazioni permettono di collegare un software esterno a Tesserando: non solo un POS o un gestionale di cassa, ma qualunque programma che registra un evento ripetibile della tua attività — un acquisto, ma anche una partita giocata, una visita, una prenotazione, un servizio erogato. Il software esterno può accreditare punti/bollini per quell'evento, leggere il saldo di un cliente e farlo riscattare premi o traguardi automaticamente, senza che tu o il tuo staff dobbiate aprire il pannello a ogni operazione.

L'unità accreditata è sempre quella della tua carta (punti o bollini), mai euro. La carta a punti legata alla spesa di uno scontrino è solo uno dei casi possibili, non l'unico: vedi Tipi di carta sotto per gli altri.

Cosa puoi fare con un'integrazione

• Far accreditare automaticamente punti/bollini per ogni evento che il tuo software esterno traccia — un acquisto in cassa, ma anche una partita giocata, una visita, una prenotazione: decidi tu cosa vale "1 unità" della carta, in base al tuo modello di tessera.
• Far leggere al software esterno il saldo e i premi/traguardi disponibili di un cliente.
• Far gestire il riscatto di premi e traguardi — incluse le carte a Traguardi (Progression) — direttamente dal software esterno.
• Far arrivare i movimenti nel negozio giusto, se hai più punti vendita (vedi Più punti vendita: il codice sede).
• Mostrare al software i vantaggi del cliente e far consegnare il regalo di compleanno (vedi Vantaggi del cliente).
• Annullare un movimento registrato per errore o reso (vedi Annullare un movimento).
• Far verificare al software se un movimento è arrivato, senza rimandarlo (vedi Controllare se un movimento è arrivato).
• Far vedere al software le carte della tua attività (quelle attive, con tipo e, se c'è, la data di fine) e, per un cliente che ne ha più di una, tutte le sue carte perché il software scelga su quale operare (vedi Se un cliente ha più carte).

Tutto questo avviene in tempo reale, sincronizzato con la tessera digitale del cliente (Apple Wallet / Google Wallet): il cliente vede subito l'aggiornamento sul telefono.

Eventuali promozioni attive sulla carta — moltiplicatore punti di un'happy hour, bonus win-back, bonus di compleanno — vengono applicate automaticamente anche alle operazioni fatte dal software esterno, esattamente come se l'operazione fosse fatta dal pannello (vale per qualunque tipo di carta, incluse quelle a Traguardi). Non serve configurare nulla lato integrazione: il software esterno indica solo i punti/bollini "base" dell'evento, gli eventuali bonus si aggiungono da soli.

Più punti vendita: il codice sede

Se la tua attività ha più negozi (piano ULTRA), ogni movimento che il software esterno registra può essere attribuito al negozio in cui è avvenuto, esattamente come le operazioni fatte dal pannello o dall'app: il cliente compare nel filtro per negozio, il movimento nel confronto tra negozi e nei messaggi per negozio.

1. Vai in Impostazioni → Negozi.
2. Nel modulo di creazione (o con la matita su un negozio esistente) compila «Codice nel tuo gestionale» con il codice con cui il tuo software indica quel punto vendita (per esempio 01, PV-VERONA). Ogni negozio ha un codice diverso, al massimo 64 caratteri; lasciarlo vuoto significa che quel negozio non è raggiungibile per codice.
3. Comunica lo stesso codice a chi configura il software: lo manda in ogni operazione (campo storeCode, dettagli nella documentazione per sviluppatori, scaricabile da questa pagina).

Tre cose da sapere:

• Se il software manda un codice che non corrisponde a nessun tuo negozio, Tesserando rifiuta l'operazione con un errore (STORE_NOT_FOUND) invece di registrarla senza negozio. Se vedi questo errore nelle "Ultime chiamate API", controlla che il codice scritto in Impostazioni → Negozi e quello configurato nel software siano identici.
• Se il software non manda nessun codice (campo assente), l'operazione funziona ma resta senza negozio, come prima. Attenzione: una stringa vuota ("") non vale come "nessun codice": viene rifiutata con 422 INVALID_PAYLOAD («storeCode must not be empty»). Solo un codice non vuoto che non corrisponde a nessun negozio dà STORE_NOT_FOUND. Con più punti vendita conviene sempre configurarlo.
• Se elimini un negozio, i movimenti che aveva restano nello storico e nei totali dell'attività come «Senza sede» (non sono persi, ma non sono più attribuibili a una sede: te lo dice anche l'avviso di conferma che mostra quanti movimenti resteranno così). Da quel momento il codice di quel negozio non corrisponde più a nessuna sede e il software riceve STORE_NOT_FOUND finché non aggiorna il codice con quello di un negozio esistente.

Vantaggi del cliente

Quando riconosce il cliente, il software esterno può leggere, insieme al saldo, tutto ciò che la tessera può dare in quel momento (solo ciò che si può davvero usare adesso):

• Coupon da usare (Win-Back «Ci manchi» e regalo di compleanno in modalità coupon), con i punti extra e la scadenza. Non si "usano" a parte: il prossimo accredito li incassa da solo e li somma ai punti di quel movimento, come già succede dal pannello e dall'app. Se la carta non accetta più accrediti (per esempio la campagna «La carta vale fino a…» è finita) i coupon non vengono mostrati, perché nessun accredito li incasserebbe. Lo stesso vale in Registra e nell'app.
• Promo compleanno: se oggi è il compleanno del cliente e sulla carta hai attivato la promo, il software vede il regalo (il testo che hai scritto nel campo «Premio» della carta, per esempio «Una fetta di torta») e può registrarne la consegna, una volta l'anno e solo quel giorno. È la stessa cosa del pulsante «Riscatta Premio» della pagina Marketing → Compleanni.
• Happy Hour in corso: il moltiplicatore attivo e quando finisce (lo applica da solo l'accredito). Come i coupon, non compare se la carta non accetta più accrediti.
• Scadenza dei punti, se la carta la usa.

Non ci sono sconti in euro o in percentuale. I vantaggi di Tesserando sono punti, un moltiplicatore e un regalo a testo libero: il software esterno non deve applicare nessuno sconto a nome di Tesserando. Se vuoi che il regalo di compleanno sia "20% di sconto", lo scrivi come testo del premio e lo applica il tuo operatore.

Il codice dei premi

Ogni premio, sia quello di una carta sia quello del catalogo premi, ha un codice che non cambia nemmeno se lo rinomini o ne cambi il costo. Lo trovi accanto al premio, con il pulsante di copia, nell'editor della carta e nel catalogo premi (Impostazioni → Configurazione App Scanner). I premi creati prima di questa novità hanno già ricevuto il loro codice.

Serve a chi configura il software esterno: il software lo usa per far ritirare quel premio e per sapere a cosa corrisponde nella tua cassa. Cosa vale un premio alla cassa (uno sconto, un articolo) lo decidi tu nel tuo software, collegandolo al codice: Tesserando ha premi in punti o bollini, non sconti in euro o in percentuale.

Quando arrivano i punti: in tempo reale

Un'operazione conta nel momento in cui Tesserando la riceve. Il software esterno non può indicare un orario passato. Per questo conviene che il software invii ogni accredito appena l'evento si chiude (una vendita, una visita, una partita, una prenotazione), non tutti insieme a fine giornata: un invio serale farebbe valutare Happy Hour e fine campagna all'ora dell'invio, non a quella dell'evento, e il saldo letto durante il giorno non conterrebbe ancora i movimenti non inviati.

Se compili il campo facoltativo operator (cassa o cassiere) o l'etichetta della tua integrazione, evita nomi che cominciano con Sistema (: quel prefisso è riservato ai movimenti automatici di Tesserando (regalo di compleanno, scadenze) che non contano nelle statistiche, e viene neutralizzato in Sistema - ….

Il saldo che il software legge può cambiare anche per movimenti fatti fuori dal suo controllo: punti aggiornati dal pannello (per esempio «Aggiorna punti da CSV»), addebiti per premi o punti scaduti, annulli registrati dal pannello. Se il software tiene una sua copia del saldo, non cercare di allinearla a posteriori: rileggila da Tesserando.

Controllare se un movimento è arrivato

Se il software non sa com'è andata una chiamata (per esempio per un errore di rete), può chiedere a Tesserando se quel movimento è arrivato, senza rimandarlo. Chiede per riferimento (quello che ha usato inviando il movimento), un movimento alla volta, e solo fra i movimenti fatti da quel software. La risposta dice se il movimento è arrivato (con il suo identificativo, i punti richiesti e quelli accreditati, il momento in cui Tesserando l'ha ricevuto e se poi è stato annullato), se è in coda in attesa che tu scelga la carta giusta di un cliente da collegare, oppure se non è arrivato: in quel caso può rimandarlo con lo stesso riferimento. Non esiste un elenco dei movimenti.

Annullare un movimento

Un accredito o un riscatto registrato per errore, oppure un reso, si annulla per intero:

• dal pannello: in Registro Scansioni c'è il pulsante Annulla accanto a ogni movimento. Lo vedono il titolare (su tutti i movimenti) e i responsabili di negozio (sui movimenti dei loro negozi); i dipendenti no. Puoi scrivere un motivo, per esempio «Reso»;
• dal software esterno: con la chiamata di annullo, solo sui movimenti fatti da quel software. Il tecnico individua il movimento con il transactionId restituito all'atto dell'operazione oppure con l'externalReference passato in origine; il regalo di compleanno consegnato si annulla solo con il suo transactionId (dettagli nella documentazione per sviluppatori, scaricabile da questa pagina).

Cosa succede:

• Annullo di un accredito: al cliente vengono tolti i punti o bollini di quel movimento, compresi eventuali bonus. Se aveva usato un coupon, il coupon torna disponibile fino alla sua scadenza. Se il cliente ha già speso quei punti, l'annullo non viene eseguito: prima annulla il riscatto che li ha usati (il saldo non va mai sotto zero). Sulle carte a Traguardi vale lo stesso per un traguardo già ritirato grazie a quei punti.
• Annullo di un riscatto: al cliente tornano i punti o bollini; sulle carte a Traguardi il traguardo torna da ritirare.
• Annullo del regalo di compleanno consegnato: il regalo torna disponibile.
• Il movimento resta nel Registro, segnato come annullato, e non conta più nelle statistiche (dashboard, confronto tra negozi, statistiche dell'app, Coach). La tessera nel wallet del cliente si aggiorna da sola.
• Solo entro 14 giorni da quando il movimento è stato registrato (14×24 ore esatte, decisione del titolare del 4 ottobre 2026). Oltre, l'annullo viene rifiutato: dal pannello il pulsante Annulla risulta spento con la spiegazione, dal software esterno la risposta è 409 REVERSAL_WINDOW_EXPIRED. Vale anche per le carte archiviate. Chi ripete un annullo già fatto riceve comunque «già annullato», anche dopo i 14 giorni.
• Un movimento si annulla una volta sola e sempre per intero: per un reso parziale annulla il movimento e registra l'accredito corretto. Se lo registra il software collegato, deve usare un riferimento nuovo: con quello del movimento annullato l'operazione risulta «già fatta» e non accredita (la risposta del retry dice anche reversed: true, così il software sa che quel movimento è stato annullato).
• Non si annullano gli addebiti automatici delle scadenze né il regalo di compleanno a punti dato dal sistema.

Cosa è cambiato dalla versione 1.9.1

Se la tua integrazione è già attiva, controlla l'elenco completo in «Cambi di comportamento dal 1.9.1» della documentazione per sviluppatori (scaricabile da questa pagina). In breve: validazione più stretta (422 INVALID_PAYLOAD per tipo non maiuscolo, importo non numerico, riferimento vuoto, data di nascita non YYYY-MM-DD), carte archiviate trattate come eliminate (409 CARD_ARCHIVED, mai trovate dalla ricerca per nome), found della ricerca che conta le persone e non le carte, e annullo possibile solo entro 14 giorni (409 REVERSAL_WINDOW_EXPIRED).

Tipi di carta

Il tipo di carta si imposta una volta sul modello di tessera (Dashboard → Le mie Card), non è configurabile dall'integrazione: il software esterno chiama sempre gli stessi endpoint (accredito/riscatto), il comportamento cambia in base al tipo collegato a quel cliente.

Sulle carte a Traguardi i bollini non vengono mai rimossi: né riscattando un traguardo, né in nessun altro momento. Se una carta ha traguardi a 3, 6 e 10 e il cliente arriva a 8 bollini senza aver ancora riscattato nulla, sia il traguardo a 3 che quello a 6 risultano riscattabili — in qualsiasi ordine, anche entrambi.

A livello di API, Punti e Bollini si comportano in modo identico (cambia solo l'etichetta mostrata al cliente, decisa dal merchant); le carte a Traguardi seguono invece una logica di riscatto diversa, con la soglia verificata automaticamente da Tesserando (un'integrazione non può far sbloccare un traguardo prima che il cliente lo raggiunga davvero) — i dettagli tecnici sono nella documentazione per sviluppatori (scaricabile da questa pagina).

Carte a tempo limitato ("La carta vale fino a…")

Dal modello di tessera (Dashboard → Le mie Card → scheda Logica, piani Pro e superiori) puoi dare alla carta un ultimo giorno di validità e, se vuoi, dei giorni extra in cui i premi si ritirano ancora: pensata per campagne a tempo, come un'estate o le feste. Per un'integrazione cambia questo:

Il software esterno può leggere lo stato della campagna prima di chiamare, dal campo campaign di GET /customers/{id} (dettagli nella documentazione per sviluppatori). Se l'attività scende a un piano senza questa funzione la data salvata non viene più applicata e tutto torna come prima. Gli eventi che Tesserando ha già messo in coda per un cliente ancora da collegare contano alla data in cui sono arrivati, non a quella in cui la coda viene svuotata.

Se il merchant archivia una carta

Se il merchant elimina una carta che ha già uno storico di movimenti, o che ha già tessere nel Wallet dei clienti, la carta non sparisce: viene archiviata, e archiviata vuol dire come eliminata. (Una carta senza storico e senza tessere nei Wallet viene cancellata davvero.) Per un'integrazione cambia questo, ed è un cambio di comportamento rispetto a prima, deciso dal titolare: chiamate che prima riuscivano ora no. Vale la pena avvisare chi gestisce il software esterno.

• Niente operazioni: POST /transactions, POST /customers, POST /customers/register-link e il riscatto del regalo di compleanno rispondono 409 CARD_ARCHIVED se la carta in gioco è archiviata (prima accreditavano o creavano la carta). Se il software ripete un'operazione già applicata prima dell'archiviazione (stesso externalReference) riceve alreadyApplied: true, non un errore.
• Stato del cliente: GET /customers/{id} risponde comunque, con points: 0 e il campo cardArchived: true (i punti residui del cliente sono decaduti). I premi e i traguardi hanno available: false; i vantaggi non ci sono: coupons è vuoto e birthdayPromo, happyHour e pointsExpiresAt sono null.
• Elenco delle carte: le carte archiviate non compaiono in GET /cards.
• Collegamento dei clienti: una carta archiviata non si collega più a nessun cliente (né per codice tessera, né per telefono o email). Se un cliente del software era già collegato a una carta archiviata, resolve lo tratta come un collegamento orfano: se il cliente ha un'altra carta attiva la ritrova e aggiorna il collegamento, altrimenti risponde ORPHANED. Finché resolve non viene richiamato, GET /customers/{id} e POST /transactions continuano a usare il collegamento salvato (cardArchived: true e 409 CARD_ARCHIVED): conviene richiamare resolve quando si riceve CARD_ARCHIVED.
• Annullo: POST /transactions/reverse resta ammesso, ma su una carta archiviata corregge solo le statistiche e il Registro del merchant: saldo, coupon e tessera non cambiano, e la risposta ha newPoints: 0 e cardArchived: true.
• Non è reversibile: per riaprire il programma il merchant crea una carta nuova e il software esterno la sceglie da quel momento in poi. Una carta che è la carta predefinita di un'integrazione non si può eliminare né archiviare finché il team non ne assegna un'altra.

Premi con scadenza ("Premi da riscattare entro N giorni")

Sempre dal modello di tessera (scheda Logica, piani Pro e superiori) il merchant può dare ai premi una scadenza: quando un cliente raggiunge un premio ha N giorni per ritirarlo, e ogni premio ha la sua scadenza. Per un'integrazione cambia questo:

• Punti e Bollini: se un premio non viene ritirato in tempo, Tesserando scala dal saldo il costo di quel premio (mai sotto zero). Il saldo letto da GET /customers/{id} è già aggiornato; il software esterno non deve fare nulla, ma sa che il saldo può calare senza una sua chiamata. Dopo l'addebito la scadenza dello stesso premio non riparte finché il cliente non fa un nuovo movimento (un accumulo o un riscatto), quindi un cliente inattivo non perde lo stesso premio ogni N giorni.
• Traguardi (Progression): il traguardo scaduto non è più riscattabile (409 MILESTONE_EXPIRED); il contatore non scende mai.
• La scadenza di ogni premio o traguardo è nel campo expiresAt di GET /customers/{id}.
• Il cliente riceve un promemoria sulla tessera 3 giorni prima e un avviso se il premio scade.
• Se l'attività scende a un piano senza questa funzione, la regola non viene più applicata.

Come richiedere un'integrazione

1. Vai su Dashboard → Impostazioni → Integrazioni esterne.
2. Clicca "Nuova richiesta" e compila il modulo:
   • Nome del software (obbligatorio, es. "Cassa XYZ", "Gestionale ristorante ABC")
   • URL/IP del server (opzionale: anche indicativo, il team Tesserando lo verifica e può completarlo in fase di approvazione)
   • Note (opzionale): a cosa serve l'integrazione, eventuali dettagli utili al team che la approva — ad es. se il software gestisce più punti vendita, se vuoi limitare i clienti trovabili a un solo tipo di tessera, se vuoi disattivare l'invito automatico via email (vedi sotto)
3. Clicca "Invia richiesta". Lo stato passa a "In attesa di approvazione".

Cosa succede dopo la richiesta

Il team Tesserando revisiona la richiesta e configura i parametri tecnici e di sicurezza dell'integrazione — questi non sono modificabili autonomamente dal pannello: se in futuro vuoi cambiarli, contatta il supporto indicando l'integrazione interessata. In particolare il team imposta:

• L'eventuale allowlist di rete (vedi sezione Sicurezza).
• Se l'integrazione deve cercare i clienti solo tra un tipo di tessera specifico (utile se hai più programmi fedeltà/tessere e vuoi che quel software interagisca solo con uno di essi) oppure tra tutte le tue tessere.
• Se mandare automaticamente un'email di invito alla registrazione quando il software esterno passa l'email di un cliente che non ha ancora una tessera Tesserando — attivo per default, salvo richiesta contraria nelle note della richiesta.
• Se abilitare le due funzionalità di identità esterna (spente per default, vedi sotto): far usare Tesserando come login/identità del software esterno.

Quando l'integrazione viene approvata:

• Lo stato passa ad "Attiva".
• Viene generata una API key dedicata: copiala e conservala subito in un posto sicuro (un password manager, le note protette del tuo gestionale, ecc.). Resta sempre rivisualizzabile dal pannello (icona "occhio" per rileggerla, "copia" per copiarla senza leggerla) finché l'integrazione è attiva. Il pannello mostra comunque il prefisso (es. tsk_live_ab12cd...), utile per verificare con chi sta integrando quale key sta usando.
• Quella key è il "lasciapassare" che andrà configurato nel software esterno per autenticare le chiamate verso Tesserando.

Se la richiesta viene rifiutata, vedrai il motivo indicato dal team Tesserando direttamente nella card dell'integrazione, e potrai inviarne una nuova.

Configurare la API key nel software esterno

La persona che configura il tuo POS/gestionale deve impostare, in tutte le chiamate verso Tesserando, l'header:

Authorization: Bearer <la-tua-api-key>

verso l'indirizzo fisso https://www.tesserando.it/api/external/v1 (uguale per tutti, non cambia da cliente a cliente).

⚠️ Attenzione al www.: l'indirizzo senza www rimanda automaticamente a quello con www, ma in quel passaggio quasi tutti i programmi perdono per strada la API key e Tesserando risponde "non autorizzato". Se chi configura il software ti dice che la key non funziona, il primo controllo da fare è proprio questo.

Il riferimento tecnico completo (endpoint disponibili, formato delle richieste e delle risposte, codici di errore) è nella documentazione per sviluppatori (API v1), scaricabile da questa pagina e pensata per chi sviluppa o configura il software esterno — condividilo con chi si occupa dell'integrazione tecnica.

Gestire un'integrazione attiva

Dalla card dell'integrazione, in Impostazioni → Integrazioni esterne, puoi:

Se l'attività viene sospesa (pagamento non riuscito oltre i giorni di tolleranza, o sospensione decisa dal team Tesserando), tutte le chiamate del software esterno vengono rifiutate con errore TENANT_SUSPENDED finché l'attività non viene riattivata — non è un problema del software né della key. Se la sospensione è per un pagamento non riuscito o per un abbonamento finito, il titolare riattiva dalla pagina dedicata (saldando la fattura). Se invece è una sospensione decisa dal team Tesserando, il titolare non può toglierla da solo, neppure pagando: la toglie solo il team ([email protected]).

Collegare i clienti del software esterno alle tessere Tesserando

Quando il software esterno comunica un cliente (in genere tramite telefono o email), Tesserando cerca automaticamente la tessera corrispondente:

• Trovata una sola tessera corrispondente → il collegamento si crea da solo, nessuna azione richiesta.
• Trovate più tessere corrispondenti → il collegamento resta in sospeso e compare nella sezione "Collegamenti da risolvere" della pagina Integrazioni esterne. Per ciascun cliente esterno vedi i candidati proposti con nome, email, telefono, numero di tessera e punti attuali, e — se il software esterno ha già provato ad accreditare punti o un riscatto per quel cliente mentre era in sospeso — quante operazioni sono in attesa: scegli il candidato giusto cliccando "Collega", oppure scarta tutti i candidati con "Nessuno di questi (rifiuta)". Attenzione: rifiutare elimina il tentativo di collegamento — non lo segna semplicemente come "rifiutato" — quindi se il software esterno invia di nuovo lo stesso cliente, Tesserando riparte da zero la ricerca (utile se nel frattempo, ad esempio, il cliente giusto si è registrato); le eventuali operazioni in attesa per quel cliente vengono scartate insieme al tentativo di collegamento, perché non c'è più una tessera a cui applicarle.
• Nessuna tessera trovata, ma è disponibile un'email → se l'invito automatico è attivo per quell'integrazione (vedi sopra; attivo per default), al cliente viene inviata un'email di invito a registrarsi; il collegamento si completa solo se il cliente porta a termine la registrazione. Lo stesso cliente non viene invitato più di una volta ogni 7 giorni, e per sicurezza c'è un tetto di 20 email di invito al giorno per integrazione: oltre quella soglia i clienti successivi risultano semplicemente "non trovati" e nessuna email parte, fino al giorno dopo. Un invito che non riesce a partire (per esempio il servizio email non è raggiungibile) non consuma il tetto. L'invito non parte nemmeno se la campagna della tessera predefinita è già chiusa: porterebbe a una pagina "Iscrizioni chiuse". Conta solo quando il software esterno ti presenta molti clienti nuovi tutti insieme (es. la prima importazione): in quel caso l'invio si distribuisce su più giorni, oppure si usa la modalità con link di registrazione descritta più sotto, che non ha questo tetto.

Controlla periodicamente la sezione "Collegamenti da risolvere": finché un collegamento resta in sospeso, il software esterno non può leggere il saldo di quel cliente (la lettura risponde con lo stato di attesa PENDING_REVIEW, non con il saldo) e gli accrediti/riscatti rispondono con un errore "non collegato". Gli accrediti/riscatti inviati nel frattempo non vengono persi: Tesserando li mette in attesa e li applica automaticamente non appena scegli la tessera giusta, senza che il software esterno debba rifare nulla. Eventuali promozioni attive (happy hour, bonus win-back/compleanno) non vengono però applicate alle operazioni rimaste in attesa, per evitare di calcolarle sul giorno sbagliato — solo i punti/bollini "base" indicati dal software esterno. Risolvere il collegamento appena possibile resta comunque la cosa migliore: il cliente vede il saldo aggiornato sulla tessera solo a quel punto.

Usare Tesserando come identità/login del software esterno

Alcuni software esterni vogliono usare la tessera Tesserando del cliente come identità unica, non solo per accreditare punti — ad esempio per far accedere il cliente al proprio gestionale (login) senza fargli creare un account separato. Per questo esistono due funzionalità aggiuntive e opzionali, spente di default, da richiedere esplicitamente al supporto (non sono nel modulo di richiesta standard):

• Ricerca cliente per nome/cognome, con email (allowIdentityLookup): il software esterno può chiedere a Tesserando "esiste un cliente con questo nome e cognome?" e, se la risposta è univoca, ricevere in cambio la sua email — tipicamente per mandargli un codice di accesso temporaneo (OTP) gestito interamente dal software esterno (Tesserando non manda l'OTP, solo l'indirizzo a cui mandarlo). È l'unica funzionalità delle integrazioni esterne che espone l'email di un cliente: per questo è opt-in, protetta da un limite di richieste dedicato (per evitare che qualcuno provi a "sondare" la tua rubrica clienti su cognomi comuni), e se ci sono più clienti con lo stesso nome e cognome l'email non viene restituita finché il software esterno non la indica lui stesso per confermare di quale dei due sta parlando. Se lo stesso cliente ha più carte (stesso nome, cognome ed email), conta come una sola persona: la risposta elenca le sue carte attive, vedi la sezione qui sotto.

• Creazione carta con anagrafica già raccolta (allowCustomerCreation): il software esterno può creare direttamente una tessera Tesserando per un cliente di cui ha già raccolto nome, cognome, contatti e consenso (tipicamente dopo la firma di un modulo/liberatoria sul suo sistema), senza passare dal normale giro "email di invito → il cliente si registra da solo". Tesserando registra una prova tecnica del consenso fornita dal software esterno (un riferimento univoco al modulo firmato, non il documento stesso) per motivi di responsabilità.

  Lo stesso permesso abilita anche una seconda modalità, più morbida, che il tuo sviluppatore può scegliere al posto della creazione diretta: invece di creare la tessera "alla cieca", il software esterno chiede a Tesserando un link alla pagina di registrazione e ci porta il cliente (sul suo schermo, sul totem, sul suo sito). Il cliente vede la pagina Tesserando, conferma, e si ritrova subito i pulsanti per aggiungere la tessera a Apple/Google Wallet — invece di scoprire più tardi di avere una tessera che non ricorda di aver chiesto. Se l'integrazione ha una tessera predefinita, il link porta solo a quella tessera (il cliente non può iscriversi a un'altra). Il link dura 7 giorni e non consuma il tetto giornaliero delle email di invito, perché non manda nessuna email: è il software esterno a mostrarlo al cliente. Se quel cliente risulta già collegato a una tessera, non serve nessun link e il software lo riconosce da solo. La pagina può arrivare già compilata con i dati che il software esterno ha raccolto, così al cliente resta solo da confermare — ma va chiesto esplicitamente a chi sviluppa l'integrazione: è un passaggio in più dalla sua parte, e senza quello il cliente si trova il modulo vuoto e ridigita tutto. Consigliata quando il cliente è fisicamente davanti (accoglienza, cassa, iscrizione a un corso); la creazione diretta resta la scelta giusta quando il consenso è già stato firmato su carta o nel gestionale e il cliente non è raggiungibile in quel momento.

  In entrambe le modalità, se l'email o il telefono corrispondono già a un'altra tessera dello stesso tipo (lo stesso programma fedeltà su cui l'integrazione è configurata), la creazione viene rifiutata esplicitamente (nessun collegamento automatico "a sorpresa"): il caso compare tra i duplicati in Impostazioni → Pulizia Duplicati, da risolvere a mano. Lo stesso cliente può invece avere regolarmente una tessera su un tuo altro programma fedeltà: quello non è considerato un duplicato. E se per quel cliente c'è un collegamento ancora in sospeso nella sezione "Collegamenti da risolvere", la creazione viene rifiutata finché non scegli tu la tessera giusta — così una nuova tessera non scavalca mai in silenzio quella che stavi per collegare.

Attivando queste funzionalità stai autorizzando il software esterno a ritrovare e creare tessere per conto tuo: valutalo con la stessa attenzione con cui valuteresti dare le chiavi del pannello clienti a quel software. Il numero di tessera (seriale) resta comunque un metodo di aggancio sempre disponibile, utile come ripiego se il cliente non riceve l'eventuale codice di accesso: basta farsi dire/mostrare il numero stampato sulla tessera digitale.

Se un cliente ha più carte

Un cliente può avere più di una tessera presso di te (per esempio la carta fedeltà e una carta a traguardi). Il software esterno non deve indovinare quale usare: può scegliere.

• Elenco delle carte della tua attività. Il software può chiedere a Tesserando quali carte sono attive: per ciascuna riceve nome, tipo (punti, bollini o traguardi), se è quella predefinita dell'integrazione, l'eventuale fine della campagna («La carta vale fino a…») e, per le carte a Traguardi, i traguardi. Le carte archiviate non compaiono. Non è un dato dei tuoi clienti e non richiede nessuna attivazione speciale.
• Le carte di un cliente. Con la ricerca per nome e cognome (se l'hai attivata, vedi sopra), quando il cliente è uno solo la risposta contiene anche l'elenco di tutte le sue carte attive nella tua attività, ciascuna con il proprio numero di tessera. Sono considerate dello stesso cliente le carte con lo stesso nome, cognome ed email. L'elenco non contiene saldi né altri dati personali. Se più clienti hanno lo stesso nome e cognome, l'elenco non viene mostrato finché il software non conferma con l'email, come già avviene per l'email stessa. Una carta archiviata è come eliminata: non compare nell'elenco e, se un cliente ha solo carte archiviate, la ricerca non lo trova (e l'email non esce).
• Il programma predefinito. Se la tua integrazione ha un programma fedeltà predefinito, la ricerca trova i clienti solo tra le carte di quel programma, ma poi l'elenco mostra anche le altre carte attive dello stesso cliente, con quella predefinita segnalata. Spetta al software decidere se usarle.
• Una carta alla volta. Ogni cliente del software è collegato a una carta: se vuole gestirne due dello stesso cliente, il tuo sviluppatore le tratta come due collegamenti distinti.

Sicurezza

Ogni integrazione è protetta da due livelli:

1. API key univoca: è la protezione principale. Senza la key corretta nessuna chiamata viene accettata.
2. Allowlist di rete (opzionale, configurata dal team Tesserando): in fase di approvazione, su richiesta o di propria iniziativa, il team Tesserando può limitare le chiamate a un insieme di indirizzi IP o a un dominio autorizzato (es. quelli del server del tuo gestionale). Questo è un livello di protezione aggiuntivo: se non è configurato, l'integrazione resta comunque protetta dalla sola API key — non è un problema lasciarlo non configurato.

Se sospetti che la tua API key sia stata compromessa (es. condivisa per errore, software violato), rigenerala immediatamente dal pannello: la vecchia key viene invalidata all'istante, senza bisogno di assistenza.

Domande frequenti

Quante integrazioni posso attivare? Non c'è un limite nel pannello. Ogni integrazione richiede comunque l'approvazione del team Tesserando.

Posso collegare più software esterni insieme? Sì. Ogni integrazione è indipendente, con la propria API key e la propria configurazione.

Se passo a un piano inferiore a ULTRA, perdo le integrazioni? No, restano configurate ma le chiamate API vengono rifiutate finché non torni su ULTRA. Basta fare l'upgrade per riattivarle, senza dover ricreare nulla.

Il software esterno può vedere dati di altri negozi/account? No. Ogni API key è legata in modo univoco al tuo account: tutte le chiamate restano isolate ai tuoi dati.

Il software esterno può applicare sconti o coupon in euro di Tesserando? No, perché non esistono: i vantaggi di Tesserando sono punti (anche i coupon Win-Back e compleanno sono punti extra), un moltiplicatore Happy Hour e il regalo di compleanno a testo libero. Il software può leggere quali ne ha il cliente e farli incassare o consegnare, ma non c'è uno sconto da applicare in fattura.

Il codice a barre/QR della tessera contiene il codice cliente del mio gestionale? No. Il QR contiene solo il numero di tessera di Tesserando (16 cifre casuali). Il codice del tuo gestionale (per esempio a 13 cifre) si associa una volta sola alla prima scansione, poi basta il tuo codice: chi sviluppa l'integrazione trova la procedura nel documento tecnico, sezione «Esempio di flusso».

Il software esterno può accreditare punti in euro invece che in punti/bollini? No: ogni importo passato dal software esterno è sempre nell'unità della tua carta (punti o bollini), mai in euro. È il software esterno a doversi occupare di convertire l'evento (una spesa, ma anche una visita, una partita giocata, ecc.) in punti secondo la tua regola, prima di chiamare Tesserando. L'importo di una singola operazione è un numero intero, da 1 a 1.000.000.

La mia attività non vende a scontrino: posso comunque usare un'integrazione? Sì. L'integrazione non presuppone un acquisto: qualsiasi software che tenga traccia di un evento ripetibile (partite giocate, ingressi, prenotazioni, sedute) può accreditare punti o bollini per quell'evento. Per le attività dove ha senso premiare più tappe di un percorso invece di un catalogo premi a scelta (es. un campo softair con traguardi a 3, 6 e 10 partite, ciascuno con un premio diverso, senza mai perdere il conteggio), usa un modello di tessera Traguardi (Progression) — vedi Tipi di carta.

Se il mio software invia per errore la stessa operazione due volte, il cliente riceve punti doppi? Solo se il software esterno non usa un riferimento univoco per ogni operazione (externalReference, lato tecnico). Verifica con chi configura l'integrazione che il software lo stia usando: in quel caso un invio duplicato viene riconosciuto e ignorato automaticamente da Tesserando, e il saldo del cliente non si muove una seconda volta. Attenzione al caso opposto: il riferimento va dato a ogni operazione, non a ogni vendita. Se il software usa lo stesso numero (per esempio quello dello scontrino) sia per l'accredito sia per il ritiro di un premio sulla stessa vendita, la seconda operazione viene presa per un doppione e non viene eseguita. Una raccomandazione per chi sviluppa: quando si ritenta un'operazione, va rimandata identica (stesso riferimento e stessi importi) — un ritentativo con lo stesso riferimento non accredita mai due volte, e Tesserando risponde "già applicato" anche se nel frattempo il saldo è cambiato o la campagna della tessera è finita (prima, in quei casi, il ritentativo di un ritiro già eseguito riceveva un rifiuto). Lo stesso vale per il codice sede: se il riferimento è già un movimento applicato, il ritentativo risponde «già applicato» anche se nel frattempo il storeCode è cambiato o il negozio è stato eliminato (con un riferimento nuovo il codice sede si controlla come sempre). Il riferimento deve essere un testo non vuoto di al massimo 128 caratteri.

Quanto impiega il team Tesserando ad approvare una richiesta? Per i tempi di approvazione, contatta il supporto: variano in base al carico e alla complessità della configurazione richiesta (es. allowlist di rete, scoping su un tipo di tessera).

Il mio software esterno può far accedere i clienti con la loro tessera Tesserando, senza farli registrare un account separato? Sì, tramite le due funzionalità opzionali descritte in Usare Tesserando come identità/login del software esterno: ricerca cliente con email (per un login via codice temporaneo gestito dal software esterno) e creazione della tessera con anagrafica già raccolta — quest'ultima o creando direttamente la tessera, o portando il cliente su un link alla pagina di registrazione Tesserando, a scelta di chi sviluppa l'integrazione. Sono spente di default: vanno richieste esplicitamente al supporto, che valuta l'attivazione insieme a te vista l'implicazione sui dati dei tuoi clienti.