Collegare i vostri strumenti con l'API
L'API consente a un'applicazione esterna di accedere ai dati della vostra organizzazione in modo programmatico: iscritti, calendari, prenotazioni e fatturazione. Si attiva con due clic e si protegge tramite una chiave, un elenco di indirizzi autorizzati e un monitoraggio dei consumi.
Capire se l'API fa per voi
L'API è destinata a uno sviluppatore, non a un responsabile di organizzazione. Serve a far dialogare il vostro account con un software che fate scrivere o configurare: un sito web su misura, uno strumento di contabilità, uno schermo informativo realizzato in casa, un collegamento verso un altro sistema.
Per le esigenze più comuni — recuperare l'elenco degli iscritti, aggiornare abbonamenti in blocco, trasmettere dei dati al consiglio direttivo — i moduli di importazione, esportazione e i rapporti rispondono senza scrivere una riga di codice.
L'API è proposta in versione beta: il suo funzionamento può ancora evolvere.
Attivare l'API e recuperare la vostra chiave
- Andate in Amministrazione›Impostazioni›API BETA.
- Attivate Attivare il modulo API poi cliccate su Salva.
- La vostra Chiave API viene visualizzata: copiatela con il pulsante Copia e trasmettetela unicamente allo strumento che state collegando.
La chiave si trasmette nell'intestazione HTTP X-API-Key di ogni richiesta. Le chiamate avvengono obbligatoriamente in HTTPS; nessuna richiesta non cifrata viene accettata.
Proteggere la chiave
Vale la pena ricordare alcune buone abitudini allo strumento o al fornitore che la utilizza:
- non depositare mai la chiave in un repository di codice; conservarla in un file di configurazione esterno al repository oppure in un gestore di segreti;
- limitare gli indirizzi autorizzati appena lo strumento effettua le chiamate da un server fisso;
- rigenerare la chiave al minimo dubbio — pubblicazione accidentale, fuga di log, fine dell'incarico di un fornitore.
Il pulsante Rigenerare chiede una conferma, poi invalida immediatamente la vecchia chiave. Tutte le applicazioni che la utilizzavano cessano di funzionare finché non ricevono la nuova: avvisatele prima di cliccare.
Limitare l'accesso per indirizzo IP
Attivate la Restrizione per indirizzo IP: vengono accettate solo le richieste provenienti dagli indirizzi che elencate, entro il limite di 10 indirizzi IPv4. Inserite ciascun indirizzo poi confermate con Aggiungi; il vostro indirizzo attuale è mostrato sullo schermo per aiutarvi.
È la protezione più efficace, e la più spesso trascurata: anche se divulgata, una chiave limitata all'indirizzo del vostro fornitore resta inutilizzabile altrove.
Monitorare i consumi
La schermata mostra in continuo ciò che consuma la vostra chiave:
- Utilizzo questo minuto e Utilizzo oggi, ciascuna rapportata al proprio limite quando un limite è configurato;
- Statistiche di utilizzo: Questa settimana, Questo mese, Totale e Ultima richiesta.
Oltre i limiti indicati, le richieste supplementari vengono temporaneamente rifiutate. Un contatore che sfiora permanentemente il proprio tetto segnala in genere uno strumento mal configurato, che richiede in continuazione gli stessi dati invece di metterli in cache.
La data dell'ultima richiesta è utile nel senso opposto: una chiave attivata ma mai chiamata da mesi è una chiave da disattivare.
Scoprire le possibilità dell'API
La documentazione completa, con i parametri e degli esempi di chiamata, è visualizzata in fondo alla schermata del modulo. A grandi linee:
- Utenti: è l'unica risorsa modificabile. Potete elencare, consultare, creare, modificare ed eliminare degli account.
- Configurazione: abbonamenti, profili, gruppi e categorie di età si consultano, ma si configurano unicamente dall'applicazione.
- Prenotazione: calendari, fasce orarie disponibili, prenotazioni ed etichette si consultano.
- Fatturazione: conti di fatturazione, ordini e pagamenti si consultano.
