> ## 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 指代什么以及您拥有哪些访问权限产生错误的假设。

```mermaid theme={null}
flowchart TD
  Org[Organization] --> M1[Merchant]
  Org --> M2[Merchant]
  M1 --> L1[Location]
  M1 --> L2[Location]
  M2 --> L3[Location]
```

## 三个层级

<ParamField path="Organization" type="顶层账户">
  合作伙伴账户。一个组织包含一个或多个商户，其团队成员可以管理所有这些商户。
</ParamField>

<ParamField path="Merchant" type="业务 / 品牌">
  组织下的一个餐厅业务或品牌。一个商户包含一个或多个门店。其法人实体持有支付和账单设置。
</ParamField>

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

## 基数关系及其重要性

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

## Developer API 公开的内容

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

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

## 门店状态

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

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

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

## 连接生命周期

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

<Steps>
  <Step title="已开通（Provisioned）">
    商户把某个门店的访问权限授予您的应用。您会收到 **`store.provisioned`**，该门店出现在 `GET /v1/locations` 中。您可以读取它，但订单暂时不会路由给您。
  </Step>

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

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

  <Step title="已撤销开通（Deprovisioned）">
    商户撤销授权。您会收到 **`store.deprovisioned`**，并完全失去对该门店的访问权限。
  </Step>
</Steps>

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

## 您会看到的标识符

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

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

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


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