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

> 将您的 POS 或平台连接到 Maple：接收并处理订单、发布菜单，并订阅已签名的 webhook。

Maple Developer API 可将您的 POS 或平台连接到已获批准的 Maple 门店。您可以在为集成批准的权限范围和门店功能内，接收并处理订单、发布菜单或管理预订。

无需安装 SDK。对于订单集成，Maple 负责处理顾客支付，并提供已计算好总额的订单。请使用开发者控制台管理您的密钥、webhook 和诊断。

- [快速入门](https://docs.maple.inc/zh/developer-api/quickstart.md): 登录、创建您自己的密钥，并找到您的第一个 API 请求和已签名的测试投递。
- [Maple 如何运作](https://docs.maple.inc/zh/developer-api/how-maple-works.md): 概念模型：应用、门店、连接，以及各自的职责归属。

## 从您要做的事情开始

- [接收并处理订单](https://docs.maple.inc/zh/developer-api/guides/receive-orders.md): 接收 order.notification webhook，并通过 accept、deny、ready 和 complete 调用推进每个订单。
- [发布菜单](https://docs.maple.inc/zh/developer-api/guides/publish-menu.md): 以您自己的稳定 ID 为键，把门店的完整菜单作为一份 JSON 文档发送，并可读回。
- [处理 webhook](https://docs.maple.inc/zh/developer-api/concepts/webhooks.md): 验证 HMAC 签名、对投递去重，并从事件记录中重放。
- [浏览所有端点](https://docs.maple.inc/zh/developer-api/api-reference.md): 门店、连接、菜单、配送区域、订单、webhook、预订、候位和反馈的请求与响应结构。

## 您无需自行构建的部分

餐厅集成通常很痛苦，因为您要承担本不属于您的问题。使用 Maple，您不需要：

- **无需对接支付。** Maple 创建并负责支付链接。您无需接触银行卡，也不承担 PCI 范围。
- **无需定价引擎。** Maple 计算每一个面向顾客的总额。您读取的是以分为单位的整数。
- **无需轮询。** 订单会推送到您的 webhook；事件记录和重放端点可用于恢复。
- **无需 SDK。** 这是一个 REST API，可用任何语言调用。
- **无需在生产环境中摸索。** 您先基于隔离的测试数据构建；集成获批后才会开通正式访问。

## API 的整体形态

每个经过身份验证的请求都携带 `Bearer` 凭据。请在已准备好的沙盒中开发，然后单独申请生产批准，并配置生产应用、授权、密钥和端点。请参阅[环境](https://docs.maple.inc/zh/developer-api/concepts/environments.md)：

```bash
# Sandbox — build and test here
curl https://api.staging.maple.inc/v1/me \
  -H "Authorization: Bearer mpk_test_..."
```

- **两个环境：** 用于开发的沙盒 `https://api.staging.maple.inc/v1`，以及生产环境 `https://api.maple.inc/v1`。两者完全隔离。请参阅[环境](https://docs.maple.inc/zh/developer-api/concepts/environments.md)。
- **API 密钥认证：** 将您的密钥（`mpk_test_…` / `mpk_live_…`）作为 Bearer 令牌发送。请参阅[身份验证](https://docs.maple.inc/zh/developer-api/concepts/authentication.md)。
- **按权限范围访问：** 您的应用只拥有其所需的权限（`orders:read`、`menus:write`、`webhooks:write` 等）。
- **可预测的资源：** 不透明的 ID、以美分为单位的整数金额（USD）、Stripe 风格的事件信封，以及一致的错误响应体。

> [!NOTE]
>
> 访问以受邀合作伙伴优先。Maple 会批准您的应用，并准备其沙盒和门店授权；之后您组织的成员登录 **Developers**，即可创建密钥、管理 webhook，并查看请求/投递诊断。请[联系我们](https://maple.inc/get-started)获取邀请，然后按照[快速入门](https://docs.maple.inc/zh/developer-api/quickstart.md)操作。创建密钥并不会授予门店访问权限，也不会开通生产环境。