Introducción

SmartTix.pro es un motor de seating embebible que se integra en tu plataforma de ticketing. Proporciona mapas de asientos interactivos con selección en tiempo real, gestión de holds temporales y un algoritmo de gap-management que maximiza la ocupación de cada venue.

La integración consta de dos partes: un Web Component que renderiza el mapa en el frontend de tu cliente, y una API REST que gestiona holds y confirmaciones desde tu backend.

Quick Start

Integra el viewer en tu página de checkout con 3 líneas de código. El componente se conecta automáticamente a la API para cargar el layout y gestionar la disponibilidad en tiempo real.

1. Incluir el script

<!-- Carga el Web Component desde el CDN -->
<script src="https://cdn.smarttix.pro/venue-viewer.js"></script>

2. Añadir el elemento

<venue-viewer
  public-token="evt_abc123def456"
  api-url="https://api.smarttix.pro"
  max-seats="6"
  currency="EUR"
></venue-viewer>

3. Escuchar selecciones

const viewer = document.querySelector('venue-viewer');

viewer.addEventListener('seatSelected', (e) => {
  console.log('Seleccionado:', e.detail);
  // { seatId, label, sectorName, rowLabel, price, currency, categoryColor }
});

viewer.addEventListener('seatDeselected', (e) => {
  console.log('Deseleccionado:', e.detail.seatId);
});

Autenticación

Los endpoints embed son públicos y no requieren autenticación JWT. El acceso se controla mediante el publicToken del evento, un identificador único generado al publicar el evento.

El publicToken es seguro para exponerlo en el frontend. Solo permite operaciones de lectura y holds temporales — no es posible modificar el venue ni la configuración del evento a través de él.

CORS está abierto para todos los orígenes en los endpoints embed, lo que permite integraciones desde cualquier dominio.

Web Component

El viewer es un Custom Element estándar (<venue-viewer>) que encapsula toda la lógica de renderizado, interacción y comunicación en tiempo real. Funciona con cualquier framework o vanilla JS.

Atributos

Eventos

Todos los eventos utilizan CustomEvent con bubbles: true y composed: true (atraviesan Shadow DOM).

{ seatId: "guid",
  label: "A-12",
  sectorName: "Platea",
  rowLabel: "A",
  price: 45.00,
  currency: "EUR",
  categoryColor: "#6366F1" }

{ sectorId: "guid",
  sectorName: "Pista",
  qty: 3,
  price: 25.00,
  currency: "EUR" }

Métodos

Obtener Seatmap

Devuelve el layout completo del venue con la disponibilidad actual de todos los asientos. Es la llamada inicial que realiza el Web Component al montarse.

Parámetros

Respuesta 200

{
  "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventName": "Concierto de Primavera",
  "holdDurationMinutes": 10,
  "venue": {
    "id": "guid",
    "name": "Teatro Principal",
    "viewportWidth": 1200,
    "viewportHeight": 800,
    "sectors": [
      {
        "id": "guid",
        "name": "Platea",
        "type": "Numbered",
        "categoryId": "guid",
        "rows": [
          {
            "id": "guid",
            "label": "A",
            "seats": [
              {
                "id": "guid",
                "label": "1",
                "x": 120.5,
                "y": 340.0,
                "radius": 12,
                "status": "Available",
                "isAccessible": false
              }
            ]
          }
        ]
      },
      {
        "id": "guid",
        "name": "Pista General",
        "type": "GeneralAdmission",
        "categoryId": "guid",
        "capacity": 500,
        "available": 342
      }
    ]
  },
  "categories": [
    {
      "id": "guid",
      "name": "VIP",
      "color": "#6366F1",
      "price": 75.00,
      "currency": "EUR"
    }
  ]
}

Estados de asiento

Crear Hold

Reserva temporalmente asientos y/o entradas de admisión general. Los asientos quedan bloqueados durante holdDurationMinutes (configurado por evento). Si el hold expira, los asientos se liberan automáticamente.

Request body

{
  "seatIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "4fb96g75-6828-5673-c4gd-3d074g77bfb7"
  ],
  "sessionId": "sess_x7k2m9",
  "gaSelections": [
    {
      "sectorId": "guid",
      "qty": 2,
      "ticketType": "Adult"
    }
  ]
}

Respuesta 200

{
  "holdId": "hold_a1b2c3d4",
  "seatIds": ["guid", "guid"],
  "gaSelections": [
    { "sectorId": "guid", "qty": 2, "ticketType": "Adult" }
  ],
  "expiresAt": "2026-03-04T15:10:00Z",
  "totalPrice": 195.00,
  "currency": "EUR"
}

Errores

Confirmar Hold

Confirma un hold activo tras completar el pago. Los asientos pasan de Held a Booked de forma permanente. Esta llamada se realiza desde tu backend, nunca desde el frontend del comprador.

Request body

{
  "holdId": "hold_a1b2c3d4",
  "sessionId": "sess_x7k2m9",
  "externalOrderId": "pi_3MqR5K2eZvKYlo2C0X1a2b3c"
}

Respuesta 200

{
  "holdId": "hold_a1b2c3d4",
  "bookedSeatIds": ["guid", "guid"],
  "gaBookings": [
    { "sectorId": "guid", "qty": 2 }
  ],
  "externalOrderId": "pi_3MqR5K2eZvKYlo2C0X1a2b3c"
}

Liberar Hold

Cancela un hold activo y libera todos los asientos asociados. Los asientos vuelven a estar disponibles inmediatamente.

Parámetros

Respuesta 204 No Content

La respuesta no tiene body. Los asientos liberados se notifican a todos los viewers conectados via SignalR.

Tiempo Real — SignalR

SmartTix utiliza SignalR (WebSocket con fallback automático) para propagar cambios de disponibilidad a todos los viewers conectados al mismo evento. El Web Component gestiona la conexión automáticamente.

Conexión

import { HubConnectionBuilder } from '@microsoft/signalr';

const connection = new HubConnectionBuilder()
  .withUrl(`https://api.smarttix.pro/hubs/seats`)
  .withAutomaticReconnect()
  .build();

await connection.start();

// Unirse al grupo del evento
await connection.invoke('JoinEvent', 'evt_abc123def456');

Eventos del servidor

// Escuchar cambios de disponibilidad
connection.on('SeatsHeld', (seatIds) => {
  // Marcar asientos como no disponibles en tu UI
  console.log('Asientos reservados por otro usuario:', seatIds);
});

connection.on('SeatsReleased', (seatIds) => {
  // Marcar asientos como disponibles de nuevo
  console.log('Asientos liberados:', seatIds);
});

Modelos

SeatStatus

Sector Types

PricingConfig

Permite sobreescribir los precios de las categorías o definir tipos de entrada por categoría.

// Precio fijo por categoría
[
  { "category": "VIP", "price": 75 },
  { "category": "General", "price": 30 }
]

// Con tipos de entrada
[
  {
    "category": "Tribuna",
    "ticketTypes": [
      { "ticketType": "Adulto", "price": 40 },
      { "ticketType": "Infantil", "price": 20 }
    ]
  }
]

SelectedSeat

Objeto devuelto por getSelectedSeats() y en los eventos seatSelected.

Códigos de Error

Todos los errores siguen el formato estándar con un campo error que contiene el código y un campo message con la descripción legible.

{
  "error": "SEATS_UNAVAILABLE",
  "message": "Los asientos solicitados ya no están disponibles"
}