> ## 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 的每个端点——状态与认证、OAuth 流程、门店与连接、菜单读取/发布、完整的订单流程以及 webhook。它附带辅助脚本，让您无需在请求之间复制粘贴 ID，就能端到端地运行一个流程。

## 下载

<CardGroup cols={3}>
  <Card title="集合" icon="download" href="/developer-api/postman/maple-developer-api.postman_collection.json">
    所有端点、示例请求体和脚本。
  </Card>

  <Card title="Staging 环境" icon="flask" href="/developer-api/postman/maple-developer-api.staging.postman_environment.json">
    指向 `api.staging.maple.inc`；请使用您的 `mpk_test_…` 密钥。
  </Card>

  <Card title="Production 环境" icon="rocket" href="/developer-api/postman/maple-developer-api.production.postman_environment.json">
    指向 `api.maple.inc`；请使用您的 `mpk_live_…` 密钥。
  </Card>
</CardGroup>

## 开始设置

<Steps>
  <Step title="导入集合和环境">
    在 Postman 中 **Import** 集合文件，然后导入 **Staging**（或 **Production**）环境文件。在右上角的环境选择器中选择该环境。
  </Step>

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

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

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

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

## 脚本的作用

* **认证回退** — 集合级的预请求脚本会把您的 `apiKey` 用作 bearer 令牌，除非显式设置了 `bearerToken`。
* **ID 串联** — 列表请求会把返回的第一个 ID（`locationId`、`orderId`、`subscriptionId`、`eventId`）保存到环境中，供需要它的请求使用。
* **Webhook 密钥捕获** — *Create webhook subscription* 会把一次性的 `signing_secret` 存入 `signingSecret`（请妥善保存；它只显示一次）。
* **OAuth（可选）** — **OAuth** 文件夹会用客户端凭据换取访问令牌，并自动把 `bearerToken` 切换为该令牌。它还包含 PKCE 生成器和授权码交换。清空 `bearerToken` 即可切回您的 API 密钥。

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


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