API et intégrations

Reliez StudioBooking à votre logiciel de production, à votre site, à un tableur ou à un outil comme Zapier, Make ou n8n. Aucune double saisie : chaque outil garde son rôle.

Forfaits : l’API et les webhooks sont inclus dans le forfait Pro (avec la billetterie). La synchronisation d’un agenda externe est incluse dans tous les forfaits. Les exports suivent le forfait de chaque rubrique.

Clé API

Créez une clé dans le tableau de bord : Paramètres › Connexions › Intégrations. Une clé correspond à un lieu. Elle est en lecture seule ou en lecture + écriture (confirmer, annuler une réservation). La clé complète n’est affichée qu’une fois ; vous pouvez la révoquer à tout moment.

Authorization: Bearer sbk_votre_cle
Adresse de base : https://studiobooking.fr/api/v1

L’en-tête X-Api-Key: sbk_… est aussi accepté. Toutes les réponses sont en JSON (UTF-8), dates au format AAAA-MM-JJ, heures en heure de Paris.

Routes

Méthode et route	Ce qu’elle renvoie
`GET /api/v1`	La liste des routes et des événements de webhook (sans clé).
`GET /studio`	Le lieu : nom, salles, horaires.
`GET /reservations`	Les réservations. Paramètres : `depuis`, `jusqua`, `statut`, `recherche`, `limite`.
`GET /reservations/{ref}`	Une réservation : salle, horaires, client, montants, options.
`POST /reservations/{ref}/confirmer` `POST /reservations/{ref}/annuler`	Confirmer ou annuler (clé lecture + écriture).
`GET /disponibilites?date=&studio=`	Les heures libres d’une journée, salle par salle.
`GET /clients`	Les fiches clients. Paramètres : `recherche`, `limite`.
`GET /statistiques`	Les chiffres clés du lieu.
`GET /evenements`	La programmation avec un résumé des ventes (billets, invitations, recette, entrées, jauge). Paramètres : `depuis`, `jusqua`, `statut`.
`GET /evenements/{id}`	Un événement et ses ventes détaillées : par tarif, par origine (en ligne, guichet, invitation), par réseau (Fnac, Ticketmaster…), remboursements, entrées.
`GET /evenements/{id}/billets`	Les billets d’un événement (référence, tarifs, montant, origine, entrées, acheteur). Paramètres : `depuis` (date de création, pour reprendre où vous en étiez), `limite` (500 au plus).

Exemple

curl https://studiobooking.fr/api/v1/evenements/ev-123 \
  -H "Authorization: Bearer sbk_votre_cle"

{
  "evenement": { "id": "ev-123", "nom": "Concert d’exemple", "date": "2026-11-14", "heure": "20:30",
                 "statut": "annonce", "salles": [{ "id": "s1", "nom": "Grande salle" }], "jauge": 400 },
  "ventes": { "billets_vendus": 212, "invitations": 18, "recette_eur": 3180, "entrees": 0,
              "par_tarif": { "Plein tarif": { "billets": 150, "recette_eur": 2400 }, "Réduit": { "billets": 62, "recette_eur": 780 } },
              "par_origine": { "en_ligne": { "billets": 190, "recette_eur": 2850 }, "guichet": { "billets": 22, "recette_eur": 330 },
                               "invitation": { "billets": 18, "recette_eur": 0 } },
              "reseaux": { "Fnac Spectacles": { "billets": 40, "recette_ttc_eur": 720 } } }
}

Données fictives, pour illustrer le format.

Webhooks

Un webhook prévient votre logiciel dès qu’il se passe quelque chose. Ajoutez une adresse https dans Paramètres › Intégrations et choisissez les événements :

Événement	Quand
`reservation.creee` · `reservation.confirmee` · `reservation.modifiee` · `reservation.annulee`	Cycle de vie d’une réservation de salle.
`paiement.recu`	Acompte ou solde payé en ligne.
`billet.vendu`	Billet vendu en ligne, au guichet, ou invitation créée.
`billet.rembourse` · `billet.annule`	Billet remboursé (carte) ou annulé (guichet, invitation retirée).
`billet.scanne`	Entrée validée au contrôle (nombre de places entrées).
`evenement.annule` · `evenement.reporte`	Événement annulé ou reporté, avec l’état des ventes.

Format

POST https://votre-logiciel.example/webhook
X-StudioBooking-Event: billet.vendu
X-StudioBooking-Delivery: evt_…
X-StudioBooking-Signature: t=1791504000,v1=5f2c…

{ "id": "evt_…", "evenement": "billet.vendu", "cree_le": "2026-10-08T18:02:11.000Z",
  "studio_id": "…", "donnees": { "billet": { "ref": "EV-1A2B3C4D", "quantite": 2, "montant_eur": 30, … } } }

Vérifier la signature

Le secret du webhook est affiché à sa création. Calculez HMAC-SHA256(secret, t + "." + corps brut) en hexadécimal et comparez-le à v1. Refusez un horodatage trop ancien (5 minutes, par exemple).

// Node.js
const [t, v1] = entete.split(',').map((x) => x.split('=')[1]);
const attendu = crypto.createHmac('sha256', secret).update(`${t}.${corpsBrut}`).digest('hex');
const valide = crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));

Nouvelles tentatives

Répondez avec un code 2xx en moins de 8 secondes. Sinon, l’envoi est retenté après 1 min, 5 min, 30 min, 2 h, 12 h et 24 h. Un même envoi garde toujours le même id : utilisez-le pour ignorer un doublon.

Agenda externe (iCal)

Votre logiciel publie déjà un agenda ? Collez son adresse iCal / ICS dans Paramètres › Connexions › Synchroniser un agenda externe. Ses dates occupent les salles choisies : elles apparaissent comme prises sur la page de réservation et dans le planning, et l’agenda est relu toutes les heures. Les titres ne sont jamais montrés au public ; l’adresse est conservée chiffrée.

Sont pris en charge : fuseaux horaires (TZID, UTC), journées entières, répétitions (RRULE quotidiennes, hebdomadaires, mensuelles, annuelles), exceptions (EXDATE, RECURRENCE-ID), dates annulées (STATUS:CANCELLED) et « disponible » (TRANSP:TRANSPARENT) ignorées. Marges avant et après, filtres par mots, salle déduite du lieu de la date.

Pour vendre les billets d’une date de cet agenda, un clic crée un brouillon dans la Billetterie, lié à la date d’origine : si l’agenda change ensuite de date ou d’heure, l’écart est signalé, jamais corrigé tout seul.

Exports CSV

Depuis le Centre d’exports du tableau de bord : réservations, clients, groupes usagers des studios (contact, séances, heures, esthétique, membres, code postal), encaissements, journal des ventes, fichier des écritures comptables (FEC). Les fichiers sont préparés en arrière-plan et gardés 7 jours.

Éditeurs de logiciels

Vous éditez un logiciel de production, de billetterie ou de gestion culturelle et souhaitez un connecteur avec StudioBooking ? Écrivez-nous à [email protected] : un lieu de test et des données fictives sont mis à votre disposition.