Creare una chiave API

Un'API è una porta sul retro del Suo account. Dove Lei clicca nella Sua gestione, un altro programma può passare da quella porta e recuperare direttamente i Suoi dati: i prodotti, i prezzi, i posti liberi, le vendite.

È utile quando vuole, per esempio:

• mostrare sul Suo sito quali visite guidate hanno ancora posto questa settimana;
• far recuperare automaticamente i dati di fatturato al Suo commercialista;
• collegare l'elenco dei soci a un altro programma.

Chi realizza l'integrazione — il Suo webmaster, il Suo gestionale contabile, un amico che programma — ha bisogno di due cose: l'indirizzo e una chiave. Le trova entrambe in un'unica schermata.

Da sapere: l'API fa parte di un piano superiore. Su un piano più piccolo Accesso API non compare nel Suo menu; se arriva comunque sulla schermata, vede una spiegazione e un pulsante Vai all'abbonamento, non le chiavi.

Dove andare

Nel menu a sinistra apra Impostazioni → Accesso API. Solo il ruolo Proprietario vede questa schermata.

In alto ci sono due schede: Chiavi e Webhook. Questo articolo riguarda la prima; i webhook sono spiegati in Configurare i webhook.

Nella scheda Chiavi vedrà tre blocchi:

1. Il collegamento — l'indirizzo e la descrizione tecnica. Sono i due dati da consegnare a chi realizza l'integrazione.
2. Nuova chiave — qui ne crea una.
3. Chiavi — quelle che esistono già e quando sono state usate l'ultima volta.

Creare una chiave

Passo 1. Dia un nome. Non il Suo nome, ma quello di ciò che sta dall'altra parte: «il nostro sito», «contabilità», «newsletter». Il nome serve solo a Lei. Apparirà nell'elenco, accanto a «ultimo utilizzo». Fra un anno saprà ancora quale chiave corrisponde a cosa — e quale può revocare tranquillamente.

Passo 2. Spunti cosa può fare la chiave. Sotto Cosa può fare questa chiave? trova i permessi, in gergo scope. Lettura è già spuntato:

Permesso	Cosa può fare il programma
Lettura	Consultare catalogo, prezzi, posti liberi, sconti, buoni regalo e abbonamenti annuali — e anche i Suoi ordini, biglietti, scansioni e acquirenti, con nome e indirizzo e-mail.
Scrittura	Creare ordini, farli pagare, annullarli e rimborsarli, richiedere una fattura, annullare e reinviare biglietti, registrare gli ingressi, ed emettere, utilizzare o rinnovare buoni regalo e abbonamenti annuali.
Webhook	Far sì che inviamo una notifica a un Suo indirizzo non appena accade qualcosa.
Pagato esternamente	Segnare un ordine come pagato senza fornitore di pagamento (bonifico, contanti). Funziona solo insieme a Scrittura.

Spunti solo ciò che serve davvero. Un sito che deve solo mostrare i posti liberi si accontenta di Lettura. Se quella chiave riceve anche Scrittura, un errore nel sito può creare o rimborsare ordini che Lei non vuole.

Sia particolarmente parsimonioso con Pagato esternamente: chi ce l'ha può emettere biglietti senza che entri denaro. Lo dia solo a una cassa o a una contabilità che gestisce Lei stesso.

Deve spuntare almeno un permesso. Una chiave senza permessi non potrebbe fare nulla, ed è il tipo di errore più difficile da individuare — per questo la schermata la rifiuta.

Passo 3 (facoltativo). Imposti una data di scadenza. Se lascia vuoto il campo Scade il (facoltativo), la chiave resta valida finché non la revoca. Se indica una data, funziona ancora quel giorno e poi si ferma da sola. La data deve essere nel futuro. Comodo quando lascia guardare qualcuno solo per un periodo: non dovrà ricordarsene dopo.

Passo 4 (facoltativo). Chiave di test. Spunti Chiave di test (sandbox) per chi sta ancora sviluppando. Una chiave così legge gli stessi dati di una normale. Se ha anche Scrittura, crea solo ordini di prova: non passano mai dal Suo fornitore di pagamento, non contano nel Suo fatturato e vengono eliminati automaticamente dopo 24 ore. Un errore di battitura non può quindi causare un vero pagamento o un vero rimborso. Una chiave di test non può configurare webhook.

Attenzione: finché non viene eliminato, un ordine di prova occupa comunque un posto reale, e l'e-mail di conferma parte davvero. Faccia provare con un prodotto o una fascia oraria creati apposta.

Riconosce una chiave di test dall'inizio: comincia con pv_test_ invece di pv_live_.

Passo 5. Clicchi su «Crea chiave».

La chiave si vede una sola volta

Subito dopo la creazione la chiave compare in un riquadro. È l'unica volta che la vedrà.

La copi adesso e la consegni subito. Se ricarica la pagina, sparisce.

Non è un fastidio ma una protezione. Noi non conserviamo la Sua chiave: teniamo solo una specie di impronta, che ci permette di riconoscerla ma non di rileggerla. Se qualcuno arrivasse un giorno al nostro database, non avrebbe comunque accesso ai Suoi dati. Il rovescio della medaglia è che nemmeno noi possiamo più mostrargliela.

L'ha persa? Nessun problema: ne crei una nuova e revochi la vecchia.

Tratti una chiave come una chiave

Chi ha la chiave può fare ciò che vi è spuntato sopra — senza password e senza aprire il Suo account. Quindi:

• non la mandi in una normale chat di gruppo dove resterà visibile;
• non la metta nel codice visibile del Suo sito;
• dia a ogni integrazione una chiave propria. Così potrà revocarne una senza rompere le altre, e nell'elenco vedrà quale è ancora in uso.

Revocare una chiave

Nell'elenco clicchi su Revoca accanto alla chiave e confermi.

Da quel momento non funziona più. La riga resta nell'elenco con la dicitura «Revocata»: potrà sempre ricostruire quale integrazione esisteva e quando.

Revochi una chiave quando:

• smette di usare lo strumento che la utilizzava;
• l'ha persa o gira da qualche parte;
• se ne va qualcuno che la possedeva.

La creazione e la revoca di una chiave finiscono anche nel registro attività di chi l'ha fatto (Impostazioni → Collaboratori, quella persona, scheda Attività), con il momento. La chiave stessa non vi compare mai.

Quando è stata usata l'ultima volta?

Sotto ogni chiave è indicato quando è stata usata l'ultima volta. Se da mesi dice «non ancora usata», probabilmente non c'è più nulla collegato. La revochi pure — una porta che nessuno usa non deve restare aperta.

Cosa consegnare a chi realizza l'integrazione

Tre cose:

1. l'indirizzo API dal blocco Il collegamento;
2. la descrizione tecnica (il link che termina con openapi.json) — uno sviluppatore vi trova subito tutto ciò che è possibile;
3. la chiave stessa e i permessi che ha spuntato.

Non gli serve altro.

E poi?

Ha l'indirizzo e la chiave. Quello che viene dopo è lavoro di chi costruisce l'integrazione — e a lui inoltra il portale per sviluppatori. Lì c'è il riferimento completo, con esempi di codice in quattro linguaggi e un file che si importa direttamente in Postman o Insomnia.

• Che cos'è un'API, e Le serve? — se prima vuole sapere di che cosa si tratta.
• Webhook — far sapere al Suo sito che è stato venduto qualcosa, senza che debba continuare a chiederlo.
• Configurare i webhook — la scheda Webhook di questa stessa schermata, passo dopo passo.