Intégration sur votre site

Cette page est la recette recommandée pour connecter le site d'une agence ou d'un promoteur à l'API publique Sway : votre site conserve son design et son hébergement, et Sway devient sa source de données pour le roster, les événements et les billets.

1. Appelez l'API côté serveur uniquement

La clé API est un secret. Tous les appels API doivent passer par votre serveur (routes API, rendu côté serveur, edge functions) — jamais depuis le navigateur du visiteur.

• Stockez la clé dans une variable d'environnement ou un gestionnaire de secrets (SWAY_API_KEY), jamais dans le dépôt ni dans le bundle client.
• Exposez vos propres routes internes (ex. /api/site-data) à votre frontend ; ces routes appellent Sway avec la clé et ne renvoient que ce dont la page a besoin.
• Faites tourner la clé en en créant une nouvelle dans Admin crew → API, en la déployant, puis en révoquant l'ancienne.

2. Mettez en cache agressivement

Un site web n'a pas besoin de données en temps réel à chaque affichage de page. Mettez en cache les réponses de l'API sur votre serveur avec des TTL adaptés à la vitesse de changement de chaque ressource :

Avec ces TTL, un site partenaire typique fait une poignée de requêtes API par minute quel que soit son trafic — très en dessous des limites de débit par défaut — et survit aux courtes indisponibilités de l'API en servant depuis le cache.

3. Vendez les billets via Sway — liens profonds uniquement

La vente de billets se fait toujours sur Sway. Ne reconstruisez jamais un checkout sur le site partenaire.

• Chaque catégorie de billets inclut un checkout_url (ex. https://www.sway.events/event/4521?ref=api).
• Affichez votre propre bouton « Billets » et faites-le pointer directement vers checkout_url.
• Utilisez le status de la catégorie (on_sale, scheduled, sold_out, off_sale) et les prix pour afficher la disponibilité — l'API n'expose volontairement ni compteurs de stock ni données acheteurs.

4. Transmettez les demandes de booking

Si votre site a un formulaire de booking (avec une clé disposant du scope write:bookings) :

1. Le visiteur remplit le formulaire sur votre site.
2. Votre serveur valide les données, puis appelle POST /v1/booking-requests.
3. La demande arrive dans le pipeline de booking de votre crew sur Sway et le crew est notifié.

Gardez votre propre protection anti-spam (captcha, honeypot) devant le formulaire — l'endpoint a une limite de débit plus stricte que les endpoints de lecture (10 requêtes / minute).

5. Conservez les contenus de démonstration en secours

Conservez le contenu statique de votre site (artistes fictifs, événements d'exemple) comme couche de secours plutôt que de le supprimer :

• Si l'API est injoignable et que le cache est vide, affichez les contenus de démonstration plutôt qu'une page vide.
• Si l'API renvoie moins d'éléments que le design n'en demande, complétez la grille avec des contenus de démonstration.
• Ordre de fusion : données API → sélection/config de votre site → contenus de démonstration pour combler les trous.

Le site reste ainsi présentable en toutes circonstances, y compris pendant la configuration initiale avant l'ajout de la première clé.

Checklist

• SWAY_API_KEY stockée comme secret côté serveur
• Tous les appels Sway passent par vos propres routes serveur
• TTL de cache : roster/profil 1 h, événements 5 min, catégories de billets 60 s
• Les boutons billets pointent vers checkout_url — pas de checkout maison
• Le formulaire de booking poste côté serveur vers /v1/booking-requests
• Contenus de démonstration conservés en secours
• GET /v1/me utilisé comme vérification de santé/config