> ## 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.

# 更新日志

> Maple Developer API 的重要变更。

Developer API 的变更，包括新端点、新事件类型和行为变化，都记录在这里。[端点参考](/zh/developer-api/api-reference)始终反映当前状态。

<Update label="2026 年 10 月" description="OpenTable 的拒绝现在使用原生错误码">
  * 在由 OpenTable 管理的门店，OpenTable 给出原因的拒绝，现在会返回与 Maple 原生门店相同的错误码和 Maple 自己的表述，而不再是带有 OpenTable 原文的 `422 provider_rejected`。时间太近返回 `422 outside_booking_window`（`details.reason: inside_min_lead`）；预订已开始或即将开始返回 `409 not_changeable` / `409 not_cancellable`（`details.reason: outside_policy_window`）；需要信用卡的时段返回 `422 payment_instrument_required`。其他拒绝仍为 `provider_rejected`。见[错误](/zh/developer-api/concepts/errors)。
</Update>

<Update label="2026 年 10 月" description="仅修改预订备注">
  * `POST /v1/bookings/{bookingId}/change` 可以只传 `notes` 而不传 `slot_token`，仅修改客人的备注：预订的时间、人数和桌位保持不变，因此无需报价。两个字段都不传会返回 `400 change_required`。见[修改或取消](/zh/developer-api/guides/take-bookings)。
</Update>

<Update label="2026 年 9 月" description="特色体验">
  * 在提供特色体验（固定套餐、品鉴、需购票的场次）的门店，可用时段中会按开始时间顺序，与标准时段一并列出这些体验。每个 `booking_slot` 都有 `experience`（`id`、`name`、`description`、`prepayment_required`），标准预订则为 `null`。`experience_id` 可将搜索限定为某一项体验。OpenTable 门店提供此功能；`booking_profile.capabilities.experiences` 说明某门店是否提供。
  * 体验时段通过常规的保留与预订流程预订，`Booking` 资源（及其 webhook 负载）带有 `experience`（`id`、`name`），标准预订则为 `null`。修改时会保留该体验：改为其他体验的时段，或在体验与标准桌位之间切换，会返回 `422 capability_unsupported`。
  * 保留一个要求预先付款的体验时段会返回 `422 payment_instrument_required`：Maple 目前还无法收取付款。见[特色体验](/zh/developer-api/guides/take-bookings)。
</Update>

<Update label="2026 年 9 月" description="OpenTable 门店的已入座预订">
  * 在由 OpenTable 管理的门店，修改或取消一个客人已入座或已结束的预订时，现在会在 Maple 调用 OpenTable 之前就返回 `409 not_changeable` 或 `409 not_cancellable`（原因为 `in_service` 或 `terminal_state`），与 Maple 原生门店的行为一致。
</Update>

<Update label="2026 年 9 月" description="门店可控制客人短信">
  * 餐厅经理现在可以为其门店关闭 Maple 的客人短信。已关闭的门店，`POST /v1/waitlist_entries/{entryId}/notify` 会返回 `422 guest_messaging_unavailable`，与尚未开通客人短信的门店一致。请改为安排入座或移除该组客人。见[管理候位](/zh/developer-api/guides/run-the-waitlist)。
  * 配置发布后，经理也可以自行开启 Maple 预订，因此 `booking_profile.enabled` 可能在 Maple 不介入的情况下发生变化。请在提供可用时段之前继续检查它。
</Update>

<Update label="2026 年 9 月" description="配置修订版本">
  * 预订配置带有 `revision`。发布时带上 `expected_revision`，如果餐厅经理在您读取之后又在 Maple 控制台中编辑过配置，您会收到 `409 stale_configuration`，而不是覆盖他们的修改；`null` 表示预期尚无配置。不带它发布仍会无条件替换配置。见[发布时不覆盖门店的修改](/zh/developer-api/guides/configure-bookings)。
</Update>

<Update label="2026 年 9 月" description="每个用餐区域都可预订">
  * Maple 原生的可用时段现在会在每个已配置的区域安排客人入座，而不只是第一个区域：先尝试第一个区域，再按 `poolId` 顺序尝试其他区域，并在第一个有空桌或可拼桌的区域预订。只有其他区域才能容纳的组（例如露台的大桌）现在也会被提供。人数上下限涵盖所有区域。见[发布规则](/zh/developer-api/guides/configure-bookings)。
</Update>

<Update label="2026 年 9 月" description="按电话或确认码查找预订">
  * `GET /v1/bookings` 新增 `phone` 和 `confirmation_code`，用于查找客人询问的预订。两者都需要 `location_id`；电话号码会先被规范化。不带时间窗口时，查找会匹配任意时间的预订，无论是原生门店还是由第三方管理的门店。不带 `location_id` 的查找会返回 `400 location_required`。见[查找客人的预订](/zh/developer-api/guides/take-bookings)。
</Update>

<Update label="2026 年 9 月" description="预订停订日期">
  * `GET /v1/locations/{locationId}/booking_profile` 会返回门店的 `blackout_dates`：不接受预订的时间窗口。
  * `PUT /v1/locations/{locationId}/booking_blackouts` 在 `bookings:configure` 权限下替换该列表，原生门店和第三方管理的门店均可。把配置中的 `blackout_dates_revision` 作为 `expected_revision` 发送，如果门店有更新的修改，您会收到 `409 stale_blackout_dates`，而不是覆盖它们。无效的范围会返回 `400 invalid_blackout_dates`。见[停订日期](/zh/developer-api/guides/configure-bookings)。
</Update>

<Update label="2026 年 9 月" description="验证错误与反馈提示">
  * 路径参数、查询、请求头或请求体未通过验证的请求，现在会返回 `400` 和 `DeveloperApiBadRequest` 响应体（`code: "invalid_request"`），并指明出错的字段，此前返回的是空响应体。
  * 每个错误响应体都带有一行 `feedback`，指向 [`POST /v1/feedback`](/zh/developer-api/concepts/feedback)。见[错误](/zh/developer-api/concepts/errors)。
</Update>

<Update label="2026 年 9 月" description="反馈">
  * `POST /v1/feedback` 用于报告 bug、缺失的功能、错误的文档或不清楚的错误信息，并引用相关请求的 ID。只有 `kind` 和 `summary` 是必填项。Maple 无法与您最近的请求匹配的 ID 会按原样保留，不会被拒绝。任何凭证都可以发送；不需要权限范围。其契约不会被破坏：字段只会新增，不会删除或改为必填。见[反馈](/zh/developer-api/concepts/feedback)。
</Update>

<Update label="2026 年 9 月" description="散客入座与门店取消">
  * `POST /v1/locations/{locationId}/walk_ins` 让到店的组在现在最早能容纳的桌位入座，并返回已入座的预订；在应用范围的 `idempotency_key` 下可安全重试。见[安排散客入座](/zh/developer-api/concepts/booking-lifecycle)。
  * `POST /v1/bookings/{id}/venue_cancel` 代表门店取消预订（`cancelled_by_venue`），可在客人的取消窗口之外使用。见[以门店身份取消](/zh/developer-api/concepts/booking-lifecycle)。
  * 两者都需要 `bookings:manage`，且适用于 Maple 原生门店。API 参考现在把候位单独列为一个部分。
</Update>

<Update label="2026 年 9 月" description="候位">
  * 在 `bookings:read` 下读取原生门店的散客队列并报价等待时间。
  * 在 `bookings:write` 下，使用应用范围的 `idempotency_key` 添加客人组，并代客人取消。
  * 在 `bookings:manage` 下，通知、安排入座和移除客人组，以及开启或关闭候位。所有客人短信都由 Maple 发送；安排入座会创建一个散客预订。见[管理候位](/zh/developer-api/guides/run-the-waitlist)。
  * 五种候位 webhook 类型（`waitlist_entry.created`、`.notified`、`.seated`、`.removed`、`.expired`），携带该条目的最新状态。见[候位事件](/zh/developer-api/webhook-events)。
</Update>

<Update label="2026 年 9 月" description="配送区域">
  * 已连接门店的配送区域增删改查：在 `delivery_zones:read` / `delivery_zones:write` 下列出、创建、获取、更新和删除区域，范围限定为您应用的有效连接。
  * `POST /v1/locations/{locationId}/delivery_zones/check` 报告某个坐标是否可配送，并返回匹配的区域和费用。见[管理配送区域](/zh/developer-api/guides/delivery-zones)。
</Update>

<Update label="2026 年 9 月" description="预订：按门店逐步开放">
  * 预订配置、有界的可用时段搜索、保留，以及预订的列表/获取/创建/修改/取消。
  * `bookings:manage` 下的门店操作，带版本检查和标明应用来源的审计记录。
  * `bookings:configure` 下的原生配置发布/读取，保留现有菜单。
  * 按需读取实时楼面、八种预订 webhook 类型，以及可选的预订沙盒开通。
  * 应用持有的原生/第三方保留、每个应用/门店原子化的十个保留配额，以及带 `Retry-After` 的独立预订请求/搜索限流。
  * 持久化的第三方写入声明、版本预留、稳定的请求标识，以及在写入结果不确定或镜像失败后的对账。重试规则见[接受预订](/zh/developer-api/guides/take-bookings)。
</Update>

<Update label="2026 年 8 月" description="配送地址、订单补齐和更密集的 webhook 重试">
  * **配送地址**：订单资源和 `order.notification` 负载现在带有 `delivery_address`（街道、单元、城市、州、邮编，以及顾客在 `notes` 中的配送说明）。自取订单和没有已存地址的外送订单为 `null`。见[接收订单](/zh/developer-api/guides/receive-orders)。
  * **订单补齐**：`GET /v1/orders` 支持 `since`、`starting_after` 和 `limit`。使用 `since` 时，结果从一个不含端点的检查点开始，按从旧到新排序，让您在停机后逐页处理积压。见[列表](/zh/developer-api/api-reference)。
  * **订单重发**：`POST /v1/orders/{orderId}/resend` 为一个错过 webhook 的有效订单重新发布一条 `order.notification`，不改变订单状态。需要 `webhooks:write`；终态订单无法重发。
  * **更密集的 webhook 重试**：失败的推送现在最多重试 9 次（此前为 6 次），前几次尝试落在六分钟的 POS 决定窗口内。见[重试与自动停用](/zh/developer-api/concepts/webhooks)。
</Update>

<Update label="2026 年 6 月" description="Developer API 上线">
  Maple Developer API 现已面向 POS 和平台合作伙伴开放。

  * **身份验证**：带权限范围的 API 密钥（沙盒使用 `mpk_test_…`，生产使用 `mpk_live_…`）。
  * **门店与连接**：列出已授权的门店，并作为门店的订单接收方进行连接。
  * **订单**：接收 `order.notification`，读取完整订单，并通过 accept / deny / ready / complete / cancel / status 作出决定。可选的预先验证。
  * **菜单**：以一份以您自己的外部 ID 为键的 JSON 文档发布门店的完整菜单，并可读回。
  * **Webhooks**：订阅事件类型，验证经 HMAC 签名的推送，并从事件记录重放。
</Update>


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