> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置预订

> 发布原生预订区域、桌位、班次、用餐时长、节奏控制和政策，而无需替换菜单。

原生门店的预订配置描述其座位区域和预订规则。请将完整文档发布到 `POST /v1/locations/{locationId}/booking_configuration`；在同一路径上使用 `GET` 读取。

## 前提条件

* 您的应用已被授予该门店的访问权限。
* 发布需要 `bookings:configure`；读取需要 `bookings:read`。
* Maple 已为该门店启用 `bookings-public-api` 灰度发布开关。
* 该门店使用 Maple 原生连接，或尚无预订连接。由提供方管理的门店会返回 `422 capability_unsupported`。

发布配置**不会**开启预订。商户需在 Maple 控制台（**Settings › Location › Bookings**）中开启预订，或由 Maple 代为开启。在提供可订时段之前，请检查 `booking_profile.enabled`。

## 发布配置

配置请求体使用 camelCase，与菜单文档一致。`poolId` 和 `unitId` 是您自己的稳定标识符。Unit ID 在整份文档中必须唯一。

```json theme={null}
{
  "timeZone": "America/New_York",
  "currency": "USD",
  "areas": [
    {
      "poolId": "dining",
      "name": "Dining Room",
      "kind": "seat",
      "units": [
        { "unitId": "t1", "seats": { "min": 1, "max": 2 } },
        { "unitId": "t2", "seats": { "min": 1, "max": 4 }, "tags": ["window"] }
      ],
      "combinations": [
        { "unitIds": ["t1", "t2"], "seats": { "min": 3, "max": 6 } }
      ]
    }
  ],
  "turnBands": [
    { "minGuests": 1, "maxGuests": 2, "minutes": 90 },
    { "minGuests": 3, "maxGuests": 6, "minutes": 120 }
  ],
  "shifts": [
    { "day": "FRI", "start": "17:00", "end": "23:00" },
    { "day": "SAT", "start": "12:00", "end": "23:00" }
  ],
  "pacing": { "intervalMinutes": 15, "maxCovers": 12, "enforcement": "hard" },
  "bookingPolicy": {
    "minLeadMinutes": 60,
    "maxHorizonDays": 60,
    "slotAlignment": "quarter_hourly",
    "autoConfirm": true
  },
  "cancellationPolicy": {
    "requiresCardOnFile": false,
    "tiers": [],
    "rescheduleCutoffHours": 2,
    "policyText": "Please contact the venue for late changes."
  }
}
```

响应包含规范化后的配置，以及 `object: "booking_configuration"`、`revision`、`location_id`、`version_id`、`published_at` 和 `livemode`。读取时会补全政策的默认值；它不一定逐字节还原您省略的字段。

## 发布时不覆盖店方的修改

餐厅经理可以在 Maple 控制台中编辑同一份配置。为避免替换他们的修改，请先读取配置、修改，然后把您读取到的 `revision` 作为 `expected_revision` 一起发布：

```json theme={null}
{ "...": "the whole configuration", "expected_revision": "<revision from your last read>" }
```

如果配置在您读取之后发生了变化，发布会返回 `409 stale_configuration`，并且不会替换任何内容：请重新读取，重新应用您的修改，并使用新的 revision 发布。首次配置请发送 `"expected_revision": null`。省略 `expected_revision` 会无条件替换配置。`revision` 只在配置本身变化时才会改变；菜单发布会推进 `version_id`，但不会改变 `revision`。

## 发布规则

* 该文档替换的是门店自行编写的预订配置，而不是其菜单或无关的商品目录资源和政策。之后由提供方/菜单发起的发布也会保留该预订配置。
* 重新发布完全相同的配置不会创建新版本。配置没有 `idempotency_key` 字段。
* 变更后的用餐时长或政策对新的可订时段报价生效。现有预订保留其锁定的条款。
* 币种必须与现有商品目录的币种一致。当尚无商品目录时，首次配置会确立币种。
* 时间为场所本地时间 `HH:MM`；班次的结束时间必须晚于开始时间。跨夜营业时间请拆分到不同的日期。
* 用餐时长区间（turn band）必须有序且互不重叠。组合桌必须指定其所在区域内互不相同的桌位。
* 每个区域都可预订。可订时段查询先尝试 `areas` 中的第一个区域，再按 `poolId` 顺序（读取时返回的顺序）尝试其余区域，并把客人安排在第一个有空闲桌位或合适组合桌的区域；预订会一直保留在其入座的区域。班次和休业日适用于整个门店。
* 未知字段、无效的时区/日期以及无效的范围会被拒绝。`400` 校验响应会指出无效的输入。`422 configuration_rejected` 表示该文档无法应用到商品目录。
* 在配置存在之前读取，会返回 `404`。

<Note>
  绑定银行卡/押金的预订流程和收取取消费用是独立的能力；声明政策并不等于支付集成。
</Note>

## 停订日期（Blackout dates）

停订日期指门店营业，但不接受预订的日期或部分时段：私人活动、节假日、仅接待散客的夜晚。它们不同于配置中的 `closedDates`：

| | `closedDates`（配置） | 停订日期 |
| - | - | - |
| 含义 | 场所关门 | 场所营业，但不接受预订 |
| 适用门店 | 仅 Maple 原生门店 | 原生门店和由提供方管理的门店（Maple 会在调用任何提供方之前强制执行） |
| 粒度 | 整天 | 整天，或指定开始和结束时间 |
| 写入方式 | `POST /v1/locations/{locationId}/booking_configuration` | `PUT /v1/locations/{locationId}/booking_blackouts`，或场所的控制台 |

当前列表可从 `GET /v1/locations/{locationId}/booking_profile`（`bookings:read`）的 `blackout_dates` 读取。使用 `bookings:configure` 替换它：

```http theme={null}
PUT /v1/locations/{locationId}/booking_blackouts
```

```json theme={null}
{
  "blackout_dates": [
    { "start_date": "2026-12-24", "end_date": "2026-12-26", "reason": "Holidays" },
    { "start_date": "2026-10-10", "end_date": "2026-10-10", "start_time": "18:00", "end_time": "22:00" }
  ],
  "expected_revision": "<blackout_dates_revision from the booking profile>"
}
```

响应是保存后的列表，按开始时间排序，某个范围缺失的时间或备注为 `null`，并附带其新的 `revision`：`{ "object": "booking_blackouts", "location_id": "…", "blackout_dates": [...], "revision": "…" }`。

* 请求体是完整列表：您省略的范围会被删除，`[]` 会清除全部。场所会在其控制台中编辑同一份列表，因此请从 profile 中读取 `blackout_dates` 和 `blackout_dates_revision`，编辑后把该 revision 作为 `expected_revision` 发送。如果列表在您读取之后发生了变化，写入会返回 `409 stale_blackout_dates`，并且不做任何更改：请重新读取并重新应用您的修改。不带 `expected_revision` 时，写入会替换现有内容。
* 日期为场所本地日期，并且包含首尾两天。不带时间的范围会屏蔽整天；`start_time` 适用于第一天，`end_time` 适用于最后一天。最多 100 个范围，备注最长 200 个字符。
* 无效的范围（不存在的日期、结束早于开始、格式错误的时间）会返回 `400 invalid_blackout_dates`，并且不做任何更改。
* 可订时段查询会省略位于停订期内的时段；原生门店还会拒绝会延伸进停订期的用餐安排。在添加停订之前获取的报价，在保留或预订时会被拒绝：原生门店返回 `409 slot_unavailable`，由提供方管理的门店返回 `422 date_blocked`。停订期内已有的预订不会被取消，保存停订时已在进行中的、由提供方管理的预订也不会被取消。
* 停订只阻止预订，不影响迎宾台：散客（`POST /v1/locations/{locationId}/walk_ins`）和为候位客人安排入座，在停订期内仍然可以按正常的桌位可用情况进行。
* 在由提供方管理的门店，提供方自己的渠道（例如 OpenTable 的网站）看不到 Maple 的列表；场所也需要在那里屏蔽这些日期。

## 配置预订沙盒

在 Maple 的管理门户中，配置合作伙伴沙盒时请选择 **Native bookings + sample floor**。该选项默认关闭。它会创建一个已启用的 Maple 预订连接，并在尚无配置时预置四张桌子、90 分钟的用餐时长和每日营业时间。重新运行会保留已有配置，并拒绝替换 OpenTable 连接。

staging 配置 CLI 通过 `--booking-connection` 提供同样的选项。对于仅使用预订的合作伙伴，您可以跳过 POS 连接；门店授权已足以使用预订。缺少预订权限范围的现有密钥，需要重新生成新的密钥。

配置结果中的 `bookings_configured` 仅确认该步骤已运行，并不表示灰度发布已启用。Maple 必须在 staging PostHog 项目中将该沙盒门店纳入 `bookings-public-api` 的目标范围。然后使用沙盒凭据运行[搜索 → 保留 → 创建 → 取消](/zh/developer-api/guides/take-bookings)流程。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.