Intégrations

Clés API, widget de réservation et portées

Clés API

Une clé API permet à un autre site web ou programme de communiquer avec votre compte FullClass. Il vous en faut une pour placer le widget de réservation sur votre propre site, ou pour connecter un outil comme Zapier. Si vous utilisez seulement votre page de réservation FullClass, vous n'en avez pas besoin. Il en existe deux types, et elles vont à des endroits différents.

Préfixe	Où elle se trouve	Comment elle est protégée
`pk_` Publique	Les navigateurs, le widget de réservation, les intégrations et les applications mobiles.	Elle est limitée par ses portées (ce qu'elle peut faire) et par une liste d'origines autorisées (les sites qui peuvent l'utiliser). Elle est sans risque dans le code de votre site tant que les deux restent étroites.
`sk_` Secrète	Uniquement dans du code serveur.	Traitez-la comme un mot de passe. Ne la mettez jamais dans le code d'un site, un dépôt de code public, une capture d'écran, un ticket d'assistance ou un créateur de sites. Une clé secrète a un accès complet, sauf si vous choisissez Restreint à sa création et ne cochez que ce qu'elle peut faire. Choisissez-le pour une clé que vous collez dans un autre service.

Créez et révoquez les clés dans Paramètres → Clés API.
Créez de nouvelles clés quand une agence, un prestataire ou un membre de l'équipe change.
Chaque clé indique sa dernière utilisation. Vous repérez ainsi les clés dont personne n'a besoin.

Sécurité des clés. Une clé pk_ est faite pour être vue. Elle se trouve dans le code source de votre page, et ce sont ses portées qui la limitent. Ne lui donnez donc que ce dont votre site a besoin. Une liste d'origines autorisées vaut aussi la peine, mais sachez ce qu'elle fait. Elle empêche un autre site web d'utiliser votre clé dans un navigateur. Elle ne peut pas empêcher quelqu'un d'utiliser la clé depuis son propre logiciel, car un programme qui n'est pas un navigateur n'envoie pas l'origine que nous vérifions. Aucun réglage ne rend une clé sk_ sûre dans un navigateur.

Widget de réservation

Le widget place toute votre page de réservation, paiement compris, dans votre propre site web. Vous n'en avez besoin que si vous voulez que vos clients réservent sans quitter votre site. Confiez cette partie à la personne qui gère votre site. Elle ajoute un conteneur, charge le script et le démarre avec une clé publique.

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

Langue : le widget utilise la langue de votre page de réservation, réglée dans Paramètres → Widget de réservation. Il n'y a rien à ajouter au code. Pour garder une intégration dans une autre langue, ajoutez data-fullclass-locale="en" (ou locale: "en" dans init).
Une catégorie par page : si chaque activité a sa propre page sur votre site, ouvrez Paramètres → Catégories et cliquez sur Copier le code widget à côté de la catégorie. Collez-le dans la balise <div> du widget sur cette page, à côté de data-fullclass-apikey. Ce widget n'affiche alors que cette catégorie et masque les onglets de catégories.
Personnalisation : des langues intégrées, vos propres mots pour n'importe quel texte, les couleurs du thème, plus de 100 propriétés CSS personnalisées, et vos propres écrans de chargement, d'absence de résultat et d'erreur.
Mode épuré : passez injectStyles: false pour garder la structure du widget sans son CSS. Les styles de votre site s'appliquent alors.
Pilotage par le code : le code de votre page peut ouvrir l'achat d'une carte cadeau, ou le formulaire de réservation d'un cours précis.
Origines autorisées : indiquez l'origine exacte, avec le protocole, le sous-domaine et le port. https://www.exemple.com est une origine différente de https://exemple.com, alors indiquez les deux si vous utilisez les deux. Pour la clé du code d'intégration prêt à l'emploi, le plus rapide est de la régler dans Paramètres → Widget de réservation, juste sous le code. En cas d'erreur, le widget ne se charge plus pour vos clients. Pour annuler, videz le champ et enregistrez.

Portées et possibilités de l'API

Les portées sont les autorisations d'une clé. Elles décident de ce que la clé peut faire. Ne donnez à chaque clé que ce dont elle a besoin. Cette partie s'adresse surtout à la personne qui gère votre site.

Portée	Ce qu'elle autorise
`events:read`	Lister les événements et lire le détail d'un événement.
`bookings:write`	Créer de nouvelles réservations. Réserver au nom d'un client existant (`purchaser_type: account`) demande aussi une clé secrète.
`bookings:read`	Lire le détail des réservations existantes (depuis du code serveur).
`bookings:cancel`	Annuler une réservation. Avec une clé publique, la requête doit aussi envoyer le `cancellation_token` de la réservation.
`customers:write`	Enregistrer des fiches clients.
`giftcards:read`	Consulter le solde ou les cours restants d'une carte cadeau.
`giftcards:write`	Acheter des cartes cadeaux.

L'API publique peut lister les événements et lire le détail d'un événement. Elle peut récupérer les décharges et les options, et créer, lire et annuler des réservations. Elle peut aussi créer et enregistrer des clients, vérifier des codes promo, et consulter ou acheter des cartes cadeaux. Aucune API ne permet de dépenser une carte cadeau. Le paiement prend le code dans la réservation, et l'équipe utilise Appliquer la carte cadeau sur la page de la réservation.

Idempotence. Envoyez toujours une clé d'idempotence quand votre code serveur crée des réservations. Ainsi, une nouvelle tentative ne réserve pas deux fois.

Cartes cadeaux vendues ailleurs

Certains studios encaissent l'argent d'un carnet de séances ou d'une carte cadeau en dehors de FullClass, par exemple par un lien de paiement Stripe, un terminal de paiement ou un virement. Votre serveur peut alors demander à FullClass d'émettre la carte sans débiter l'acheteur une deuxième fois. Envoyez une requête POST à /v1/giftcards avec un bloc external_purchase au lieu des informations de carte bancaire.

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

Clé secrète uniquement. Cette requête émet une carte payée sans encaisser de paiement. Une clé pk_ est donc refusée. Appelez-la depuis votre serveur, jamais depuis une page web.
La référence empêche les doublons. Mettez dans reference l'identifiant du paiement dans votre propre système. Si la même référence arrive deux fois (un webhook renvoyé, ou un script relancé), le second appel est refusé et aucune deuxième carte n'est émise.
Vous fixez le prix. amount_cents est ce que vous avez réellement encaissé. Il n'est pas comparé au prix de votre carnet de séances. Vous pouvez donc vendre le même carnet à plusieurs prix.
Envoyez le montant taxes comprises. Envoyez le montant total payé par l'acheteur. Pour un carnet de séances, FullClass considère qu'il inclut la taxe que vous appliquez aux carnets de séances, aux taux de taxe réglés pour vos carnets de séances.
C'est compté comme une vente. L'acheteur reçoit les e-mails habituels de code et de reçu, et vous recevez la notification de nouvelle vente. Dans vos rapports, la carte apparaît comme Payée en dehors de FullClass, et non comme un cadeau.

← PrécédentIntégrations Suivant →Assistants IA