Intégration sur votre site

Cette page est la recette recommandée pour connecter le site web d'un crew à Sway : le site garde son propre design et son propre hébergement, et Sway devient sa source pour le roster, les événements, les billets, les formulaires et le programme ambassadeurs.

1. Appelez l'API depuis votre serveur

Gardez la clé secrète sur votre serveur (routes API, rendu côté serveur, edge functions), jamais dans une page.

• Stockez-la comme un secret (SWAY_API_KEY), jamais dans le dépôt ni dans le bundle client.
• Donnez à vos pages vos propres routes (/api/site-data) qui appellent Sway et ne renvoient que ce que la page affiche.
• Vérifiez la clé et ses limites au démarrage avec GET /v1/me.
• Les limites comptées par visiteur (demandes de booking, inscriptions à la newsletter, checkout, routes ambassadeurs) comptent le visiteur que votre serveur nomme dans le corps, en client_ip, et votre clé dans son ensemble avec vingt fois la marge. Envoyez-le : sans lui, seule la clé est comptée, et un visiteur qui insiste peut épuiser la marge de tout votre site.
• Un site entièrement statique sans serveur peut à la place utiliser une clé publique (sway_pk_) depuis le navigateur, pour les lectures publiques uniquement, en listant les adresses du site sur la clé. Voir Deux types de clé.

2. Laissez le cache porter le trafic

Sway met en cache chaque lecture par crew et sert les répétitions gratuitement, si bien que le trafic de votre site ne devient pas du trafic API. Faites votre part :

• Envoyez If-None-Match. Gardez l'ETag de chaque réponse ; une ressource inchangée répond 304, sans corps et sans coût.
• Gardez votre propre copie aussi longtemps que Sway la garde, et servez-la quand l'API est lente ou injoignable :

• Ne demandez que ce que vous affichez. ?fields= allège les réponses, ?expand=venue,lineup,ticket_tiers sur le flux d'un promoteur remplace trois requêtes par événement, ?ids= récupère 50 événements connus d'un coup, et updated_since ne synchronise que ce qui a changé.
• Écoutez plutôt qu'interroger. Avec les webhooks, rafraîchissez un événement quand event.updated arrive et ajoutez-le sur event.published, plutôt que de relire chaque page sur une minuterie. Envoyez ces relectures avec Cache-Control: no-cache, pour que Sway les lise à la source plutôt que dans une copie faite avant le changement.

Un site construit ainsi ne fait que quelques requêtes API par minute quel que soit son trafic, et continue de fonctionner pendant une courte panne.

3. Vendez des billets

Le paiement se passe toujours sur la page de paiement Sway. Deux façons d'y arriver :

Un lien. Chaque catégorie de billets porte un checkout_url. Affichez votre propre bouton "Obtenir des billets" qui pointe vers lui. Rien d'autre à construire.

Un paiement ouvert par votre site. Avec write:checkout, votre serveur appelle POST /v1/checkout-sessions avec les catégories et quantités que le visiteur a choisies sur votre page, et redirige vers l'url que ça renvoie. Avant cela :

• vérifiez un coupon ou un code d'accès avec POST /v1/coupons/validate ou POST /v1/access-codes/validate, pour montrer la réduction ou débloquer des catégories cachées avant que le visiteur ne paie ;
• gardez le checkout_id de la réponse pour suivre le paiement (GET /v1/checkout-sessions/{id}) ou le terminer (POST /v1/checkout-sessions/{id}/expire) quand le visiteur s'en va.

Ensuite order.paid arrive sur votre webhook avec "via_your_site": true.

Montrez la disponibilité à partir du status de la catégorie (on_sale, scheduled, sold_out, off_sale) et de GET /v1/events/{id}/availability. L'API n'expose jamais les compteurs de stock ni les données acheteurs.

4. Collectez depuis vos formulaires

Validez d'abord sur votre serveur, et gardez votre propre protection anti-bot (un captcha, un honeypot) devant chaque formulaire : Sway voit votre serveur, pas le visiteur. Transmettez l'adresse du visiteur là où l'endpoint la demande (client_ip), pour que les limites propres à Sway s'appliquent par visiteur plutôt qu'à tout votre site. Les demandes de booking sont limitées à 10 par minute et par visiteur et 300 par jour par crew.

Les demandes de booking arrivent dans Admin crew → API → Demandes de booking ; les inscriptions newsletter et les réponses aux formulaires dans le CRM du promoteur et les réponses du formulaire. Envoyez Idempotency-Key sur chacun de ces appels, pour qu'une nouvelle tentative n'enregistre jamais une soumission deux fois.

5. Gardez des contenus de remplacement en secours

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

• Si l'API est injoignable et que votre cache est vide, affichez les contenus de remplacement 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 eux.
• Ordre de fusion : données de l'API, puis la sélection propre à votre site, puis les contenus de remplacement.

Le site reste présentable en toutes circonstances, y compris avant que la première clé ne soit configurée.

6. Faites tourner le portail ambassadeurs sur votre serveur

Quand le promoteur active l'inscription depuis votre site web, la page d'inscription, la page de connexion et la page propre du membre sont à vous de créer, et le classement, les récompenses et les quêtes du programme sont à vous d'afficher (read:ambassadors). Une seule règle : le navigateur détient un cookie à vous, jamais un identifiant Sway.

• Gardez la session membre (amb_st_...) sur votre serveur, dans un cookie first-party scellé ou un magasin de sessions. Sway refuse de toute façon cet en-tête venant d'un navigateur.
• Faites tourner votre propre protection anti-bot sur les formulaires d'inscription et de connexion. Sway n'affiche ni l'un ni l'autre.
• Échangez le ?amb_token=... de votre page d'atterrissage contre une session sur votre serveur, au premier chargement, puis retirez-le de l'URL.
• Ne mettez jamais un discount_id dans une page. Captez le ?amb=CODE, gardez le code pour la visite, et résolvez-le à nouveau sur votre serveur au moment d'ouvrir le paiement.
• La liste des membres, les registres et les statistiques (read:ambassador-members) sont des données personnelles réservées aux outils du promoteur, jamais pour une page publique.

Checklist

• SWAY_API_KEY stockée comme secret côté serveur (ou une clé publique limitée à vos sites web)
• GET /v1/me utilisé comme vérification au démarrage
• If-None-Match envoyé, réponses gardées, copie périmée servie en cas d'erreur
• fields, expand, ids et updated_since utilisés là où ils économisent des requêtes
• Un webhook pour event.published et event.updated plutôt que d'interroger en boucle
• Les boutons de billets utilisent checkout_url, ou votre serveur ouvre POST /v1/checkout-sessions
• Formulaires envoyés depuis votre serveur, avec votre propre protection anti-bot et une Idempotency-Key
• Contenus de remplacement gardés en secours
• Sessions ambassadeurs gardées sur votre serveur, ?amb=CODE résolu au paiement