Che cos’è un’API, e Le serve?

Incontra queste tre lettere nel preventivo del Suo webmaster, o nell’elenco delle funzioni del Suo gestionale contabile: API. Questo articolo spiega di che cosa si tratta, senza che Lei debba saper programmare.

La risposta breve

Un’API è una porta sul retro del Suo account.

Dove Lei clicca nella schermata di gestione per vedere quanti posti sono ancora liberi, un altro programma può chiedere esattamente la stessa cosa da quella porta — senza nessuno davanti a uno schermo. Dietro entrambe le porte ci sono gli stessi dati: i Suoi prodotti, i Suoi prezzi, i Suoi posti liberi, le Sue vendite.

La differenza è chi entra. Dalla porta principale entra una persona con un mouse. Dalla porta sul retro entra un programma con una chiave.

Quando Le serve?

Solo quando vuole qualcosa che la schermata di gestione non fa. Per esempio:

• mostrare sul Suo sito quali visite hanno ancora posto questa settimana, nella Sua grafica, con numeri corretti in quel preciso momento;
• lasciare che il commercialista si serva da solo, così recupera lui il fatturato del mese scorso invece di ricevere ogni mese un export da Lei;
• uno schermo nell’atrio che mostra quale fascia oraria sta per iniziare;
• vendere da un programma che già usa, senza dover prima entrare nella schermata di gestione.

E quando non Le serve? Quando può cliccarlo. Costruire un’integrazione costa tempo e manutenzione; esportare un elenco due volte al mese costa due minuti. Scelga la prima solo quando la seconda comincia a essere d’intralcio.

Attenzione: non deve costruirlo Lei. Chi lo costruisce — il Suo webmaster, il fornitore del Suo gestionale, qualcuno del consiglio che sa programmare — ha bisogno solo di due cose: l’indirizzo e una chiave. Entrambi li trova nella Sua schermata di gestione.

Che cosa consegna esattamente

Apra Impostazioni → Accesso API (questa schermata è riservata al titolare dell’organizzazione). Nella scheda Chiavi ci sono tre cose che può consegnare:

1. L’indirizzo. Una riga di testo. È lì che parla l’altro programma.
2. La descrizione tecnica, il link che finisce con openapi.json. Con quello uno sviluppatore vede a colpo d’occhio tutto ciò che è possibile: quali dati esistono, come si chiedono, che cosa torna.
3. Una chiave, che crea Lei stesso. Veda Creare una chiave API.

Non gli serve altro, e non deve dare altro — di sicuro non la Sua password.

Che cosa può e non può una chiave

Alla creazione spunta che cosa la chiave può fare. Non è una formalità:

• Lettura — consultare tutto, non cambiare nulla. È ciò di cui ha bisogno la maggior parte delle integrazioni. Attenzione: «tutto» comprende anche i Suoi ordini e i Suoi 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 — indicare dove possono arrivare i messaggi. Veda Webhook.
• Pagato esternamente — segnare un ordine come pagato senza che sia intervenuto un fornitore di pagamento (bonifico, contanti). Lo dia solo a una cassa o a una contabilità che gestisce Lei stesso: chi può farlo, può emettere biglietti senza che entri denaro.

Dia a ogni integrazione una chiave propria, con solo ciò che le serve. Così può revocarne una senza rompere il resto, e vede nell’elenco quale è ancora in uso.

Una chiave, del resto, non è una password che apre il Suo account: dà solo quello che vi è spuntato e appartiene a una sola organizzazione. Anche se resta in giro da qualche parte, nessuno può usarla per consultare i dati di altri.

Prima provare senza rischi

Accanto a una chiave normale può creare una chiave di prova. Legge esattamente gli stessi dati. Se può anche scrivere, 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. Una chiave di prova non può configurare webhook.

È fatta esattamente per questo momento — qualcuno che sta provando e non è ancora sicuro di quello che fa. Lasci che il Suo webmaster cominci con una chiave di prova e passi all’altra solo alla fine.

Una cosa da sapere: anche un ordine di prova occupa un posto reale (finché non viene eliminato), e l’e-mail di conferma parte davvero. Faccia quindi provare il Suo webmaster con un prodotto o una fascia oraria creati apposta.

E se va storto?

Revochi la chiave. Clicchi su Revoca nell’elenco e da quel momento non funziona più. L’integrazione si ferma, i Suoi dati restano. Non esiste nessuna situazione in cui una chiave possa fare qualcosa che Lei non possa fermare con un clic.

Quanto costa

L’API fa parte di un piano più grande. Su un piano più piccolo Accesso API non compare nel Suo menu. Se arriva comunque su quella schermata, vede una spiegazione, in quale piano si trova l’API e un pulsante Vai all'abbonamento — nessuna chiave. Che cosa c’è in quale piano sta nella pagina dei prezzi di Passavo.

Per saperne di più

• Creare una chiave API — la schermata stessa, passo per passo.
• Webhook — far sapere al Suo sito che è stato venduto qualcosa, senza che debba continuare a chiederlo.
• Configurare i webhook — la schermata stessa, passo dopo passo.
• Il portale per sviluppatori — per chi costruisce l’integrazione.