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

# 快速入门

> 登录开发者控制台，创建您自己的密钥，并验证 API 请求和已签名的 webhook。

使用开发者控制台管理 Maple 已批准应用的凭据和 webhook。请先在沙盒环境中完成一个受支持的业务流程，再申请生产环境访问权限。

## 开始之前

您需要：一份加入开发者组织的邀请、一个分配给该组织的已批准应用，以及对应环境的控制台：沙盒使用 `https://app.staging.maple.inc`，生产环境使用 `https://app.maple.inc`（参阅[环境](/zh/developer-api/concepts/environments)）。Maple 会为您准备沙盒，并授予您的集成所需的门店。**创建密钥不会创建沙盒，也不会授予门店访问权限。**

如果您没有邀请或已批准的应用，请[联系 Maple](https://maple.inc/get-started)。公开注册、应用审批、门店授权和生产环境激活都不支持自助完成。

## 从编码助手开始

如果由编码助手（Claude Code、Cursor、Codex 或类似工具）为您构建集成，请在 `MAPLE_KEY` 中放入沙盒密钥后，把下面的提示词复制给它。它会让助手阅读这些文档和 API 参考，将其限制在沙盒中，并告诉它如何报告 API 中妨碍工作的任何问题。

<Prompt description="Set up a coding agent to build against the Maple Developer API in the sandbox." icon="robot" actions={["copy", "cursor"]}>
  You are building an integration with the Maple Developer API in this repository.

  Read these first:

  * The docs index: [https://docs.maple.inc/llms.txt](https://docs.maple.inc/llms.txt) (every page is available as Markdown at the page URL plus `.md`)
  * The quickstart: [https://docs.maple.inc/developer-api/quickstart.md](https://docs.maple.inc/developer-api/quickstart.md)
  * The OpenAPI spec, which is the source of truth for every endpoint and field: [https://docs.maple.inc/openapi/developer-api.json](https://docs.maple.inc/openapi/developer-api.json)

  Rules:

  * Use the sandbox only. The base URL is `https://api.staging.maple.inc/v1`, and the key is in the `MAPLE_KEY` environment variable (it starts with `mpk_test_`). Never print, log, or commit the key, and ask me before doing anything against production.
  * Send the key as `Authorization: Bearer $MAPLE_KEY`. Start by calling `GET /me` to confirm the app, the environment, and the scopes the key has, and plan around those scopes.
  * Keep the `x-request-id` header from every response. It identifies the request in the developer console and in feedback.
  * Branch on an error's `_tag` and `code`, never its `message`. Follow `Retry-After` on a 429.
  * Verify the HMAC signature on every webhook before acting on it.

  When the API gets in your way (a bug, a capability you need that is missing, docs that disagree with what the API does, or an error that does not tell you what to change), report it with `POST /v1/feedback`, citing the `x-request-id` values involved, then carry on with the best workaround you have. See [https://docs.maple.inc/developer-api/concepts/feedback.md](https://docs.maple.inc/developer-api/concepts/feedback.md) for the fields.

  Start by reading the docs above, calling `GET /me`, and telling me what the key can do and which guide fits what we are building.
</Prompt>

<Steps>
  <Step title="登录并选择您的应用">
    按邀请指引，使用受邀邮箱登录，然后打开 **Developers**。选择正确的组织和已批准的应用。您无需创建或选择餐厅。

    继续之前，请确认 **Sandbox** 或 **Production** 标识以及 API 基础 URL。每个控制台只管理各自的部署环境。切换环境时，请使用对应的邀请或控制台 URL；不要假设会话或数据是共享的。

    如果没有显示任何应用，请联系 Maple 批准该应用，或将其关联到所选组织。仅有员工访问权限并不会让应用出现在开发者控制台中。
  </Step>

  <Step title="创建并保存密钥">
    在 **Overview & keys** 中选择 **Create key**，为其命名，并只选择您的客户端所需且已获批准的权限范围（scope）。请妥善保存完整密钥：它只显示一次，关闭对话框后无法再次获取。

    在您自己的客户端环境中设置 `MAPLE_KEY`。示例都使用这个变量；请勿把密钥粘贴到文档、源代码管理、截图或请求历史字段中。

    设置沙盒控制台显示的公开基础 URL:

    ```bash theme={null}
    export MAPLE_BASE="https://api.staging.maple.inc/v1"
    ```

    已暂停或已吊销的应用无法使用其密钥进行身份验证。您仍可以在控制台中查看并吊销密钥。
  </Step>

  <Step title="验证您的身份">
    运行 **Getting started** 中复制的 **/me** 命令，或使用：

    ```bash theme={null}
    curl --include "$MAPLE_BASE/me" \
      -H "Authorization: Bearer $MAPLE_KEY"
    ```

    ```json Response theme={null}
    {
      "object": "developer_app",
      "id": "dap_...",
      "name": "Your Integration",
      "environment": "test",
      "scopes": ["locations:read", "webhooks:read", "webhooks:write"]
    }
    ```

    确认应用、环境和实际生效的权限范围。保留 **`x-request-id`** 响应头，以便在 **Requests** 中找到这次调用。密钥的权限永远不会超过应用当前获批的权限上限。
  </Step>

  <Step title="查看您的门店">
    **Granted locations** 显示为此应用配置的授权。要通过 API 读取门店，请使用带有 `locations:read` 的密钥：

    ```bash theme={null}
    curl --include "$MAPLE_BASE/locations" \
      -H "Authorization: Bearer $MAPLE_KEY"
    ```

    列表为空并不意味着需要在门户中创建餐厅。请联系 Maple，由其提供测试门店和您的集成所需的授权。

    授权与订单接收方连接是两回事。对于订单/POS 集成，请按照[接收并处理订单](/zh/developer-api/guides/receive-orders)连接已授权的门店。对于预订，请阅读[预订资料与预订指南](/zh/developer-api/guides/take-bookings)；不要仅为了测试预订而创建订单接收方连接。
  </Step>

  <Step title="注册并测试 webhook">
    打开 **Webhooks → Endpoints**，选择 **Add endpoint**，输入您可控的公开 HTTPS URL，并选择受支持的事件类型。您的应用需要 `webhooks:read` 才能查看此区域，需要 `webhooks:write` 才能更改端点或发送测试。

    保存一次性签名密钥，并在您的接收端实现[签名验证](/zh/developer-api/concepts/webhooks)。创建端点不会自动发送测试。

    选择 **Send test**。“已送达”表示接收端返回了 `2xx`；这并不能证明您的处理程序已验证签名。失败或被跳过的测试不算成功。一次测试只有一次尝试，该操作不会安排自动重试。
  </Step>

  <Step title="查找请求和投递记录">
    在 **Requests** 中搜索您 API 调用的 `x-request-id`。您无需访问内部日志，即可查看其状态和安全的错误摘要。历史记录涵盖使用您应用的密钥或令牌发出的请求（包括已吊销的），保留 7 天；没有可识别凭据的请求不会被记录。历史记录服务不可用不等同于历史记录为空且成功。

    在 **Webhooks → Deliveries** 中，查看已签名测试的结果、尝试次数、HTTP 状态和时间戳。历史记录是按事件/端点汇总的，不是逐次尝试的时间线。URL 和启用状态反映的是端点当前的配置，而不是过去某次请求的目的地。

    对于可重放的业务事件，**Review event** 会预览事件级重试。确认后会重试符合条件的目的地；已成功的组合和已停用的目的地会被跳过。仅测试的记录提供 **Send another test**，而不是重放不存在的事件记录条目。关于限制和结果不确定的情况，请参阅[Webhooks](/zh/developer-api/concepts/webhooks)。

    Getting started 中的 **Check recent activity** 会按需读取最近的 `/me` 调用和已送达测试的元数据。它只是设置提示，不能证明您当前的密钥、当前的端点配置或完整的集成已通过验证。
  </Step>

  <Step title="完成您的业务流程并验证吊销">
    按照您已获批准的集成对应的指南，在隔离的测试门店上执行一次真实操作，例如：查询可用时段 → 保留 → 创建 → 修改/取消预订。接收由此产生的业务事件，并找到其诊断信息。仅有 `/me` 和合成测试不能验证业务集成。

    当临时验收密钥不再需要时，在控制台中选择 **Revoke** 并确认。使用该密钥再次发送 `/me` 请求，并确认身份验证失败。请勿吊销仍被其他客户端使用的密钥。
  </Step>
</Steps>

## 遇到问题时

| 您看到的情况 | 需要检查的内容 |
| - | - |
| 没有已批准的应用 | 受邀邮箱、所选组织，以及 Maple 对应用的归属/审批情况 |
| 没有授权或门店列表为空 | 按环境划分的门店授权，以及密钥上的 `locations:read` |
| 没有最近的请求 | 您的响应/请求 ID、筛选条件、7 天保留期，以及您是否使用了此应用和此环境的密钥进行调用 |
| 历史记录不可用 | 稍后重试读取历史记录；密钥和 webhook 管理是独立的 |
| 端点已停用 | 重新启用之前，先查看其配置和失败历史 |
| 应用已暂停 | 联系 Maple；创建另一个密钥无法绕过应用状态 |
| 环境错误 | 确保控制台、API 基础 URL 和凭据一致；沙盒不会激活生产环境 |

## 继续您的集成

<Columns cols={2}>
  <Card title="接受预订" icon="calendar" href="/zh/developer-api/guides/take-bookings">
    读取预订资料、搜索可用时段、保留时段，并创建或修改预订。
  </Card>

  <Card title="接收并处理订单" icon="receipt" href="/zh/developer-api/guides/receive-orders">
    连接已授权的门店，处理订单通知和订单决定。
  </Card>

  <Card title="发布菜单" icon="book-open" href="/zh/developer-api/guides/publish-menu">
    为已获批准的订单/POS 集成发布商品目录。
  </Card>

  <Card title="生产环境访问" icon="key" href="/zh/developer-api/concepts/environments">
    了解正式上线所需的独立审批、凭据、授权和端点设置。
  </Card>
</Columns>


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