组织、商户和门店

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 对单个门店进行操作。

Info

访问权限按门店授予。 商户会逐个把特定门店的访问权限授予您的应用。持有某一个门店的授权，并不会让您访问同一商户下的其他门店，每个门店都需要单独授权（并单独连接）。有关授权与连接，请参阅Maple 如何运作。

门店状态

门店的 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。

您会看到的标识符

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

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

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