Integración web

Esta página es la receta recomendada para conectar la web de un crew a Sway: el sitio conserva su propio diseño y alojamiento, y Sway se convierte en su fuente para el roster, los eventos, las entradas, los formularios y el programa de embajadores.

1. Llama a la API desde tu servidor

Mantén la clave secreta en tu servidor (rutas de API, renderizado en servidor, edge functions), nunca en una página.

• Guárdala como un secreto (SWAY_API_KEY), nunca en el repositorio ni en el bundle del cliente.
• Da a tus páginas tus propias rutas (/api/site-data) que llamen a Sway y devuelvan solo lo que la página muestra.
• Comprueba la clave y sus límites al arrancar con GET /v1/me.
• Los límites contados por visitante (solicitudes de booking, altas en la newsletter, checkout, las rutas de embajadores) cuentan al visitante que tu servidor nombra en el cuerpo como client_ip, y tu clave en conjunto con veinte veces el margen. Envíalo: sin él, solo se cuenta la clave entera, y un visitante que insiste puede agotar el margen de toda tu web.
• Un sitio totalmente estático sin servidor puede usar en su lugar una clave publicable (sway_pk_) desde el navegador, solo para lecturas públicas, listando las direcciones del sitio en la clave. Ver Dos tipos de clave.

2. Deja que la caché absorba el tráfico

Sway guarda en caché cada lectura por crew y sirve las repeticiones gratis, así que el tráfico de tu web no se convierte en tráfico de API. Pon tu parte:

• Envía If-None-Match. Guarda el ETag de cada respuesta; un recurso sin cambios responde 304, sin cuerpo y sin coste.
• Guarda tu propia copia durante el mismo tiempo que Sway, y sírvela cuando la API vaya lenta o no responda:

• Pide solo lo que muestras. ?fields= recorta las respuestas, ?expand=venue,lineup,ticket_tiers en el feed de un promotor sustituye tres peticiones por evento, ?ids= trae 50 eventos conocidos de una vez, y updated_since sincroniza solo lo que cambió.
• Escucha en vez de preguntar. Con webhooks, actualiza un evento cuando llega event.updated y añádelo con event.published, en vez de releer cada página con un temporizador. Envía esas actualizaciones con Cache-Control: no-cache, para que Sway las lea frescas en vez de desde una copia anterior al cambio.

Una web construida así hace pocas peticiones a la API por minuto sea cual sea su tráfico, y sigue funcionando durante un corte breve.

3. Vende entradas

El pago siempre pasa por la página de checkout de Sway. Hay dos formas de llegar a ella:

Un enlace. Cada tipo de entrada lleva una checkout_url. Muestra tu propio botón "Comprar entradas" apuntando a ella. Nada más que construir.

Un checkout abierto por tu web. Con write:checkout, tu servidor llama a POST /v1/checkout-sessions con los tipos y las cantidades que el visitante eligió en tu página, y redirige a la url que devuelve. Antes de eso:

• comprueba un cupón o un código de acceso con POST /v1/coupons/validate o POST /v1/access-codes/validate, para mostrar el descuento o desbloquear tipos ocultos antes de que el visitante pague;
• guarda el checkout_id de la respuesta para seguir el checkout (GET /v1/checkout-sessions/{id}) o cerrarlo (POST /v1/checkout-sessions/{id}/expire) cuando el visitante se vaya.

Luego llega order.paid a tu webhook con "via_your_site": true.

Muestra la disponibilidad a partir del status del tipo de entrada (on_sale, scheduled, sold_out, off_sale) y de GET /v1/events/{id}/availability. La API nunca expone el stock ni los datos de los compradores.

4. Recoge datos de tus formularios

Valida primero en tu servidor, y pon tu propia protección antibots (un captcha, un honeypot) delante de cada formulario: Sway ve tu servidor, no al visitante. Pasa la dirección del visitante donde el endpoint la pida (client_ip), para que los propios límites de Sway se apliquen por visitante y no a toda tu web. Las solicitudes de booking están limitadas a 10 por minuto y visitante y 300 al día por crew.

Las solicitudes de booking llegan a Admin del crew → API → Solicitudes de booking; las altas a la newsletter y las respuestas de formulario van al CRM del promotor y a las respuestas del formulario. Envía Idempotency-Key en cada una de estas llamadas, para que un reintento nunca registre un envío dos veces.

5. Conserva marcadores de reserva

Conserva el contenido estático de tu web (artistas de ejemplo, eventos de muestra) como una capa de reserva en vez de borrarlo:

• Si la API no responde y tu caché está vacía, muestra los marcadores en vez de una página vacía.
• Si la API devuelve menos elementos de los que necesita el diseño, completa la cuadrícula.
• Orden de mezcla: datos de la API, luego la propia selección de tu web, luego los marcadores.

La web se mantiene presentable en todo momento, incluso antes de configurar la primera clave.

6. Ejecuta el portal de embajadores en tu servidor

Cuando el promotor activa el alta desde tu web, la página de alta, la de acceso y la página propia del miembro son tuyas para mostrar, y la clasificación, las recompensas y las misiones del programa también son tuyas para mostrar (read:ambassadors). Una regla: el navegador guarda una cookie tuya, nunca una credencial de Sway.

• Mantén la sesión del miembro (amb_st_...) en tu servidor, en una cookie propia sellada o en un almacén de sesiones. Sway rechaza esa cabecera desde un navegador de todos modos.
• Pon tu propia protección antibots en los formularios de alta y de acceso. Sway no muestra ninguno de los dos.
• Cambia el ?amb_token=... de tu página de aterrizaje por una sesión en tu servidor, en la primera carga, y quítalo de la URL.
• Nunca pongas un discount_id en una página. Captura ?amb=CODE, guarda el código durante la visita, y resuélvelo en tu servidor al abrir el checkout.
• La lista de miembros, sus movimientos y las estadísticas (read:ambassador-members) son datos personales para las propias herramientas del promotor, nunca para una página pública.

Lista de comprobación

• SWAY_API_KEY guardada como secreto en el servidor (o una clave publicable limitada a tus sitios web)
• GET /v1/me usado como comprobación al arrancar
• If-None-Match enviado, respuestas guardadas, copia obsoleta servida ante errores
• fields, expand, ids y updated_since usados donde ahorran peticiones
• Un webhook para event.published y event.updated en vez de preguntar
• Los botones de entradas usan checkout_url, o tu servidor abre POST /v1/checkout-sessions
• Formularios enviados desde tu servidor, con tu propia protección antibots y una Idempotency-Key
• Contenido de marcador conservado como reserva
• Sesiones de embajadores guardadas en tu servidor, ?amb=CODE resuelto al hacer el checkout