API de billetterie pour site internet : que vérifier ?

Lorsque votre entreprise doit intégrer la billetterie à son infrastructure existante, la qualité de l'API est déterminante. Si vous comparez encore les options, notre guide sur comment choisir une plateforme de billetterie détaille les critères clés. Une API mal conçue, ce sont des mois de développement, des bugs à répétition et des limites découvertes trop tard. Ce guide vous aide à évaluer ce qu'il faut vérifier avant de vous engager avec une plateforme.

La bonne nouvelle, c'est que presque rien de ce qu'il faut exiger n'est une question d'opinion. L'essentiel figure dans des spécifications publiques : OpenAPI pour le contrat, les RFC de l'IETF pour l'authentification, les erreurs et la fin de vie d'un endpoint, et la documentation du prestataire de paiement pour la livraison des événements. Voici cette liste, avec la référence concrète à côté.

Que révèle la qualité de la documentation d'une API ?

La qualité de la documentation reflète la maturité de l'API. Cherchez ces éléments :

• Spécification OpenAPI/Swagger : elle permet de générer des clients automatiquement
• Exemples de code : dans les langages que vous utilisez (JS, Python, PHP...)
• Guides par cas d'usage : pas seulement de la référence, aussi des tutoriels
• Changelog : historique des changements et politique de versionnement
• Status page : visibilité sur la disponibilité du service

Le standard a un nom et une date. La OpenAPI Specification 3.1.0 a été publiée le 15 février 2021 et exige un champ openapi indiquant la version de la spécification utilisée par le document, distincte de la version de l'API elle-même. Elle admet JSON et YAML, et recommande YAML 1.2 pour que la conversion entre les deux ne perde aucune information.

Le contraste pratique est simple. Un document OpenAPI valide se charge dans un générateur et produit en quelques minutes un client typé dans votre langage. Un PDF ou une page d'exemples épars, non. Demandez le fichier, pas la capture d'écran : si le prestataire ne peut pas vous remettre l'openapi.yaml le jour même où vous le demandez, l'intégration démarre avec de la dette.

Comment une API de billetterie sécurisée doit-elle gérer l'authentification ?

L'API manipule des données sensibles et des transactions financières. La sécurité n'est pas négociable.

• OAuth 2.0 : standard moderne d'authentification
• Clés d'API avec scopes : permissions granulaires par clé
• Rotation des identifiants : possibilité de les renouveler sans interruption de service
• Rate limiting : protection contre les abus, avec des limites documentées
• Journaux d'accès : audit de qui accède à quoi

Le cadre de base est la RFC 6749, qui définit l'OAuth 2.0 Authorization Framework. Mais ce qu'il faut apporter à la réunion technique, c'est la RFC 9700, *Best Current Practice for OAuth 2.0 Security*, publiée en 2025. Trois de ses exigences se vérifient en une après-midi :

• Les serveurs d'autorisation doivent prendre en charge PKCE, et les clients publics doivent l'utiliser. C'est la protection contre le vol du code d'autorisation.
• La validation de la *redirect URI* doit se faire par comparaison exacte de chaînes, avec pour seule exception les ports variables sur localhost pour les applications natives. Toute correspondance par motif est une porte ouverte.
• Les jetons d'accès devraient être liés à l'émetteur par mTLS ou DPoP, afin qu'un jeton divulgué soit inutilisable entre d'autres mains.

Si le prestataire ne propose qu'une clé d'API statique et éternelle, ce n'est pas rédhibitoire, mais le contrat doit couvrir ce que ce choix implique : de vrais scopes, une rotation sans coupure de service et un journal des accès que vous pouvez exporter.

Quels endpoints essentiels l'API doit-elle couvrir ?

Vérifiez que l'API couvre toutes les opérations dont vous avez besoin.

• Événements : créer, modifier, lister, gérer les statuts
• Billets : types, prix, disponibilité, réservations
• Commandes : créer, consulter, annuler, rembourser
• Validation : vérifier les billets, enregistrer les accès
• Webhooks : notifications d'événements (vente, accès, etc.)

Une question compte plus que la liste ci-dessus : que se passe-t-il si la même requête arrive deux fois ? En billetterie, une relance réseau sur une création de commande peut dupliquer une vente et bloquer une jauge qui n'existe pas. La bonne réponse est une clé d'idempotence par opération d'écriture, de sorte que la seconde tentative renvoie le résultat de la première au lieu de créer une nouvelle commande. Posez la question par écrit et demandez à voir le comportement dans le sandbox.

La deuxième question porte sur la pagination et les limites de lecture. Une API qui ne documente ni le nombre de commandes renvoyées par page ni la façon de parcourir l'historique transforme n'importe quel export nocturne vers votre tableau de bord de métriques en problème d'ingénierie à part entière.

À quoi servent les webhooks dans une intégration ?

Les webhooks sont essentiels pour garder votre système synchronisé sans polling permanent.

• Événements disponibles : quelles actions déclenchent des webhooks
• Payload documenté : structure claire de chaque type d'événement
• Relances : que se passe-t-il si votre endpoint échoue
• Vérification de signature : pour valider l'authenticité du webhook
• Journaux : historique des webhooks envoyés et de leur statut

Comment vérifier une signature

La procédure la mieux documentée du secteur est celle de Stripe, et elle sert de modèle même si votre prestataire est un autre. Sa documentation des webhooks décrit un en-tête Stripe-Signature contenant un horodatage préfixé par t= et une ou plusieurs signatures préfixées par un schéma ; le seul schéma valide en production est v1. La signature est calculée comme un HMAC avec SHA-256 sur la chaîne formée de l'horodatage, d'un point et du corps JSON exact de la requête, avec le secret de l'endpoint pour clé.

Trois détails qui font échouer des intégrations réelles. Premièrement : il faut utiliser le corps brut ; si votre framework resérialise le JSON, la vérification échoue systématiquement. Deuxièmement : la comparaison doit se faire en temps constant, pour ne pas révéler d'information par le temps de réponse. Troisièmement : les bibliothèques officielles appliquent par défaut une tolérance de 5 minutes entre l'horodatage et l'heure actuelle, et la documentation elle-même déconseille de la mettre à zéro, car cela désactive le contrôle de fraîcheur et rouvre la porte à l'attaque par rejeu.

Relances, doublons et ordre

Les chiffres concrets comptent pour dimensionner votre file d'attente. Stripe documente des relances automatiques pendant trois jours au maximum avec un backoff exponentiel en production, et trois relances en quelques heures en sandbox. Le renvoi manuel fonctionne jusqu'à 15 jours depuis le tableau de bord et jusqu'à 30 jours depuis la CLI. On peut enregistrer jusqu'à 16 endpoints de webhook.

Et deux avertissements à recopier tels quels dans votre conception : l'ordre de livraison des événements n'est pas garanti, et un endpoint peut recevoir le même événement plus d'une fois. La recommandation officielle est d'enregistrer les identifiants d'événements déjà traités et de ne pas utiliser l'horodatage de création pour déduire l'ordre. De plus, l'endpoint doit renvoyer un 2xx avant la logique lourde : toute réponse 3xx est considérée comme un échec de livraison, et un *timeout* déclenche le cycle de relances.

Comment l'API doit-elle traiter les erreurs et les limites d'usage ?

Avec des formats standard, pas avec des chaînes inventées. La RFC 9457, *Problem Details for HTTP APIs*, publiée en 2023, définit un corps d'erreur lisible par machine avec cinq champs : type (URI qui identifie le type de problème), title, status, detail et instance, servi en application/problem+json. Une API qui l'utilise vous évite d'écrire un traducteur d'erreurs pour chaque prestataire.

Pour les limites d'usage, la référence est la RFC 6585, *Additional HTTP Status Codes*, d'avril 2012, qui a introduit le code 429 Too Many Requests. La spécification indique que la réponse devrait inclure des détails expliquant la situation et peut inclure un en-tête Retry-After précisant combien de temps attendre. Cet en-tête fait la différence entre une relance raisonnée et une boucle qui aggrave la saturation.

Lors de l'évaluation, demandez quelles limites l'API applique par minute et par clé, si elles diffèrent en lecture et en écriture, et ce qui se passe lors des pics d'une ouverture de vente, qui est précisément le moment où votre intégration appelle le plus. Une plateforme qui ne publie pas ses limites vous demande de les découvrir le pire jour possible.

Pourquoi ai-je besoin d'un environnement de test (sandbox) ?

Développer directement en production est la recette du désastre. Exigez un sandbox digne de ce nom.

• Environnement sandbox distinct : données de test sans effet sur la production
• Cartes de test : pour simuler des paiements sans débit réel
• Données d'exemple : événements et billets préchargés pour tester
• Parité avec la production : même comportement, mêmes réponses

Ajoutez un test que presque personne ne fait lors de l'évaluation : forcer les erreurs. Un sandbox utile permet de simuler un paiement refusé, un remboursement partiel, une authentification bancaire que l'acheteur abandonne et un webhook qui arrive en retard. Si vous ne pouvez tester que le cas nominal, vous n'avez rien testé.

L'horloge compte aussi. Vérifiez que le sandbox permet d'avancer la date d'un événement afin de contrôler la clôture des ventes, la validation à l'entrée et la génération des rapports ultérieurs sans attendre des semaines.

Quelles obligations légales l'intégration entraîne-t-elle ?

Deux fronts, et aucun n'est facultatif dans l'Union européenne.

Le premier, ce sont les paiements. Le Règlement délégué (UE) 2018/389 exige, à son article 4, que l'authentification repose sur deux éléments ou plus des catégories connaissance, possession et inhérence, et, à son article 5, le lien dynamique : le code généré doit être spécifique au montant et au bénéficiaire acceptés par le payeur. Son article 16 prévoit l'exemption pour les paiements de faible valeur : opérations jusqu'à 30 EUR, avec un cumul antérieur n'excédant pas 100 EUR ou un maximum de cinq opérations à distance consécutives. Votre intégration doit savoir ramener l'acheteur dans le parcours après une authentification, et cela se teste en sandbox, pas le soir de l'ouverture de la vente. Si vous vendez en Espagne, croisez ces éléments avec les moyens de paiement disponibles.

Le second, ce sont les données. Le Règlement (UE) 2016/679 impose, à son article 32, d'appliquer des mesures techniques et organisationnelles appropriées, y compris le chiffrement et la capacité de garantir la confidentialité et l'intégrité, et, à son article 33, de notifier les violations de sécurité à l'autorité de contrôle dans les meilleurs délais et, si possible, 72 heures au plus tard. L'API qui vous livre les e-mails et les téléphones des participants vous rend responsable de ce que vous en faites : le contrat de sous-traitance se signe avant le premier appel, pas après. Le détail opérationnel figure dans notre guide du RGPD pour les organisateurs.

Comment versionner et déprécier une API sans casser votre intégration ?

Avec des règles publiques. Le versionnement sémantique 2.0.0 réserve l'incrément de version majeure aux changements incompatibles avec les versions précédentes, la version mineure aux fonctionnalités compatibles et le correctif aux corrections. Appliqué à une API, cela signifie qu'un changement qui casse votre client ne peut pas arriver dans un déploiement silencieux un mardi.

Pour la fin de vie, il existe un en-tête standard. La RFC 8594, de mai 2019, définit le champ de réponse HTTP Sunset avec un unique horodatage indiquant à quel moment la ressource risque de cesser de répondre, et un type de relation de lien sunset pour pointer vers la politique de retrait ou de migration. Demander si l'API l'émet est un moyen rapide de savoir si le prestataire a pensé au cycle de vie ou seulement au lancement.

La même logique vaut pour le widget de vente intégré : si son JavaScript est servi depuis une URL sans version, tout changement du prestataire arrive sur votre site sans prévenir.

Quel support technique le prestataire doit-il offrir ?

Quand quelque chose plante à 2 heures du matin avant votre événement, il vous faut des réponses rapides.

• Canal technique : accès à des développeurs, pas seulement à un support générique
• SLA documenté : délais de réponse garantis
• Communauté : forum ou Slack pour résoudre vos questions
• Onboarding technique : session d'intégration guidée

Demandez que le SLA indique trois choses chiffrées : le délai de première réponse par niveau de gravité, la plage horaire couverte et ce qui se passe en cas de manquement. Un engagement sans conséquence n'est qu'une déclaration d'intention. Et interrogez-les sur la fenêtre de changements : une plateforme qui déploie en production un vendredi d'ouverture de vente a un problème de processus, pas de technologie.

Comment choisir la bonne API de billetterie ?

Une bonne API de billetterie accélère votre développement, réduit les bugs et vous permet de construire des expériences sur mesure. Elle est aussi la base pour intégrer un widget de vente intégré à votre propre site ou connecter votre tableau de bord de métriques. Une mauvaise API vous enferme dans des limites découvertes trop tard. Prenez le temps d'évaluer avant de vous engager : demandez l'accès au sandbox, testez les endpoints critiques et parlez à l'équipe technique. La bonne décision vous fera économiser des mois de frustration.

Neuf vérifications concrètes pour cette évaluation :

• Demandez le fichier OpenAPI, pas la documentation en HTML. S'il n'existe pas, générez vous-même le client et ajoutez-le au coût du projet.
• Exigez PKCE et la validation exacte de la redirect URI s'il y a OAuth 2.0, comme le demande la RFC 9700.
• Testez l'idempotence : lancez deux fois la même création de commande et vérifiez qu'une seule est créée.
• Vérifiez une signature de webhook à la main avant de vous fier à la bibliothèque, et fixez une tolérance temporelle différente de zéro.
• Faites échouer votre endpoint exprès et mesurez combien de relances arrivent, pendant combien de temps et avec quels en-têtes.
• Dupliquez un webhook et vérifiez que votre système ne vend pas deux fois le même billet.
• Demandez les limites d'usage par clé et si l'API renvoie 429 avec Retry-After.
• Contrôlez le format d'erreur : application/problem+json avec type, title, status, detail et instance fait gagner des semaines.
• Interrogez-les sur l'en-tête Sunset et sur la politique de versionnement avant de signer, pas quand l'avis arrivera.

Sources

• OpenAPI Specification v3.1.0, 15 février 2021 (OpenAPI Initiative)
• OpenAPI/Swagger Specification (SmartBear, Swagger)
• OAuth 2.0, page officielle du standard
• RFC 6749: The OAuth 2.0 Authorization Framework (IETF)
• RFC 9700: Best Current Practice for OAuth 2.0 Security (IETF, 2025)
• RFC 9457: Problem Details for HTTP APIs (IETF, 2023)
• RFC 6585: Additional HTTP Status Codes, avril 2012 (IETF)
• RFC 8594: The Sunset HTTP Header Field, mai 2019 (IETF)
• Semantic Versioning 2.0.0, spécification en espagnol
• Receive Stripe events in your webhook endpoint, documentation officielle de Stripe
• Règlement délégué (UE) 2018/389, normes techniques de réglementation relatives à l'authentification forte du client (EUR-Lex)
• Règlement (UE) 2016/679, Règlement général sur la protection des données (EUR-Lex)