> ## 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 的变更，包括新端点、新事件类型和行为变化，都记录在这里。[端点参考](https://docs.maple.inc/zh/developer-api/api-reference.md)始终反映当前状态。 2026 年 10 月 ## 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`。见[错误](https://docs.maple.inc/zh/developer-api/concepts/errors.md)。 2026 年 10 月 ## 仅修改预订备注 - `POST /v1/bookings/{bookingId}/change` 可以只传 `notes` 而不传 `slot_token`，仅修改客人的备注：预订的时间、人数和桌位保持不变，因此无需报价。两个字段都不传会返回 `400 change_required`。见[修改或取消](https://docs.maple.inc/zh/developer-api/guides/take-bookings.md)。 2026 年 9 月 ## 特色体验 - 在提供特色体验（固定套餐、品鉴、需购票的场次）的门店，可用时段中会按开始时间顺序，与标准时段一并列出这些体验。每个 `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 目前还无法收取付款。见[特色体验](https://docs.maple.inc/zh/developer-api/guides/take-bookings.md)。 2026 年 9 月 ## OpenTable 门店的已入座预订 - 在由 OpenTable 管理的门店，修改或取消一个客人已入座或已结束的预订时，现在会在 Maple 调用 OpenTable 之前就返回 `409 not_changeable` 或 `409 not_cancellable`（原因为 `in_service` 或 `terminal_state`），与 Maple 原生门店的行为一致。 2026 年 9 月 ## 门店可控制客人短信 - 餐厅经理现在可以为其门店关闭 Maple 的客人短信。已关闭的门店，`POST /v1/waitlist_entries/{entryId}/notify` 会返回 `422 guest_messaging_unavailable`，与尚未开通客人短信的门店一致。请改为安排入座或移除该组客人。见[管理候位](https://docs.maple.inc/zh/developer-api/guides/run-the-waitlist.md)。 - 配置发布后，经理也可以自行开启 Maple 预订，因此 `booking_profile.enabled` 可能在 Maple 不介入的情况下发生变化。请在提供可用时段之前继续检查它。 2026 年 9 月 ## 配置修订版本 - 预订配置带有 `revision`。发布时带上 `expected_revision`，如果餐厅经理在您读取之后又在 Maple 控制台中编辑过配置，您会收到 `409 stale_configuration`，而不是覆盖他们的修改；`null` 表示预期尚无配置。不带它发布仍会无条件替换配置。见[发布时不覆盖门店的修改](https://docs.maple.inc/zh/developer-api/guides/configure-bookings.md)。 2026 年 9 月 ## 每个用餐区域都可预订 - Maple 原生的可用时段现在会在每个已配置的区域安排客人入座，而不只是第一个区域：先尝试第一个区域，再按 `poolId` 顺序尝试其他区域，并在第一个有空桌或可拼桌的区域预订。只有其他区域才能容纳的组（例如露台的大桌）现在也会被提供。人数上下限涵盖所有区域。见[发布规则](https://docs.maple.inc/zh/developer-api/guides/configure-bookings.md)。 2026 年 9 月 ## 按电话或确认码查找预订 - `GET /v1/bookings` 新增 `phone` 和 `confirmation_code`，用于查找客人询问的预订。两者都需要 `location_id`；电话号码会先被规范化。不带时间窗口时，查找会匹配任意时间的预订，无论是原生门店还是由第三方管理的门店。不带 `location_id` 的查找会返回 `400 location_required`。见[查找客人的预订](https://docs.maple.inc/zh/developer-api/guides/take-bookings.md)。 2026 年 9 月 ## 预订停订日期 - `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`。见[停订日期](https://docs.maple.inc/zh/developer-api/guides/configure-bookings.md)。 2026 年 9 月 ## 验证错误与反馈提示 - 路径参数、查询、请求头或请求体未通过验证的请求，现在会返回 `400` 和 `DeveloperApiBadRequest` 响应体（`code: "invalid_request"`），并指明出错的字段，此前返回的是空响应体。 - 每个错误响应体都带有一行 `feedback`，指向 [`POST /v1/feedback`](https://docs.maple.inc/zh/developer-api/concepts/feedback.md)。见[错误](https://docs.maple.inc/zh/developer-api/concepts/errors.md)。 2026 年 9 月 ## 反馈 - `POST /v1/feedback` 用于报告 bug、缺失的功能、错误的文档或不清楚的错误信息，并引用相关请求的 ID。只有 `kind` 和 `summary` 是必填项。Maple 无法与您最近的请求匹配的 ID 会按原样保留，不会被拒绝。任何凭证都可以发送；不需要权限范围。其契约不会被破坏：字段只会新增，不会删除或改为必填。见[反馈](https://docs.maple.inc/zh/developer-api/concepts/feedback.md)。 2026 年 9 月 ## 散客入座与门店取消 - `POST /v1/locations/{locationId}/walk_ins` 让到店的组在现在最早能容纳的桌位入座，并返回已入座的预订；在应用范围的 `idempotency_key` 下可安全重试。见[安排散客入座](https://docs.maple.inc/zh/developer-api/concepts/booking-lifecycle.md)。 - `POST /v1/bookings/{id}/venue_cancel` 代表门店取消预订（`cancelled_by_venue`），可在客人的取消窗口之外使用。见[以门店身份取消](https://docs.maple.inc/zh/developer-api/concepts/booking-lifecycle.md)。 - 两者都需要 `bookings:manage`，且适用于 Maple 原生门店。API 参考现在把候位单独列为一个部分。 2026 年 9 月 ## 候位 - 在 `bookings:read` 下读取原生门店的散客队列并报价等待时间。 - 在 `bookings:write` 下，使用应用范围的 `idempotency_key` 添加客人组，并代客人取消。 - 在 `bookings:manage` 下，通知、安排入座和移除客人组，以及开启或关闭候位。所有客人短信都由 Maple 发送；安排入座会创建一个散客预订。见[管理候位](https://docs.maple.inc/zh/developer-api/guides/run-the-waitlist.md)。 - 五种候位 webhook 类型（`waitlist_entry.created`、`.notified`、`.seated`、`.removed`、`.expired`），携带该条目的最新状态。见[候位事件](https://docs.maple.inc/zh/developer-api/webhook-events.md)。 2026 年 9 月 ## 配送区域 - 已连接门店的配送区域增删改查：在 `delivery_zones:read` / `delivery_zones:write` 下列出、创建、获取、更新和删除区域，范围限定为您应用的有效连接。 - `POST /v1/locations/{locationId}/delivery_zones/check` 报告某个坐标是否可配送，并返回匹配的区域和费用。见[管理配送区域](https://docs.maple.inc/zh/developer-api/guides/delivery-zones.md)。 2026 年 9 月 ## 预订：按门店逐步开放 - 预订配置、有界的可用时段搜索、保留，以及预订的列表/获取/创建/修改/取消。 - `bookings:manage` 下的门店操作，带版本检查和标明应用来源的审计记录。 - `bookings:configure` 下的原生配置发布/读取，保留现有菜单。 - 按需读取实时楼面、八种预订 webhook 类型，以及可选的预订沙盒开通。 - 应用持有的原生/第三方保留、每个应用/门店原子化的十个保留配额，以及带 `Retry-After` 的独立预订请求/搜索限流。 - 持久化的第三方写入声明、版本预留、稳定的请求标识，以及在写入结果不确定或镜像失败后的对账。重试规则见[接受预订](https://docs.maple.inc/zh/developer-api/guides/take-bookings.md)。 2026 年 8 月 ## 配送地址、订单补齐和更密集的 webhook 重试 - **配送地址**：订单资源和 `order.notification` 负载现在带有 `delivery_address`（街道、单元、城市、州、邮编，以及顾客在 `notes` 中的配送说明）。自取订单和没有已存地址的外送订单为 `null`。见[接收订单](https://docs.maple.inc/zh/developer-api/guides/receive-orders.md)。 - **订单补齐**：`GET /v1/orders` 支持 `since`、`starting_after` 和 `limit`。使用 `since` 时，结果从一个不含端点的检查点开始，按从旧到新排序，让您在停机后逐页处理积压。见[列表](https://docs.maple.inc/zh/developer-api/api-reference.md)。 - **订单重发**：`POST /v1/orders/{orderId}/resend` 为一个错过 webhook 的有效订单重新发布一条 `order.notification`，不改变订单状态。需要 `webhooks:write`；终态订单无法重发。 - **更密集的 webhook 重试**：失败的推送现在最多重试 9 次（此前为 6 次），前几次尝试落在六分钟的 POS 决定窗口内。见[重试与自动停用](https://docs.maple.inc/zh/developer-api/concepts/webhooks.md)。 2026 年 8 月 ## 顾客电话和预约订单 - **预约订单**：订单资源和 `order.notification` 负载现在带有 `scheduled_for`：请求的备好时间，为 ISO 8601 UTC 时间戳；若订单要求尽快完成则为 `null`。 - **顾客电话**：订单和 `order.notification` 中现在包含 `customer.phone`（E.164 格式，或 `null`）和 `customer.phone_last_four`。见[接收订单](https://docs.maple.inc/zh/developer-api/guides/receive-orders.md)。 2026 年 6 月 ## Developer API 上线 Maple Developer API 现已面向 POS 和平台合作伙伴开放。 - **身份验证**：带权限范围的 API 密钥（沙盒使用 `mpk_test_…`，生产使用 `mpk_live_…`）。 - **门店与连接**：列出已授权的门店，并作为门店的订单接收方进行连接。 - **订单**：接收 `order.notification`，读取完整订单，并通过 accept / deny / ready / complete / cancel / status 作出决定。可选的预先验证。 - **菜单**：以一份以您自己的外部 ID 为键的 JSON 文档发布门店的完整菜单，并可读回。 - **Webhooks**：订阅事件类型，验证经 HMAC 签名的推送，并从事件记录重放。