База знаний

Начало работы

Это руководство показывает кратчайший практичный путь от нуля до рабочего бронировочного представления Seatmap Pro на вашей странице продаж.

Если вам удобнее видеоформат, воспользуйтесь обзором:

Полный видеообзор (YouTube)

Компоненты Seatmap Pro

Сквозной процесс включает четыре компонента:

Editor: создание площадок и схем, управление ценами и публикация изменений.
Booking Renderer: интерактивная схема на вашем сайте или мобильной странице продаж.
Admin Renderer: операционные инструменты для менеджеров и групп поддержки.
Booking API: серверное управление событиями, состоянием мест, блокировками и продажами.

Общий процесс работы во время выполнения:

Менеджер настраивает площадку и схему в Editor.
Ваш бэкенд создаёт событие и управляет состоянием мест через Booking API.
Покупатель открывает страницу продаж, где Booking Renderer загружается по publicKey + eventId.
Выбор и оформление заказа обновляют доступность, и рендерер отражает актуальное состояние.

Шаг 1. Нарисуйте и опубликуйте свою первую схему

Начните в Seatmap Editor.

Доступ к Editor может быть:

предоставлен Seatmap Pro (SaaS), или
развёрнут в вашей инфраструктуре (on-prem через Docker/Kubernetes).

После входа откройте список площадок и выберите существующую площадку или создайте новую.

Откройте рабочую область редактирования схемы и спроектируйте раскладку (секции, ряды, места, геометрия).

Опубликуйте схему, чтобы она стала доступна для использования через рендерер/API.

Справка: Руководство пользователя Editor

Шаг 2. Скопируйте интеграционные учётные данные из панели администратора

В панели администратора Editor откройте сведения об организации и скопируйте:

Public API Key (используется Booking Renderer на стороне клиента)
Organization token (используется как X-API-Key в серверных вызовах API)

Настройки организации с публичным ключом

Справка: Управление доступом

Шаг 3. Создайте событие на бэкенде и сохраните `eventId`

Событие связывает вашу опубликованную схему с конкретным показом/датой.

Вызовите Booking API из вашего бэкенда:

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
  }'

Затем:

сохраните возвращённый eventId в записи вашего события
верните этот eventId на вашу страницу продаж

Это критически важный мост между вашей предметной областью продажи билетов и инициализацией рендерера.

Вы также можете создать событие через интерфейс Editor, перейдя на вкладку «События» и создав новое событие там. Подробнее об управлении событиями через интерфейс читайте в этом разделе.

Шаг 4. Создайте и назначьте цены (бэкенд)

Создайте цены для события:

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
    }
  ]'

Назначьте созданную цену местам:

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 — это идентификатор объекта места из метаданных схемы, а assignmentId — идентификатор созданного назначения цены.

Составные ключи

Для адресации атрибутов места (цена, блокировка, состояние продажи) Seatmap Pro использует составные ключи на естественном языке.

Пример:

Место Section B, Row 5, Seat 14 -> Section B;;5;;14

Используйте составные ключи как основной способ адресации для операций на уровне места.

Входная зона: места адресуются по имени секции.

Чтобы получить составные ключи для схемы, используйте соответствующий метод getMeta из раздела Venues/API.

Опционально: вы можете управлять ценами напрямую в режиме цен Editor вместо назначения их через серверный API.

Шаг 5. Инициализируйте Booking Renderer через SDK

Инициализация рендерера на странице продаж

Установите пакет (выберите один вариант):

npm install @seatmap.pro/renderer

yarn add @seatmap.pro/renderer

pnpm add @seatmap.pro/renderer

Справка по SDK: Инициализация SDK

Добавьте контейнер рендерера в шаблон вашей страницы продаж:

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

Затем инициализируйте рендерер в коде вашего приложения, например:

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;
}

Обязательные значения времени выполнения:

publicKey: из настроек организации в панели администратора Editor.
eventId: создаётся и сохраняется вашим бэкендом для конкретного показа.

Шаг 6. Обрабатывайте операции с местами

Рендерер предоставляет колбэки для событий мест и взаимодействий, включая:

выбор места
отмену выбора места
наведение и потерю фокуса

Для начала работы основной точкой интеграции является onSeatSelect.

После срабатывания колбэка обычно выбирают один из следующих подходов:

Хранить выбор только в локальной корзине и синхронизировать с бэкендом позже (например, при оформлении заказа).
Блокировать или разблокировать места при каждом событии выбора/отмены выбора (схема «блокировка по клику»).

Для продакшен-продажи билетов схема «блокировка по клику» обычно является более безопасным подходом.

Схема «блокировка по клику»:

Пользователь выбирает место на странице продаж.
Рендерер вызывает колбэк и уведомляет код вашей страницы продаж.
Страница продаж отправляет запрос на блокировку в ваш бэкенд продажи билетов.
Бэкенд выполняет внутренние проверки состояния и проверяет, разрешена ли блокировка.
Бэкенд вызывает Booking API для блокировки места.

Процесс операций с местами при блокировке по клику

Шаг 7. Протестируйте интеграцию

Вы готовы к продакшен-интеграции, когда:

схема опубликована и видна в Editor
публичный API-ключ и токен организации скопированы из настроек организации
бэкенд может предоставить валидный eventId для показа
бэкенд может создавать цены и назначать их объектам мест
страница продаж отображает схему и взаимодействия с местами работают
процесс оформления заказа корректно обновляет состояние мест

Если вам нужен готовый пример HTML/CSS/JS, смотрите:

Рабочее демо (CodePen)

Пример итогового размещения рендерера на странице продаж:

Рендерер, встроенный в раскладку страницы продажи билетов

Дополнительные материалы

Visual Workshop: How to Build Beautiful Maps – разбор проектирования реалистичной раскладки арены в Editor
Step-by-step guide to starting your venue chart – от регистрации до работающей схемы рассадки
Why API integration is crucial for ticketing platforms – как Booking API вписывается в продакшен-процесс продажи билетов