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