Skip to main content
原生门店的预订配置描述其座位区域和预订规则。请将完整文档发布到 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 在整份文档中必须唯一。
响应包含规范化后的配置，以及 object: "booking_configuration"、revision、location_id、version_id、published_at 和 livemode。读取时会补全政策的默认值；它不一定逐字节还原您省略的字段。

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

餐厅经理可以在 Maple 控制台中编辑同一份配置。为避免替换他们的修改，请先读取配置、修改，然后把您读取到的 revision 作为 expected_revision 一起发布：
如果配置在您读取之后发生了变化，发布会返回 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。
绑定银行卡/押金的预订流程和收取取消费用是独立的能力；声明政策并不等于支付集成。

​
停订日期（Blackout dates）

停订日期指门店营业，但不接受预订的日期或部分时段：私人活动、节假日、仅接待散客的夜晚。它们不同于配置中的 closedDates： 当前列表可从 GET /v1/locations/{locationId}/booking_profile（bookings:read）的 blackout_dates 读取。使用 bookings:configure 替换它：
响应是保存后的列表，按开始时间排序，某个范围缺失的时间或备注为 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 的目标范围。然后使用沙盒凭据运行搜索 → 保留 → 创建 → 取消流程。