Website-integratie

Deze pagina is het aanbevolen recept om de website van een crew aan Sway te koppelen: de site houdt zijn eigen design en hosting, en Sway wordt zijn bron voor het roster, evenementen, tickets, formulieren en het ambassadeursprogramma.

1. Roep de API aan vanaf je server

Houd de secret key op je server (API-routes, server-side rendering, edge functions), nooit in een pagina.

• Bewaar hem als een secret (SWAY_API_KEY), nooit in de repository of de clientbundel.
• Geef je pagina's eigen routes (/api/site-data) die Sway aanroepen en alleen teruggeven wat de pagina toont.
• Controleer de sleutel en zijn limieten bij het opstarten met GET /v1/me.
• Limieten die per bezoeker tellen (bookingaanvragen, nieuwsbriefinschrijvingen, checkout, de ambassadeursroutes) tellen de bezoeker die je server in de body noemt als client_ip, en je sleutel als geheel met twintig keer de ruimte. Stuur het mee: zonder telt alleen de hele sleutel, en één bezoeker die blijft proberen kan de ruimte van je hele site opmaken.
• Een volledig statische site zonder server kan in plaats daarvan een publishable key (sway_pk_) gebruiken vanuit de browser, alleen voor publieke reads, met de adressen van de site op de sleutel vermeld. Zie Twee soorten sleutel.

2. Laat caching het verkeer dragen

Sway cachet elke read per crew en serveert herhalingen gratis, zodat het verkeer van je site geen API-verkeer wordt. Doe je deel:

• Stuur If-None-Match. Bewaar de ETag van elk antwoord; een ongewijzigde bron antwoordt 304, zonder body en zonder kosten.
• Bewaar je eigen kopie even lang als Sway dat doet, en serveer ze wanneer de API traag of onbereikbaar is:

• Vraag wat je toont. ?fields= snoeit antwoorden, ?expand=venue,lineup,ticket_tiers op de feed van een promotor vervangt drie verzoeken per evenement, ?ids= haalt 50 bekende evenementen in één keer op, en updated_since synct alleen wat veranderde.
• Luister in plaats van te pollen. Ververs met webhooks een evenement zodra event.updated binnenkomt en voeg het toe bij event.published, in plaats van elke pagina steeds opnieuw te lezen op een timer. Stuur die verversingen met Cache-Control: no-cache, zodat Sway ze vers leest in plaats van uit een kopie van voor de wijziging.

Een site die zo gebouwd is, doet maar een handvol API-verzoeken per minuut, wat het verkeer ook is, en blijft werken tijdens een korte storing.

3. Verkoop tickets

Betalen gebeurt altijd op de checkoutpagina van Sway. Twee manieren om er te komen:

Een link. Elk tickettype draagt een checkout_url. Toon je eigen knop "Tickets kopen" die ernaartoe wijst. Er is niets anders te bouwen.

Een checkout die je site opent. Met write:checkout roept je server POST /v1/checkout-sessions aan met de tickettypes en aantallen die de bezoeker op je pagina koos, en stuurt door naar de url die het teruggeeft. Daarvoor:

• controleer een coupon of een toegangscode met POST /v1/coupons/validate of POST /v1/access-codes/validate, om de korting te tonen of verborgen tickettypes te ontgrendelen voordat de bezoeker betaalt;
• bewaar de checkout_id uit het antwoord om de checkout te volgen (GET /v1/checkout-sessions/{id}) of te beëindigen (POST /v1/checkout-sessions/{id}/expire) wanneer de bezoeker vertrekt.

Daarna komt order.paid binnen op je webhook met "via_your_site": true.

Toon beschikbaarheid via de status van het tickettype (on_sale, scheduled, sold_out, off_sale) en GET /v1/events/{id}/availability. De API toont nooit voorraadaantallen of kopersgegevens.

4. Verzamel via je formulieren

Valideer eerst op je server, en zet je eigen botbescherming (een captcha, een honeypot) voor elk formulier: Sway ziet je server, niet de bezoeker. Geef het adres van de bezoeker mee waar het endpoint erom vraagt (client_ip), zodat de eigen limieten van Sway per bezoeker gelden in plaats van voor je hele site. Bookingaanvragen zijn beperkt tot 10 per minuut per bezoeker en 300 per dag per crew.

Bookingaanvragen komen terecht in Crew admin → API → Bookingaanvragen; nieuwsbriefinschrijvingen en formulierantwoorden in de CRM van de promotor en de antwoorden van het formulier. Stuur Idempotency-Key mee op elk van deze aanroepen, zodat een retry een inzending nooit twee keer registreert.

5. Houd placeholders als terugval

Houd de statische inhoud van je site (voorbeeldartiesten, voorbeeldevenementen) als terugvallaag in plaats van ze te verwijderen:

• Is de API onbereikbaar en je cache leeg, toon dan de placeholders in plaats van een lege pagina.
• Geeft de API minder items terug dan het design nodig heeft, vul het raster dan aan.
• Samenvoegvolgorde: API-gegevens, dan de eigen selectie van je site, dan placeholders.

De site blijft altijd toonbaar, ook voordat de eerste sleutel is ingesteld.

6. Draai het ambassadeursportaal op je server

Zet de promotor aanmelden vanaf je website aan, dan zijn de aanmeldpagina, de inlogpagina en de eigen pagina van het lid aan jou om te tonen, en zijn de ranglijst, rewards en quests van het programma aan jou om te tonen (read:ambassadors). Eén regel: de browser bewaart een cookie van jou, nooit een Sway-inloggegeven.

• Houd de ledensessie (amb_st_...) op je server, in een verzegelde first-party cookie of een session store. Sway weigert die header sowieso vanuit een browser.
• Zet je eigen botbescherming op de aanmeld- en inlogformulieren. Sway toont geen van beide.
• Ruil de ?amb_token=... op je landingspagina in voor een sessie op je server, meteen bij de eerste keer laden, en haal hem daarna uit de URL.
• Zet nooit een discount_id in een pagina. Vang ?amb=CODE op, bewaar de code voor dat bezoek, en los hem op je server op wanneer je de checkout opent.
• De ledenlijst, puntengeschiedenis en statistieken (read:ambassador-members) zijn persoonsgegevens voor de eigen tools van de promotor, nooit voor een publieke pagina.

Checklist

• SWAY_API_KEY bewaard als secret op de server (of een publishable key beperkt tot je websites)
• GET /v1/me gebruikt als opstartcontrole
• If-None-Match verstuurd, antwoorden bewaard, verouderde kopie geserveerd bij fouten
• fields, expand, ids en updated_since gebruikt waar ze verzoeken besparen
• Een webhook voor event.published en event.updated in plaats van pollen
• Ticketknoppen gebruiken checkout_url, of je server opent POST /v1/checkout-sessions
• Formulieren gepost vanaf je server, met je eigen botbescherming en een Idempotency-Key
• Placeholderinhoud bewaard als terugval
• Ambassadeurssessies bewaard op je server, ?amb=CODE opgelost bij de checkout