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

# Maple 如何运作

> 每个集成背后的对象与关系：应用、门店、连接，以及您与 Maple 之间的职责划分。

在编写代码之前，先在脑中建立完整的模型会很有帮助。对象只有寥寥几个，并且按单一方向相互衔接。

## 对象

<ParamField path="Developer app" type="您的身份">
  您已获批准的集成，由 Maple 明确分配给某个开发者组织。受邀的组织成员通过开发者控制台创建密钥。凭证、授权和订阅都以环境为范围；沙盒和生产是相互独立的部署。应用审批和权限范围上限仍由 Maple 管理。
</ParamField>

<ParamField path="Location" type="一家餐厅">
  一家餐厅，也是 Developer API 操作的基本单位（ID 为 `str_…`）。商户会向您的应用**授权**某个门店；该授权让您可以读取它。门店有 `status`（`active`、`inactive`、`paused`），您应予以遵守。门店隶属于商户和组织，见[组织、商户与门店](/zh/developer-api/concepts/entities)。
</ParamField>

<ParamField path="Connection" type="您是订单接收方">
  连接到已授权的门店，会让您的应用成为该门店的**订单接收方**。只有建立连接之后，订单才会路由给您。每个环境下，一个门店只能连接到一个应用。
</ParamField>

<ParamField path="Order" type="顾客下的订单">
  顾客在已连接门店下的订单，包含商品明细、合计（由 Maple 计算）和支付对象。您通过决定调用来推动它走完生命周期。
</ParamField>

<ParamField path="Menu" type="顾客据以点餐的内容">
  门店的商品目录，包括分类、菜品、规格、加料选项，以及税费定义，以一份以您自己的外部 ID 为键的 JSON 文档发布。
</ParamField>

<ParamField path="Webhook subscription" type="您如何得知事件">
  一个 HTTPS 端点加上您需要的事件类型。Maple 会对事件签名并投递给它，并保留一份您可以从中重放的事件记录。
</ParamField>

## 它们如何连接

```mermaid theme={null}
flowchart LR
  App[Your developer app] -- granted --> Loc[Location]
  App -- connection --> Loc
  Loc -- emits --> Order[Order]
  App -- publishes --> Menu[Menu]
  Order -- order.notification --> Hook[Your webhook endpoint]
  Hook -- accept / deny / ready / complete --> Order
```

商户向您授权一个门店 → 您连接到它 → 该门店的订单被推送到您的 webhook → 您对每笔订单作出决定。与此同时，您发布这些订单所依据的菜单。

## 谁负责什么

这是最需要理解的一点，也是大多数餐厅集成最容易出错的地方。Maple 负责带有风险的部分：

| Maple 负责 | 您负责 |
| - | - |
| 顾客支付生命周期（由 Stripe 支持的支付链接） | 接收订单并作出决定 |
| 所有面向顾客的合计、税费和附加费计算 | 把订单状态反馈回来（accept、ready、complete） |
| 银行卡数据和 PCI 合规范围 | 发布准确的菜单 |
| 投递、重试和签名 webhook | 验证签名并对事件去重 |

您永远不需要计算价格、接触银行卡或构建支付流程。Maple 交给您的订单，`totals` 已是最终值，`payment` 对象您可以读取但无需管理。

<Info>
  请把 Maple 的合计视为权威。您在订单阶段的工作是决定能否履行订单，而不是重新计价。
</Info>

## 订单流程全貌

1. 顾客在已连接的门店下单。
2. *（可选）* Maple 发送 `order.validation_requested`，并等待您确认订单可以履行。见[验证订单](/zh/developer-api/guides/receive-orders)。
3. Maple 发送包含完整订单的 `order.notification`。
4. 您**接受**或**拒绝**订单。
5. 您回报进度，先 **ready**，再 **complete**；如果接单后不得不取消，则 **cancel**。
6. 如果顾客或门店取消，您会收到 `order.cancelled`。

每个决定调用都可安全重放，因此重试不会有影响。完整流程见[接收并处理订单](/zh/developer-api/guides/receive-orders)。

## 环境

Maple 运行两个相互隔离的环境，各有自己的基础 URL：

* **沙盒**：`https://api.staging.maple.inc/v1`，使用您的 `mpk_test_…` 密钥。用于开发和测试。
* **生产**：`https://api.maple.inc/v1`，使用您的 `mpk_live_…` 密钥。处理真实流量。

您在沙盒中针对隔离的数据构建并验证所有内容，待集成获批后，再把同样的代码指向生产。两个环境永远看不到对方的数据。更多内容见[环境与测试模式](/zh/developer-api/concepts/environments)。

## 下一步

<CardGroup cols={2}>
  <Card title="快速入门" icon="rocket" href="/zh/developer-api/quickstart">
    亲自发出第一批调用。
  </Card>

  <Card title="身份验证" icon="key" href="/zh/developer-api/concepts/authentication">
    API 密钥、环境和权限范围的详细说明。
  </Card>
</CardGroup>


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