Integrazione nel sito

Questa pagina è la ricetta consigliata per collegare il sito di una crew a Sway: il sito mantiene il suo design e il suo hosting, e Sway ne diventa la fonte per il roster, gli eventi, i biglietti, i moduli e il programma ambassador.

1. Chiama l'API solo dal tuo server

Tieni la chiave segreta sul tuo server (rotte API, rendering lato server, edge function), mai in una pagina.

• Salvala come segreto (SWAY_API_KEY), mai nel repository o nel bundle del client.
• Dai alle tue pagine rotte tue (/api/site-data) che chiamano Sway e restituiscono solo quello che la pagina mostra.
• Verifica la chiave e i suoi limiti all'avvio con GET /v1/me.
• I limiti contati per visitatore (richieste di booking, iscrizioni alla newsletter, checkout, le route degli ambassador) contano il visitatore che il tuo server indica nel corpo come client_ip, e la tua chiave nel suo insieme con venti volte il margine. Invialo: senza, conta solo la chiave intera, e un visitatore che insiste può esaurire il margine di tutto il tuo sito.
• Un sito interamente statico senza server può invece usare una chiave pubblicabile (sway_pk_) dal browser, solo per letture pubbliche, elencando sulla chiave gli indirizzi del sito. Vedi Due tipi di chiave.

2. Lascia che la cache regga il traffico

Sway mette in cache ogni lettura per crew e serve le ripetizioni gratis, così il traffico del tuo sito non diventa traffico verso l'API. Fai la tua parte:

• Invia If-None-Match. Conserva l'ETag di ogni risposta; una risorsa non cambiata risponde 304, senza corpo e senza costo.
• Tieni una tua copia per tutto il tempo in cui la tiene Sway, e servila quando l'API è lenta o irraggiungibile:

• Chiedi solo quello che mostri. ?fields= snellisce le risposte, ?expand=venue,lineup,ticket_tiers sul feed di un promoter sostituisce tre richieste per evento, ?ids= recupera 50 eventi noti in una volta, e updated_since sincronizza solo quello che è cambiato.
• Ascolta invece di interrogare a intervalli. Con i webhook, aggiorna un evento quando arriva event.updated e aggiungilo su event.published, invece di rileggere ogni pagina a intervalli regolari. Invia queste letture con Cache-Control: no-cache, così Sway le legge alla fonte e non da una copia fatta prima del cambiamento.

Un sito costruito così fa poche richieste API al minuto qualunque sia il suo traffico, e continua a funzionare durante una breve interruzione.

3. Vendi i biglietti

Il pagamento avviene sempre sulla pagina di checkout di Sway. Due modi per arrivarci:

Un link. Ogni tipo di biglietto porta una checkout_url. Mostra il tuo pulsante "Acquista biglietti" che punta lì. Non c'è altro da costruire.

Un checkout aperto dal tuo sito. Con write:checkout, il tuo server chiama POST /v1/checkout-sessions con i tipi e le quantità che il visitatore ha scelto sulla tua pagina, e reindirizza all'url che restituisce. Prima di questo:

• verifica un coupon o un codice di accesso con POST /v1/coupons/validate o POST /v1/access-codes/validate, per mostrare lo sconto o sbloccare tipi nascosti prima che il visitatore paghi;
• conserva il checkout_id dalla risposta per seguire il checkout (GET /v1/checkout-sessions/{id}) o terminarlo (POST /v1/checkout-sessions/{id}/expire) quando il visitatore se ne va.

Poi order.paid arriva sul tuo webhook con "via_your_site": true.

Mostra la disponibilità a partire dallo status del tipo di biglietto (on_sale, scheduled, sold_out, off_sale) e da GET /v1/events/{id}/availability. L'API non espone mai i conteggi di stock né i dati degli acquirenti.

4. Raccogli dai tuoi moduli

Convalida prima sul tuo server, e tieni la tua protezione antispam (un captcha, un honeypot) davanti a ogni modulo: Sway vede il tuo server, non il visitatore. Passa l'indirizzo del visitatore dove l'endpoint lo richiede (client_ip), così i limiti di Sway si applicano per visitatore invece che a tutto il tuo sito. Le richieste di booking sono limitate a 10 al minuto per visitatore e 300 al giorno per crew.

Le richieste di booking arrivano in Admin della crew → API → Richieste di booking; le iscrizioni alla newsletter e le risposte ai moduli nel CRM del promoter e nelle risposte del modulo. Invia Idempotency-Key su ognuna di queste chiamate, così un tentativo ripetuto non registra mai due volte lo stesso invio.

5. Tieni i segnaposto come riserva

Tieni il contenuto statico del tuo sito (artisti di esempio, eventi di esempio) come livello di riserva invece di cancellarlo:

• Se l'API è irraggiungibile e la tua cache è vuota, mostra i segnaposto invece di una pagina vuota.
• Se l'API restituisce meno elementi di quelli che servono al design, completa la griglia.
• Ordine di unione: dati dell'API, poi la selezione del tuo sito, poi i segnaposto.

Il sito resta presentabile in ogni momento, anche prima che la prima chiave sia configurata.

6. Gestisci il portale ambassador sul tuo server

Quando il promoter attiva l'iscrizione dal tuo sito, la pagina di iscrizione, la pagina di accesso e la pagina personale del membro sono tue da mostrare, e la classifica, i premi e le missioni del programma sono tuoi da mostrare (read:ambassadors). Una regola: il browser tiene un tuo cookie, mai una credenziale Sway.

• Tieni la sessione membro (amb_st_...) sul tuo server, in un cookie first-party sigillato o in uno store di sessioni. Sway rifiuta comunque quell'header da un browser.
• Metti la tua protezione anti-bot sui moduli di iscrizione e di accesso. Sway non ne mostra nessuno dei due.
• Scambia il ?amb_token=... della tua pagina di arrivo con una sessione sul tuo server, al primo caricamento, e toglilo dall'URL.
• Non mettere mai un discount_id in una pagina. Cattura ?amb=CODE, tieni il codice per la visita, e risolvilo sul tuo server quando apri il checkout.
• L'elenco dei membri, gli estratti conto e le statistiche (read:ambassador-members) sono dati personali per gli strumenti del promoter, mai per una pagina pubblica.

Checklist

• SWAY_API_KEY salvata come segreto lato server (o una chiave pubblicabile limitata ai tuoi siti)
• GET /v1/me usato come verifica all'avvio
• If-None-Match inviato, risposte conservate, copia stantia servita in caso di errore
• fields, expand, ids e updated_since usati dove fanno risparmiare richieste
• Un webhook per event.published e event.updated invece di interrogare a intervalli
• I pulsanti dei biglietti usano checkout_url, oppure il tuo server apre POST /v1/checkout-sessions
• Moduli inviati dal tuo server, con la tua protezione anti-bot e un Idempotency-Key
• Contenuto segnaposto tenuto come riserva
• Sessioni ambassador tenute sul tuo server, ?amb=CODE risolto al checkout