Skip to content

Documentation API Billetto et guide des webhooks

Comment vous authentifier, quels endpoints appeler et comment les webhooks Billetto envoient les données de billetterie à vos systèmes en temps réel. Des guides techniques pour les développeurs qui construisent sur Billetto.
DEVELOPER HUB

Ce que vous pouvez construire avec l'API Billetto

L'API Billetto est une API REST qui renvoie du JSON. Elle donne à votre propre code accès aux mêmes données que votre billetterie : événements, types de billets, commandes, participants, écritures comptables, questions de réservation et audiences. Les webhooks vous envoient les changements dès qu'ils se produisent, sans que vous ayez à les demander.

Les équipes l'utilisent pour synchroniser les acheteurs dans un CRM, charger les ventes dans un data warehouse, afficher les événements sur leur propre site, ajouter des membres à des audiences de prévente et rapprocher les versements dans leur système financier. Cette page explique comment l'API est structurée et comment fonctionnent les webhooks. Le schéma complet de chaque endpoint se trouve dans la référence de l'API.

Pour commencer

AUTHENTIFICATION

S'authentifier avec une paire de clés API ou OAuth 2.0

Paires de clés API pour votre propre compte

Utilisez une paire de clés lorsque vos propres systèmes appellent l'API au nom de votre compte organisateur. Créez-la dans Billetto sous Integrations → Developers → API - Key pairs, donnez-lui un nom qui décrit son usage (par exemple "Synchro CRM" ou "Data warehouse") et envoyez-la à chaque appel dans l'en-tête Api-Keypair.

  • Créez une paire de clés par système, pour pouvoir en révoquer une sans affecter les autres
  • Gardez le secret sur votre serveur. Ne l'exposez jamais dans un navigateur, une application mobile ou un dépôt public
  • Révoquez et remplacez immédiatement une paire de clés si vous pensez qu'elle a fuité

OAuth 2.0 pour les applications utilisées par d'autres organisateurs

Utilisez OAuth lorsque vous développez un produit auquel d'autres organisateurs Billetto connectent leur compte, comme un outil marketing, une plateforme d'événements ou un tableau de bord d'agence. OAuth utilise le flux authorization code : l'organisateur se connecte à Billetto, approuve votre application et vous recevez un jeton pour son compte. Vous ne voyez jamais son mot de passe, et il peut déconnecter votre application à tout moment.

Les deux méthodes sont décrites pas à pas dans le guide de démarrage.

Événements et types de billets

Récupérez les événements de votre compte avec date, lieu, statut et types de billets.

  • GET /organiser/events liste vos événements
  • Types de billets, prix et disponibilité par événement
  • Questions de réservation posées aux acheteurs lors du paiement

Usage typique

Affichez vos prochains événements avec la disponibilité en direct sur votre site ou votre application, et redirigez les acheteurs vers le paiement Billetto.

Commandes et participants

Voyez qui a acheté quoi, quand et pour quel événement.

  • GET /organiser/orders liste les commandes de tous vos événements
  • GET /organiser/events/{event_id}/attendees liste les participants d'un événement
  • Les résultats sont paginés : récupérez la page suivante jusqu'à ce qu'il n'y en ait plus

Usage typique

Gardez les données acheteurs à jour dans votre CRM ou envoyez les listes de participants à un système de contrôle d'accès ou d'accréditation.

Écritures comptables et rapports

Obtenez le détail financier de vos ventes de billets.

  • GET /organiser/ledger_entries liste ventes, remboursements, frais et versements
  • Un rapport BI par événement avec les principaux chiffres de vente

Usage typique

Chargez le chiffre d'affaires dans votre comptabilité ou votre data warehouse et rapprochez-le de vos versements.

Audiences et membres

Écrivez des données dans Billetto au lieu de seulement les lire.

  • Créer, mettre à jour et supprimer des membres d'audiences
  • Importer des listes complètes et suivre le statut de l'import
  • Récupérer une audience et son nombre de membres

Usage typique

Synchronisez membres, abonnés ou listes partenaires depuis votre CRM vers Audiences pour des préventes et des offres exclusives.

Abonnements webhook

Gérez les webhooks par le code plutôt que dans l'interface Billetto.

  • POST /organiser/webhooks enregistre une URL d'endpoint
  • Mettre à jour ou supprimer un webhook existant
  • Générer un nouveau secret de signature pour un webhook

Usage typique

Enregistrez automatiquement des webhooks lors de la mise en place d'un nouveau client ou environnement, et renouvelez les secrets selon un calendrier.

Public Event Search

Recherchez les événements publiés sur Billetto, tous organisateurs confondus.

  • Paramètres de requête pour filtrer les résultats, décrits dans la référence
  • Chaque résultat renvoie vers la page de l'événement et le paiement

Usage typique

Médias, guides de ville et plateformes partenaires montrent ainsi ce qui se passe, avec des billets vendus via Billetto.

EN PRATIQUE

L'API et les webhooks Billetto, étape par étape

APIÉtape 1 : accès

Créez une paire de clés et faites votre premier appel

Ouvrez Integrations, allez dans l'onglet Developers et créez une paire de clés pour le système que vous connectez. Copiez le secret, ajoutez-le aux en-têtes de votre requête et appelez un endpoint comme /organiser/orders. La réponse est du JSON que vous pouvez intégrer directement dans votre propre modèle de données.

  • Une paire de clés par intégration, nommée d'après le système qui l'utilise
  • Réponses JSON pour événements, commandes, participants et écritures comptables
  • Révoquez une paire de clés à tout moment sans affecter les autres
Ouvrir la référence de l'API

AUDIENCESÉtape 2 : écrire dans Billetto

Ajoutez des contacts à une audience via l'API

Les endpoints Audiences sont le principal moyen d'écrire des données dans Billetto. Envoyez des contacts de votre CRM vers une audience, ou importez une liste complète et vérifiez son statut jusqu'à ce qu'elle soit prête. Le groupe est alors prêt pour les invitations, les préventes et les offres exclusives.

  • Ajoutez, mettez à jour et supprimez des membres un par un
  • Imports en masse avec un statut que vous pouvez consulter
  • Les groupes apparaissent immédiatement dans Audiences

WEBHOOKSÉtape 3 : webhooks Billetto

Enregistrez un webhook et suivez les envois en direct

Ajoutez l'URL de votre endpoint dans l'onglet Developers, et Billetto génère un secret de signature pour celui-ci. Dès lors, chaque commande, remboursement, modification de participant ou publication d'événement est envoyé à votre URL sous forme de HTTP POST avec un corps JSON.

  • Configuration dans l'interface ou via POST /organiser/webhooks
  • Un secret de signature par webhook, que vous pouvez régénérer
  • La carte Webhooks affiche l'URL et la version d'API de chaque webhook
Lire la référence des webhooks
WEBHOOKS BILLETTO

Ce que sont les webhooks Billetto et quand les utiliser

Un webhook est une URL sur votre serveur que Billetto appelle lorsqu'un changement survient dans votre compte. Au lieu d'interroger l'API toutes les quelques minutes pour savoir s'il y a de nouvelles commandes, vous recevez un appel au moment où une commande est créée, remboursée ou modifiée.

C'est pourquoi les webhooks sont le bon outil quand le timing compte : une confirmation dans votre CRM en quelques secondes, un message Slack quand un billet VIP est vendu, ou un système de contrôle d'accès qui doit être informé d'un billet annulé avant l'ouverture des portes.

Webhooks ou API ?

  • Utilisez les webhooks pour réagir aux changements dès qu'ils se produisent : nouvelles commandes, remboursements, modifications de participants et événements publiés
  • Utilisez l'API pour charger l'historique, lancer une synchronisation complète chaque nuit ou récupérer des détails qu'un webhook ne contient pas
  • Utilisez les deux pour la solution la plus fiable : les webhooks pour la rapidité et une synchronisation API planifiée qui rattrape tout ce que vous avez manqué
COMMENT ÇA MARCHE

Comment un webhook Billetto est livré

De la vente d'un billet à son traitement dans votre système.
1
ENREGISTREZ L'ENDPOINT
Ajoutez une URL HTTPS publique dans l'onglet Developers ou via l'API, et conservez le secret de signature fourni par Billetto.
2
QUELQUE CHOSE CHANGE
Un acheteur commande, un billet est remboursé, les données d'un participant changent ou vous publiez un événement.
3
BILLETTO ENVOIE UN POST
Billetto envoie à votre URL un HTTP POST avec un corps JSON décrivant le changement.
4
VÉRIFIEZ ET RÉPONDEZ
Vérifiez l'appel avec votre secret de signature, répondez avec un statut 2xx et traitez les données en arrière-plan.
BONNES PRATIQUES WEBHOOK

Construire un récepteur de webhooks fiable

Sécurité

  • Vérifiez chaque appel avec le secret de signature du webhook avant de faire confiance à son contenu. La référence des webhooks explique comment
  • N'acceptez que le HTTPS et stockez le secret dans la configuration du serveur, pas dans le code
  • Générez un nouveau secret s'il a pu être exposé, puis mettez à jour votre récepteur

Fiabilité

  • Répondez vite. Renvoyez un statut 2xx dès que l'appel est vérifié, et faites le travail lourd dans une file d'attente
  • Gérez les doublons. Enregistrez les identifiants traités pour qu'une même commande ne soit jamais créée deux fois
  • Ne comptez pas sur l'ordre. S'il est important, récupérez l'état actuel de la commande via l'API
  • Rapprochez régulièrement. Une synchronisation API planifiée rattrape ce que votre endpoint a manqué pendant une panne
Documentation complète des endpoints

Référence de l'API Billetto

La référence de l'API documente chaque endpoint avec ses paramètres, des exemples d'appels et les objets de réponse. Utilisez-la avec ce guide quand vous commencez à coder : trouvez la bonne ressource ci-dessus, puis consultez les champs exacts dans la référence.

La ressource webhook

Référence des webhooks

La ressource webhook contient la configuration d'un endpoint : son URL, la version d'API utilisée et son secret de signature. Nous recommandons de créer votre premier webhook dans Billetto sous Integrations → Developers, puis de le gérer via l'API à mesure que votre configuration grandit.

Événements publics de tous les organisateurs

Public Event Search API

La Public Event Search API renvoie les événements que les organisateurs ont publiés sur Billetto, tous organisateurs confondus. Elle convient aux sites médias, guides de ville, offices de tourisme et applications partenaires qui veulent montrer ce qui se passe, chaque résultat renvoyant vers la page de l'événement Billetto où les billets sont achetés.

FAQ API ET WEBHOOKS

Questions sur l'API et les webhooks Billetto

Questions techniques de développeurs qui travaillent avec l'API Billetto. Vous ne trouvez pas votre réponse ? Parlez à notre équipe.

Où trouver ma clé API Billetto ?

Connectez-vous à Billetto, ouvrez Integrations et allez dans l'onglet Developers. Sous API - Key pairs, vous pouvez créer une nouvelle paire de clés, voir à qui appartient chacune et révoquer celles que vous n'utilisez plus.

Quelle est la différence entre une paire de clés API et OAuth ?

Une paire de clés donne à vos propres systèmes accès à votre propre compte organisateur. OAuth 2.0 est destiné aux applications auxquelles d'autres organisateurs connectent leur compte Billetto, pour agir en leur nom sans connaître leurs identifiants.

Quels événements les webhooks Billetto peuvent-ils envoyer ?

Les webhooks couvrent les changements sur les commandes, les participants et les événements, comme les nouvelles commandes, les remboursements, les modifications de participants et les événements publiés. La référence des webhooks liste tous les événements et leur contenu.

Comment vérifier qu'un appel webhook vient bien de Billetto ?

Chaque webhook a son propre secret de signature. Utilisez-le pour vérifier chaque appel entrant avant de le traiter, et rejetez les appels qui échouent à la vérification. Vous pouvez générer un nouveau secret pour un webhook à tout moment.

Puis-je créer des webhooks via l'API ?

Oui. Vous pouvez enregistrer, mettre à jour et supprimer des webhooks via les endpoints webhook, et générer un nouveau secret de signature pour un webhook existant. La plupart des équipes commencent dans l'interface et passent à l'API lorsqu'elles gèrent plusieurs environnements.

Que faire face à une réponse HTTP 429 ?

Un 429 signifie que vous envoyez trop d'appels. Attendez et réessayez avec une pause de plus en plus longue, et utilisez les webhooks plutôt qu'un polling fréquent pour limiter le nombre d'appels.

Puis-je afficher des événements Billetto sur mon site ou ma plateforme ?

Oui. Utilisez la Public Event Search API pour les événements publiés sur Billetto, ou l'endpoint events de l'organisateur pour vos propres événements. Les acheteurs finalisent leur achat dans le paiement Billetto.

Je ne suis pas développeur. Puis-je quand même connecter Billetto à d'autres outils ?

Oui. Google Analytics 4, le Meta Pixel, Zapier et votre propre prestataire de paiement se connectent sans code. Sur la page intégrations Billetto, vous voyez ce que vous pouvez configurer en quelques minutes.

Prêt pour votre premier appel ?

Créez une paire de clés sous Integrations, ouvrez la référence et appelez votre premier endpoint. Si vous préférez connecter Google Analytics, le Meta Pixel ou Zapier sans code, commencez par les intégrations Billetto.