Integrazioni

Chiavi API, widget di prenotazione e ambiti

Chiavi API

Una chiave API permette a un altro sito o programma di parlare con il tuo account FullClass. Te ne serve una per mettere il widget di prenotazione sul tuo sito, o per collegare uno strumento come Zapier. Se usi solo la tua pagina di prenotazione FullClass, non te ne serve nessuna. Ce ne sono di due tipi, e vanno in posti diversi.

Prefisso	Dove si usa	Come è protetta
`pk_` Pubblica	Browser, widget di prenotazione, inserimenti e app per dispositivi mobili.	È limitata dai suoi ambiti (cosa può fare) e da un elenco di origini consentite (quali siti possono usarla). È al sicuro nel codice del tuo sito, purché entrambi restino ristretti.
`sk_` Segreta	Solo nel codice del server.	Trattala come una password. Non metterla mai nel codice di un sito, in archivi di codice pubblici, in screenshot, nei ticket di assistenza o nei costruttori di siti. Una chiave segreta ha accesso completo, a meno che tu non scelga Limitato quando la crei e spunti solo ciò che può fare. Scegli questa opzione per una chiave che incolli in un altro servizio.

Crea e revoca le chiavi in Impostazioni → Chiavi API.
Crea chiavi nuove quando cambia un'agenzia, un fornitore o una persona del personale.
Ogni chiave mostra quando è stata usata l'ultima volta, così individui le chiavi che non servono più a nessuno.

Sicurezza delle chiavi. Una chiave pk_ è fatta per essere vista. Sta nel codice sorgente della tua pagina, e sono i suoi ambiti a limitarla, quindi concedile solo ciò che serve al tuo sito. Vale la pena impostare anche un elenco di origini consentite, ma sappi cosa fa. Impedisce a un altro sito di usare la tua chiave in un browser. Non può impedire a qualcuno di usare la chiave dal proprio software, perché un programma che non è un browser non invia l'origine che controlliamo. Nessuna impostazione rende sicura una chiave sk_ in un browser.

Widget di prenotazione

Il widget mette tutta la tua pagina di prenotazione, pagamento compreso, dentro il tuo sito. Ti serve solo se vuoi che i clienti prenotino senza lasciare il tuo sito. Passa questa parte a chi cura il tuo sito. Aggiunge un contenitore, carica lo script e lo avvia con una chiave pubblica.

<div id="booking-widget"></div>
<script src="https://app.fullclass.io/sdk/v1/booking.min.js"></script>
<script>
  FullClassBooking.init({
    apiKey: "pk_your_public_api_key",
    container: "#booking-widget"
  });
</script>

Lingua: il widget usa la lingua della tua pagina di prenotazione, impostata in Impostazioni → Widget di prenotazione. Non c'è nulla da aggiungere al codice. Per tenere un inserimento in un'altra lingua, aggiungi data-fullclass-locale="en" (oppure locale: "en" in init).
Una categoria per pagina: se ogni attività ha la sua pagina sul tuo sito, apri Impostazioni → Categorie e clicca su Copia codice widget accanto alla categoria. Incollalo nel <div> del widget su quella pagina, accanto a data-fullclass-apikey. Quel widget mostra allora solo quella categoria e nasconde le schede delle categorie.
Personalizzazione: lingue integrate, le tue parole per qualsiasi testo, colori del tema, oltre 100 proprietà CSS personalizzate, e le tue schermate di caricamento, di elenco vuoto e di errore.
Modalità essenziale: passa injectStyles: false per tenere la struttura del widget senza nessun suo CSS, così si applicano gli stili del tuo sito.
Controllo dal codice: il codice della tua pagina può aprire l'acquisto di una carta regalo, o il modulo di prenotazione di una lezione precisa.
Origini consentite: inserisci l'origine esatta, con protocollo, sottodominio e porta. https://www.example.com è un'origine diversa da https://example.com, quindi indicale tutte e due se le usi entrambe. Per la chiave del codice di inserimento già pronto, il posto più rapido per impostarlo è Impostazioni → Widget di prenotazione, subito sotto il codice. Se sbagli, il widget smette di caricarsi per i tuoi clienti. Per annullare, svuota il campo e salva.

Ambiti e funzionalità dell'API

Gli ambiti sono i permessi di una chiave. Decidono cosa può fare la chiave. Dai a ogni chiave solo ciò che le serve. Questa parte è soprattutto per chi cura il tuo sito.

Ambito	Cosa consente
`events:read`	Elencare gli eventi e leggerne i dettagli.
`bookings:write`	Creare nuove prenotazioni. Prenotare a nome di un cliente esistente (`purchaser_type: account`) richiede anche una chiave segreta.
`bookings:read`	Leggere i dettagli delle prenotazioni esistenti (dal codice del server).
`bookings:cancel`	Cancellare una prenotazione. Con una chiave pubblica, la richiesta deve inviare anche il `cancellation_token` della prenotazione.
`customers:write`	Registrare schede cliente.
`giftcards:read`	Controllare il saldo o le lezioni rimaste di una carta regalo.
`giftcards:write`	Acquistare carte regalo.

L'API pubblica può elencare gli eventi e leggerne i dettagli. Può recuperare liberatorie e opzioni, e creare, leggere e cancellare prenotazioni. Può anche creare e registrare clienti, controllare codici promozionali, e consultare o acquistare carte regalo. Non esiste un'API per spendere una carta regalo. Il pagamento accetta il codice dentro la prenotazione, e il personale usa Applica la carta regalo nella pagina della prenotazione.

Idempotenza. Invia sempre una chiave di idempotenza quando il codice del tuo server crea prenotazioni, così un nuovo tentativo non prenota due volte.

Carte regalo vendute altrove

Alcuni studi incassano un carnet di lezioni o una carta regalo fuori da FullClass, per esempio con un link di pagamento Stripe, un terminale per carte o un bonifico. Il tuo server può allora far emettere la carta a FullClass senza addebitare di nuovo l'acquirente. Invia una richiesta a /v1/giftcards con un blocco external_purchase al posto dei dati della carta.

{
  "type": "class_pass",
  "class_pass_count": 5,
  "purchased_by_email": "[email protected]",
  "external_purchase": {
    "reference": "pi_3RxAbCdEfGhIjKlM",
    "amount_cents": 8000
  }
}

Solo con chiave segreta. Questa richiesta emette una carta pagata senza incassare nulla, quindi una chiave pk_ viene rifiutata. Chiamala dal tuo server, mai da una pagina web.
Il riferimento evita i duplicati. Metti in reference l'ID del pagamento nel tuo sistema. Se lo stesso arriva due volte (un webhook inviato di nuovo, o uno script eseguito di nuovo), la seconda chiamata viene rifiutata e non viene emessa una seconda carta.
Il prezzo lo decidi tu. amount_cents è quanto hai davvero incassato. Non viene confrontato con il prezzo del tuo carnet di lezioni, quindi puoi vendere lo stesso carnet a più prezzi.
Invia l'importo con l'imposta inclusa. Invia l'intero importo pagato dall'acquirente. Per un carnet di lezioni, FullClass lo considera comprensivo dell'imposta che applichi ai carnet, con le aliquote delle impostazioni dei tuoi carnet.
Conta come una vendita. L'acquirente riceve le solite e-mail con il codice e la ricevuta, e tu ricevi la notifica di nuova vendita. Nei tuoi report la carta compare come Pagata al di fuori di FullClass, non come un omaggio.

← PrecedenteIntegrazioni Avanti →Assistenti IA