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.
Diagrama de los cinco pasos: crear el esquema, crear el evento, asignar precios, integrar el renderizador y completar la compra
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.
Captura de pantalla de la lista de recintos y la creación de un recinto en el Editor
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).
Captura de pantalla de la página de edición de esquemas en el Editor
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)
  • Clave API secreta (usada como X-API-Key en las llamadas a la API del backend)
Captura de pantalla de la configuración de la organización con la clave pública
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

Diagrama: tu backend crea el evento mediante la Booking API y guarda el eventId que devuelve
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.

Captura de pantalla de la visión general de Events Hub
Visión general de Events Hub

Paso 4. Crea y asigna precios (backend)

Diagrama: tu backend crea los precios del evento y los asigna a asientos y áreas de admisión general mediante la Booking API
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.

ID de asientos y áreas

La Booking API v2 identifica cada asiento y cada área de admisión general por su ID numérico, tanto en las asignaciones de precios como en las operaciones con asientos. Un área de admisión general también recibe un número de plazas: activeCount en una asignación de precio, y capacity en las llamadas de bloqueo, desbloqueo y venta.

Para leer los ID de los asientos de un evento, usa su listado de asientos, GET /api/private/v2.0/events/<EVENT_ID>/seats/. Devuelve los asientos del evento página a página, cada uno con su fila y su sección, por ID y por etiqueta, junto con el estado y el precio del asiento.

El renderizador informa de cada asiento seleccionado con su id numérico y una clave compuesta (key) como Section B;;5;;14. Envía el id a la Booking API v2; si un asiento llega sin él, búscalo por las etiquetas de sección, fila y asiento en el listado de asientos. Las claves compuestas solo identifican asientos en la API v1 heredada.

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

Diagrama: la página de venta crea el renderizador con la clave pública y carga el evento desde la Booking API
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.
Diagrama del bloqueo por clic: el renderizador informa del asiento seleccionado, tu backend lo comprueba y bloquea el asiento mediante la Booking API
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:

Captura de pantalla de un mapa de asientos mostrado en una página de venta de entradas
Renderizador integrado en la distribución de una página de venta de entradas

Lecturas adicionales

Escriba una función, un ajuste, un endpoint o un método del SDK.