Skip to main content
Developer API 是一个 JSON REST API。本参考文档中的每个端点在侧边栏中按资源分组：auth、locations、connections、menu、orders 和 webhooks。本页介绍它们共用的约定；所链接的概念页面则更为深入。

​
基础 URL

每个环境都有各自的主机，均在 /v1 前缀下提供服务：
请使用与主机匹配的凭证（沙盒使用 mpk_test_…，生产环境使用 mpk_live_…）。请参阅环境。

​
身份验证

每个请求都需发送 Bearer 凭证：
将您的 API 密钥（沙盒使用 mpk_test_…，生产环境使用 mpk_live_…）作为 bearer 令牌发送。GET /v1/me 会返回任一密钥对应的应用、环境和权限范围（scopes）。详情请参阅身份验证。

​
资源约定

  • 不透明 ID 带有类型前缀 — str_（门店）、ord_（订单）、dws_（webhook 订阅）、evt_（事件）等。请将它们视为不透明字符串。
  • 金额为整数美分（USD cents）。 450 表示 $4.50。切勿将金额解析为浮点数。货币代码始终为大写的 ISO‑4217 代码（USD）。
  • 字段命名风格。 菜单负载使用 camelCase（externalId、minSelections、modifierGroups）；订单和 webhook 负载使用 snake_case（fulfillment_type、menu_entity_id、payment_status）。订单行项目的 menu_entity_id 携带您为该菜单对象发布的 externalId。
  • 事件和订单的时间戳为 Unix 秒（created 字段）。
  • 对象类型。 大多数资源带有 object 字段（order、location、event 等），便于区分它们。

​
列表

列表端点返回一个信封，其 object 为 list，并带有 data 数组：
列表返回有界窗口并附带 has_more 标志，而不是总数：
  • GET /v1/orders 最多返回您已连接门店的 100 个订单。默认最新的在前；请参阅下方的追赶参数。
  • GET /v1/webhook_events 最多返回 50 个事件，最新的在前。
  • GET /v1/locations 和 GET /v1/webhook_subscriptions 返回您应用的全部内容。

​
停机后拉取订单

GET /v1/orders 接受三个可选查询参数，专为核对积压订单而设计： 请求 GET /v1/orders?since=<checkpoint>&limit=100，然后在 has_more 为 true 时，将 starting_after 设置为上次返回的最后一个订单 id 并重复请求。没有 location_id 过滤器 — 请在客户端按 location_id 过滤。 如果希望让 Maple 重新投递 webhook，而不是自行拉取订单，对于实时订单请使用 POST /v1/orders/{orderId}/resend；当原始事件标识很重要时，请使用事件记录和重放。

​
列出预订

GET /v1/bookings 读取已授权门店的预订，可选用 location_id 缩小范围。start/end 使用 ISO-8601 时刻，跨度最多 31 天；两者都不提供时，窗口为未来七天。或者，updated_since 按最旧在前拉取更新，且不能与时间窗口组合使用。 要查找顾客来电或发短信所询问的预订，请将 location_id 与 phone、confirmation_code 或两者一并传入。电话会先被规范化，因此 (415) 555-0142 和 +14155550142 匹配同一顾客。不带窗口时，查找会匹配任意时间的预订，并按时段开始时间排序；添加 start/end 可缩小到未来几天。在提供商管理的门店，带 phone 的查找还会查询提供商，因此能找到直接在那里所做的预订；仅用确认码的查找则覆盖 Maple 已知的预订。不带 location_id 的查找会返回 400 location_required，无法使用的电话会返回 400 invalid_phone。 使用 limit（1–100，默认 20）分页，并将上一页不透明的 next_cursor 作为 starting_after。跨页时请保持过滤条件不变。默认窗口在其各页之间保持固定。对于检查点轮询，请重叠几秒，并按预订的 id 和 version 去重。 预订使用 bkg_… ID，候位条目使用 bkw_…；所有合作伙伴保留（hold）使用 bkh_…，包括提供商管理的保留。不会暴露提供商的锁令牌。预订资源使用 snake_case；预订配置使用 camelCase。created 为 Unix 秒；starts_at、updated_at、expires_at、published_at 以及楼面的 as_of 为 ISO-8601 时刻。可用时段搜索的边界则是场所本地的挂钟值。

​
错误

错误使用标准 HTTP 状态码，JSON 响应体带有稳定的 _tag 和便于阅读的 message。请根据 tag 而不是 message 进行分支处理。完整目录请参阅错误。

​
速率限制

预订默认限制为每分钟 60 次可用时段搜索和每分钟 300 次其他预订请求（包括候位调用），按应用/环境在各门店间独立计算。每个应用还有一个原子性限制：每个门店最多十个有效或待处理的保留。429 会携带 Retry-After 和以秒为单位的 JSON retry_after。这些预订预算不适用于现有的订单/菜单路由；OAuth 令牌请求有其各自的限制。 请异步响应 webhook，避免密集的轮询循环，并在重试写入时保留原始幂等键。请参阅接受预订。