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

# Postman 集合

> 一个可直接运行的 Postman 集合，涵盖整个 Developer API，并已配置好认证和请求串联。

Postman 集合涵盖 Developer API——状态与认证、门店与连接、菜单读取/发布、配送区域、完整的订单流程、webhook、预订、候位以及反馈。它附带辅助脚本，让您无需在请求之间复制粘贴 ID，就能端到端地运行一个流程。

## 下载

- [集合](https://docs.maple.inc/developer-api/postman/maple-developer-api.postman_collection.json): 所有端点、示例请求体和脚本。
- [Staging 环境](https://docs.maple.inc/developer-api/postman/maple-developer-api.staging.postman_environment.json): 指向 api.staging.maple.inc；请使用您的 mpk\_test\_… 密钥。
- [Production 环境](https://docs.maple.inc/developer-api/postman/maple-developer-api.production.postman_environment.json): 指向 api.maple.inc；请使用您的 mpk\_live\_… 密钥。

## 开始设置

1. ### 导入集合和环境

   在 Postman 中 **Import** 集合文件，然后导入 **Staging**（或 **Production**）环境文件。在右上角的环境选择器中选择该环境。

2. ### 添加您的 API 密钥

   打开环境，把您的密钥粘贴到 `apiKey` 中——staging 使用 `mpk_test_…`,production 使用 `mpk_live_…`。使用 API 密钥认证时，这是您唯一需要设置的值。

   > [!NOTE]
   >
   > 请求会发送 `Authorization: Bearer {{bearerToken}}`。当 `bearerToken` 为空时，它会自动回退为您的 `apiKey`，因此只需设置 `apiKey` 即可。

3. ### 确认凭据

   运行 **Status & Auth → Current app (/me)**。如果返回 `200`，并包含您的应用名称、环境和权限范围，就说明已准备就绪。

4. ### 运行一个流程

   运行 **Locations & Connections → List locations**，然后运行其下的 **Get location** / **Create connection**——列表请求会把第一个 `locationId` 保存到环境中，因此其后的请求可以直接使用。同样的串联机制还会捕获 `orderId`、`subscriptionId` 和 `eventId`。

## 脚本的作用

- **认证回退** — 集合级的预请求脚本会把您的 `apiKey` 用作 bearer 令牌，除非显式设置了 `bearerToken`。
- **ID 串联** — 请求会把后续请求所需的 ID（`locationId`、`orderId`、`subscriptionId`、`eventId`、`zoneId`、`holdId`、`bookingId`、`waitlistEntryId` 等）保存到环境中。
- **Webhook 密钥捕获** — *Create webhook subscription* 会把一次性的 `signing_secret` 存入 `signingSecret`（请妥善保存；它只显示一次）。
- **OAuth（可选）** — **OAuth** 文件夹会用客户端凭据换取访问令牌，并自动把 `bearerToken` 切换为该令牌。它还包含 PKCE 生成器和授权码交换。OAuth 目前尚不属于正式发布的 API（参见[身份验证](https://docs.maple.inc/zh/developer-api/concepts/authentication.md#oauth)），因此除非 Maple 已为您的应用启用 OAuth，请使用您的 API 密钥。清空 `bearerToken` 即可切回您的 API 密钥。

> [!TIP]
>
> 金额字段是以最小货币单位表示的整数（分）。发布菜单的请求包含一份完整的示例文档，您可以据此修改。字段的详细说明请参阅[API 参考](https://docs.maple.inc/zh/developer-api/api-reference.md)和[菜单模型](https://docs.maple.inc/zh/developer-api/concepts/the-menu-model.md)。