1. Base de conocimiento

Primeros pasos

Esta guía muestra el camino práctico más corto desde cero hasta una vista de reserva de Seatmap Pro funcionando en tu página de venta.

Si prefieres un formato en vídeo, usa el recorrido:

Componentes de Seatmap Pro

El flujo de extremo a extremo incluye cuatro componentes:

  • Editor: crea recintos y esquemas, gestiona precios y publica cambios.
  • Booking Renderer: gráfico interactivo en tu sitio web o página de venta móvil.
  • Admin Renderer: herramientas operativas para gestores y equipos de soporte.
  • Booking API: control de backend para eventos, estado de asientos, bloqueos y ventas.

Flujo general en tiempo de ejecución:

  1. El gestor configura el recinto/esquema en Editor.
  2. Tu backend crea el evento y gestiona el estado de los asientos a través de Booking API.
  3. El cliente abre la página de venta donde Booking Renderer se carga mediante publicKey + eventId.
  4. La selección/pago actualizan la disponibilidad y el renderizador refleja el estado más reciente.
Flujo de primeros pasos de extremo a extremo

Paso 1. Dibuja y publica tu primer esquema

Empieza en Seatmap Editor.

El acceso a Editor puede ser:

  • proporcionado por Seatmap Pro (SaaS), o
  • desplegado en tu infraestructura (on-prem mediante Docker/Kubernetes).
  1. Abre la lista de recintos después de iniciar sesión y selecciona un recinto existente o crea uno nuevo.
Lista de recintos y creación de recinto
  1. Abre el espacio de trabajo de edición de esquemas y diseña la distribución (secciones, filas, asientos, geometría).
Página de edición de esquema
  1. Publica el esquema para que quede disponible para su uso por el renderizador/API.

Referencia: Guía de usuario de Editor

Paso 2. Copia las credenciales de integración desde el panel de administración

En el panel de administración de Editor, abre los detalles de la organización y copia:

  • Public API Key (usada por Booking Renderer en el lado del cliente)
  • Organization token (usada como X-API-Key en las llamadas a la API del backend)
Configuración de la organización con la clave pública

Referencia: Gestión de acceso

Paso 3. Crea el evento en el backend y conserva el eventId

Creación del evento y traspaso del eventId

Un evento vincula tu esquema publicado con un espectáculo/fecha específica.

Llama a Booking API desde tu backend:

curl -X POST "https://booking.seatmap.pro/api/private/v2.0/events/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <ORGANIZATION_TOKEN>" \
  -H "X-Organization-ID: <ORGANIZATION_ID>" \
  -d '{
    "id": null,
    "createdDate": null,
    "start": "2025-12-03T20:00:00Z",
    "endDate": "2025-12-03T22:30:00Z",
    "name": "My Concert - Dec 03 2025",
    "schemaId": 3275
  }'

Luego:

  • guarda el eventId devuelto en el registro de tu evento
  • devuelve este eventId a tu página de venta

Este es el puente crítico entre tu dominio de venta de entradas y la inicialización del renderizador.

También puedes crear un evento mediante la interfaz de Editor haciendo clic en la pestaña Eventos y creando un nuevo evento desde allí. Para más información sobre la gestión de eventos a través de la interfaz, lee esta sección.

Visión general de Events Hub

Paso 4. Crea y asigna precios (backend)

Flujo de creación y asignación de precios

Crea precios para el evento:

curl -X POST "https://booking.seatmap.pro/api/private/v2.0/event/<EVENT_ID>/prices/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <ORGANIZATION_TOKEN>" \
  -H "X-Organization-ID: <ORGANIZATION_ID>" \
  -d '[
    {
      "id": null,
      "name": "2000",
      "eventId": "<EVENT_ID>",
      "externalId": null
    }
  ]'

Asigna el precio creado a los asientos:

curl -X POST "https://booking.seatmap.pro/api/private/v2.0/event/<EVENT_ID>/prices/assignments/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <ORGANIZATION_TOKEN>" \
  -H "X-Organization-ID: <ORGANIZATION_ID>" \
  -d '{
    "seats": [
      {
        "objectId": 5142395,
        "assignmentId": 3618500,
        "activeCount": null
      }
    ]
  }'

objectId es el ID del objeto de asiento de los metadatos del esquema, y assignmentId es el ID de la asignación de precio creada.

Claves compuestas

Para direccionar los atributos del asiento (precio, bloqueo, estado de venta), Seatmap Pro usa claves compuestas en lenguaje natural.

Ejemplo:

  • Asiento Section B, Row 5, Seat 14 -> Section B;;5;;14

Usa las claves compuestas como la opción principal de direccionamiento para operaciones a nivel de asiento.

Admisión General: los asientos se direccionan por el nombre de la sección.

Para obtener las claves compuestas de un esquema, usa el método getMeta correspondiente de la sección Venues/API.

Opcional: puedes gestionar precios directamente en el modo de precios de Editor en lugar de asignarlos a través de la API del backend.

Paso 5. Inicializa Booking Renderer mediante el SDK

Inicialización del renderizador en la página de venta

Instala el paquete (elige uno):

npm install @seatmap.pro/renderer

yarn add @seatmap.pro/renderer

pnpm add @seatmap.pro/renderer

Referencia del SDK: Inicialización del SDK

Añade un contenedor del renderizador a la plantilla de tu página de venta:

<div id="seatmap-root" style="width: 100%; height: 600px;"></div>

Luego inicializa el renderizador en el código de tu aplicación, por ejemplo:

import { SeatmapBookingRenderer } from '@seatmap.pro/renderer';

type SeatmapConfig = {
  eventId: string;
  publicKey: string;
};

async function initSeatmap(container: HTMLElement, cfg: SeatmapConfig) {
  const renderer = new SeatmapBookingRenderer(container, {
    publicKey: cfg.publicKey,
    onSeatSelect: (seat) => {
      console.log('select', seat);
      // sync selection with your cart/back-end
    },
    onSeatDeselect: (seat) => {
      console.log('deselect', seat);
      // sync deselection with your cart/back-end
    },
  });

  await renderer.loadEvent(cfg.eventId);
  return renderer;
}

Valores requeridos en tiempo de ejecución:

  • publicKey: de la configuración de la organización en el panel de administración de Editor.
  • eventId: creado y almacenado por tu backend para un espectáculo específico.

Paso 6. Gestiona las operaciones con asientos

El renderizador expone callbacks para eventos de asiento y de interacción, incluyendo:

  • selección de asiento
  • deselección de asiento
  • interacciones de hover y blur

Para empezar, el principal punto de integración es onSeatSelect.

Después de que se dispara el callback, normalmente eliges uno de estos enfoques:

  1. Mantener la selección solo en un carrito local y sincronizar con el backend más tarde (por ejemplo, al finalizar la compra).
  2. Bloquear o desbloquear asientos en cada evento de selección/deselección (flujo de bloqueo por clic).

Para venta de entradas en producción, el bloqueo por clic suele ser el enfoque más seguro.

Flujo de bloqueo por clic:

  1. El usuario selecciona un asiento en la página de venta.
  2. El renderizador dispara el callback y notifica al código de tu página de ventas.
  3. La página de ventas envía una solicitud de bloqueo a tu backend de venta de entradas.
  4. El backend realiza comprobaciones internas de estado y valida que el bloqueo está permitido.
  5. El backend llama a Booking API para bloquear el asiento.
Flujo de operaciones con asientos con bloqueo por clic

Paso 7. Prueba la integración

Estás listo para la integración en producción cuando:

  • el esquema está publicado y visible en Editor
  • la clave pública de API y el token de organización están copiados desde la configuración de la organización
  • el backend puede proporcionar un eventId válido para un espectáculo
  • el backend puede crear precios y asignarlos a los objetos de asiento
  • la página de venta renderiza el gráfico y las interacciones con asientos funcionan
  • el flujo de pago actualiza correctamente el estado de los asientos

Si quieres un ejemplo listo de HTML/CSS/JS, consulta:

Ejemplo de la ubicación final del renderizador en una página de venta:

Renderizador integrado en la distribución de una página de venta de entradas

Lecturas adicionales