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

# 约定

> 所有 Developer API 端点共用的基础 URL、资源约定、ID、金额和列表行为。

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

## 基础 URL

每个环境都有各自的主机，均在 `/v1` 前缀下提供服务：

```
https://api.staging.maple.inc/v1   # Sandbox — development and testing
https://api.maple.inc/v1           # Production — live traffic
```

请使用与主机匹配的凭证（沙盒使用 `mpk_test_…`，生产环境使用 `mpk_live_…`）。请参阅[环境](/zh/developer-api/concepts/environments)。

## 身份验证

每个请求都需发送 `Bearer` 凭证：

```http theme={null}
Authorization: Bearer mpk_test_…
```

将您的 API 密钥（沙盒使用 `mpk_test_…`，生产环境使用 `mpk_live_…`）作为 bearer 令牌发送。`GET /v1/me` 会返回任一密钥对应的应用、环境和权限范围（scopes）。详情请参阅[身份验证](/zh/developer-api/concepts/authentication)。

## 资源约定

* **不透明 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` 数组：

```json theme={null}
{ "object": "list", "data": [ /* … */ ] }
```

列表返回**有界窗口**并附带 `has_more` 标志，而不是总数：

* `GET /v1/orders` 最多返回您已连接门店的 100 个订单。默认最新的在前；请参阅下方的追赶参数。
* `GET /v1/webhook_events` 最多返回 50 个事件，最新的在前。
* `GET /v1/locations` 和 `GET /v1/webhook_subscriptions` 返回您应用的全部内容。

### 停机后拉取订单

`GET /v1/orders` 接受三个可选查询参数，专为核对积压订单而设计：

| 参数 | 含义 |
| - | - |
| `since` | 不含边界的 ISO 8601（UTC）检查点。使用 `since` 时，结果**最旧的在前**，这样您可以向前拉取，而不会跳过时间戳相同的订单。 |
| `starting_after` | 上一页的最后一个订单 id（`ord_…`）。需要配合 `since` 使用，且该订单必须属于您的应用。 |
| `limit` | 每页数量，1–100。默认为 100。 |

请求 `GET /v1/orders?since=<checkpoint>&limit=100`，然后在 `has_more` 为 true 时，将 `starting_after` 设置为上次返回的最后一个订单 id 并重复请求。没有 `location_id` 过滤器 — 请在客户端按 `location_id` 过滤。

如果希望让 Maple 重新投递 webhook，而不是自行拉取订单，对于实时订单请使用 [`POST /v1/orders/{orderId}/resend`](/zh/developer-api/guides/receive-orders)；当原始事件标识很重要时，请使用[事件记录和重放](/zh/developer-api/concepts/webhooks)。

### 列出预订

`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 进行分支处理。完整目录请参阅[错误](/zh/developer-api/concepts/errors)。

## 速率限制

预订默认限制为每分钟 60 次可用时段搜索和每分钟 300 次其他预订请求（包括候位调用），按应用/环境在各门店间独立计算。每个应用还有一个原子性限制：每个门店最多十个有效或待处理的保留。`429` 会携带 `Retry-After` 和以秒为单位的 JSON `retry_after`。这些预订预算不适用于现有的订单/菜单路由；OAuth 令牌请求有其各自的限制。

请异步响应 webhook，避免密集的轮询循环，并在重试写入时保留原始幂等键。请参阅[接受预订](/zh/developer-api/guides/take-bookings)。


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