> ## 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 如何组织您所集成的业务，以及为什么 Developer API 在门店层级工作。

Maple 把每个业务组织为三层结构。您主要会使用最底层，也就是门店，但了解整体结构可以避免对某个 ID 指代什么以及您拥有哪些访问权限产生错误的假设。

```
flowchart TD
  Org[Organization] --> M1[Merchant]
  Org --> M2[Merchant]
  M1 --> L1[Location]
  M1 --> L2[Location]
  M2 --> L3[Location]
```

## 三个层级

### `Organization`

顶层账户

合作伙伴账户。一个组织包含一个或多个商户，其团队成员可以管理所有这些商户。

### `Merchant`

业务 / 品牌

组织下的一个餐厅业务或品牌。一个商户包含一个或多个门店。其法人实体持有支付和账单设置。

### `Location`

单个餐厅

一家实体餐厅，是 Developer API 操作的单位，也是 Maple 定价和计费的单位。一个门店恰好属于一个商户。其 ID 形如 `str_…`，API 将其作为 `location` 资源公开。

## 基数关系及其重要性

- 一个组织有**多个**商户；一个商户有**多个**门店。
- 一个门店恰好属于**一个**商户，一个商户至多属于**一个**组织。这些关系不会变动，门店无法改挂到另一个商户名下。
- **运营数据存放在门店层级。** 订单、菜单、连接和 webhook 都按门店划分，而不是商户或组织。就您的集成而言，同一商户下的两个门店是相互独立的。

## Developer API 公开的内容

Developer API 呈现的是**门店**。`location` 资源携带门店的 ID（`str_…`）、名称、状态、时区、电话和地址，不包含其上级商户或组织。当您列出门店、建立连接、接收订单或发布菜单时，始终是通过 `str_…` ID 对单个门店进行操作。

> [!NOTE]
>
> **访问权限按门店授予。** 商户会逐个把特定门店的访问权限授予您的应用。持有某一个门店的授权，并不会让您访问同一商户下的其他门店，每个门店都需要单独授权（并单独连接）。有关授权与连接，请参阅[Maple 如何运作](https://docs.maple.inc/zh/developer-api/how-maple-works.md)。

## 门店状态

门店的 `status` 告诉您它是否开放接单：

| 状态         | 含义              |
| ---------- | --------------- |
| `active`   | 已上线并接收订单        |
| `paused`   | 暂时不接收订单         |
| `inactive` | 尚未上线（设置未完成）或已停用 |

请遵循该状态，不要期望从非 `active` 的门店收到订单，也不要向其分派工作。

## 连接生命周期

您对某个门店的访问会经历四个时刻，并由三个 webhook 事件标记：

1. ### 已开通（Provisioned）

   商户把某个门店的访问权限授予您的应用。您会收到 **`store.provisioned`**，该门店出现在 `GET /v1/locations` 中。您可以读取它，但订单暂时不会路由给您。

2. ### 已连接（Connected）

   您调用 `POST /v1/locations/{id}/connection`，成为该门店的订单接收方。连接的 `status` 变为 `active`，并触发 **`store.status.changed`**，其中 `status: "connected"`。订单现在会路由给您。

3. ### 已断开（Disconnected）

   您（或 Maple）通过 `DELETE` 移除连接。触发 **`store.status.changed`**，其中 `status: "disconnected"`，订单不再路由给您。授权仍然保留，因此您之后可以重新连接。

4. ### 已撤销开通（Deprovisioned）

   商户撤销授权。您会收到 **`store.deprovisioned`**，并完全失去对该门店的访问权限。

每个环境中，一个门店至多有一个已连接的应用，因此对已被其他应用占用的门店发起 `POST` 会返回 `409`。要订阅这些事件，请参阅[Webhooks](https://docs.maple.inc/zh/developer-api/concepts/webhooks.md)。

## 您会看到的标识符

| 资源         | ID 前缀   | 在 Developer API 中？                  |
| ---------- | ------- | ----------------------------------- |
| 门店         | `str_…` | 是，即 `location` 资源和每一个 `location_id` |
| 订单         | `ord_…` | 是                                   |
| Webhook 订阅 | `dws_…` | 是                                   |
| 事件         | `evt_…` | 是                                   |

商户和组织的 ID 在内部存在，但不属于 Developer API 的范围，您通过门店来寻址一切。

有关合作伙伴如何在控制台中管理组织、商户和门店，请参阅[Maple 的组织结构](https://docs.maple.inc/zh/partners/overview.md)。