Схема зала, места и зоны

Метод GET /event-items/{eventItemID}/seats возвращает всё, что нужно, чтобы нарисовать зал и дать покупателю выбрать билеты:

{
  "data": {
    "type": 1,
    "map": { ... },
    "sections": [ ... ],
    "seats": [ ... ],
    "zones": [ ... ],
    "prices": [ ... ]
  }
}

Типы сеансов

Поле type определяет, как продаются билеты:

type	Как продаются билеты	Что передавать в заказе
6	Без схемы зала, по ценовым категориям	prices
любой другой	По схеме зала: отдельные места и/или зоны	seats и/или zones

Для type = 6 поля map, sections, seats, zones обычно пустые, а продажа идёт только по prices.

Из чего состоит схема

map (карта зала, width × height)
 └─ sections (секции: партер, балкон, фан-зона…)
     ├─ objects (декор: сцена, подписи, контуры, картинки)
     ├─ seats   (места с координатами x, y)
     └─ zones   (области без мест: танцпол, VIP-зона)
prices (ценовые категории с цветом и остатком)

• map — размеры полотна (width, height), в координатах которого заданы все объекты. Может быть null, если у сеанса нет схемы.
• sections — логические части зала. У каждой есть массив objects — элементы оформления.
• seats — отдельные места с рядом, номером, ценой и координатами.
• zones — прямоугольники или многоугольники, в которых продаётся определённое число билетов без конкретных мест.
• prices — ценовые категории сеанса. Место или зона ссылается на категорию через price_id.

Места

Место можно забронировать, только если is_available = true. Это значит, что одновременно:

• на место нет билета (ни брони, ни продажи);
• место не заблокировано и не скрыто организатором;
• место доступно для продажи;
• у места есть цена больше нуля.

Поле status (available, locked, reserved, sold, blocked, hidden) — внутренний статус места в Ticket.kg. Для решения о продаже используйте is_available, а не status.

Зоны

Зона — область, в которой продаётся limit билетов без привязки к местам (например, танцпол).

• available — сколько билетов ещё можно купить в зоне.
• Если available = 0, зона распродана или не продаётся.
• Зона без лимита не продаётся (available = 0).

В заказе зона передаётся с количеством:

{ "zones": [{ "zone_id": 11, "quantity": 2 }] }

Ценовые категории

prices нужны для двух целей:

1. Легенда схемы. Цвет и подпись категории для мест и зон с соответствующим price_id.
2. Продажа без мест (type = 6). Билеты заказываются по price_id:

{ "prices": [{ "price_id": 4179, "quantity": 3 }] }

Поля остатка:

• limit и available заполнены, если у категории есть лимит.
• Если оба null, категория не ограничена отдельно. Но может действовать общий лимит сеанса: если его не хватит, заказ вернёт 409 limit_exceeded с details.available.

Многоуровневые схемы

Большие площадки (стадионы, арены) могут иметь иерархическую схему: на общей карте (map.type = "hierarchical") секции ведут на отдельные детальные карты с местами.

1. Запросите /event-items/{id}/seats — получите общую карту. У секций с детальной картой заполнено поле constructor_child_map_id.
2. Когда покупатель выбирает такую секцию, запросите детальную карту:

curl "https://gateway.ticket.kg/api/v1/event-items/2505/seats?child_map_id=318" \
  -H "X-API-Key: $KEY"

В ответе будут map, sections, seats и zones только этой части зала. prices и type всегда относятся ко всему сеансу.

Отрисовка

• Координаты x, y и размеры width, height мест, зон и объектов заданы в системе координат карты (map.width × map.height).
• Объекты (objects) бывают типов text, rect, polygon, image. Текст подписи — в text, адрес картинки — в src, поворот — в rotation.
• Зоны бывают типов rect и polygon.
• Дополнительные параметры фигуры (например, вершины многоугольника) передаются как есть в поле data — в том же формате, в котором схема сохранена в конструкторе залов Ticket.kg.
• Цвета: у места и зоны — color, у ценовой категории — color в prices. Связь места или зоны с категорией — через price_id.

Обновление доступности

Метод не кэшируется и всегда возвращает актуальное состояние. Если покупатель долго выбирает места, перед бронированием можно обновить схему. Но даже актуальная схема не гарантирует, что место не займут за секунду до вашего заказа, поэтому всегда обрабатывайте 409 seat_unavailable.