知识库

快速入门

本指南介绍从零开始，在售票页面上实现 Seatmap Pro 预订视图的最简实用路径。

如需视频演示，请观看：

完整操作视频（YouTube）

Seatmap Pro 组件

完整流程包含四个组件：

Editor：创建场地和座位图，管理定价并发布更改。
Booking Renderer：网站或移动端售票页面上的交互式座位图。
Admin Renderer：面向管理人员和客服团队的运营工具。
Booking API：从后端控制活动、座位状态、锁定和销售。

运行流程概览：

管理人员在 Editor 中配置场地和座位图。
您的后端通过 Booking API 创建活动并管理座位状态。
顾客打开售票页面，Booking Renderer 使用 publicKey 和 eventId 加载活动。
选座和结算会更新可用状态，Renderer 随之显示最新状态。

五步流程：创建座位图、创建活动、分配价格、嵌入渲染器、执行结算 — 完整入门流程

第 1 步：绘制并发布第一个座位图

从 Seatmap Editor 开始。Editor 可以由 Seatmap Pro 提供（SaaS），也可以通过 Docker/Kubernetes 部署在您的基础设施中。

登录后打开场地列表，选择现有场地或创建新场地。

打开座位图编辑工作区，设计区域、排、座位及几何布局。

发布座位图，使其可供 Renderer 和 API 使用。

参考：Editor 用户指南

第 2 步：从管理面板复制集成凭据

在 Editor 管理面板中打开组织详情，复制：

Public API key：公共 API 密钥，供客户端 Booking Renderer 使用。
Secret API key：私密 API 密钥，用于后端 API 调用的 X-API-Key 请求头。

参考：访问管理

第 3 步：在后端创建活动并保存 `eventId`

后端通过 Booking API 创建活动并保存返回的 eventId — 创建活动并传递 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 返回给售票页面。

这是票务业务与 Renderer 初始化之间的关键连接。

也可以在 Editor 界面中点击 Events 标签页创建活动。有关通过界面管理活动的详情，请参阅活动中心。

第 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 是座位图元数据中的座位对象 ID，assignmentId 是已创建的价格分配 ID。

座位和区域 ID

Booking API v2 在价格分配和座位操作中都使用数字 ID 标识座位及通用入场区。通用入场区还需要名额数量：价格分配使用 activeCount，锁定、解锁和销售调用使用 capacity。

通过 GET /api/private/v2.0/events/<EVENT_ID>/seats/ 获取活动座位列表，以读取座位 ID。该接口分页返回活动座位，包括排和区域的 ID 与标签，以及座位状态和价格。

Renderer 会为选中的座位提供数字 id 和类似 Section B;;5;;14 的组合 key。向 Booking API v2 传递 id；如果座位没有 ID，请在座位列表中按区域、排及座位标签查找。组合键仅用于旧版 v1 API 的座位寻址。

可选：您也可以直接在 Editor 的定价模式中管理价格，无需通过后端 API 分配。

第 5 步：通过 SDK 初始化 Booking Renderer

售票页面使用公共密钥创建渲染器，并从 Booking API 加载活动 — 在售票页面初始化 Renderer

选择一种方式安装包：

npm install @seatmap.pro/renderer

yarn add @seatmap.pro/renderer

pnpm add @seatmap.pro/renderer

SDK 参考：初始化 SDK

在售票页面模板中添加 Renderer 容器：

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

然后在应用代码中初始化 Renderer，例如：

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 步：处理座位操作

Renderer 提供座位和交互事件的回调，包括选中座位、取消选座，以及悬停和移出交互。

入门时主要使用 onSeatSelect。回调触发后通常有两种处理方式：

仅在本地购物车中保存选择，稍后（例如结算时）同步到后端。
每次选中或取消选择时锁定或解锁座位（逐次点击锁定流程）。

对于生产环境的票务系统，逐次点击锁定通常更稳妥。

逐次点击锁定流程：

用户在售票页面选择座位。
Renderer 触发回调，通知售票页面代码。
售票页面向您的票务后端发送锁定请求。
后端检查内部状态，验证是否允许锁定。
后端调用 Booking API 锁定座位。

第 7 步：测试集成

满足以下条件即可进入生产集成阶段：

座位图已发布，并在 Editor 中可见。
已从组织设置复制公共和私密 API 密钥。
后端能提供演出的有效 eventId。
后端能创建价格并分配给座位对象。
售票页面能渲染座位图，座位交互正常。
结算流程能正确更新座位状态。

如需现成的 HTML/CSS/JS 示例，请参阅：

可运行演示（CodePen）

Renderer 在售票页面中的最终效果示例：