> ## 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 创建订单，并处理支付和面向顾客的状态转换；您通过接单和回报进度来推动履行。本页是所有状态、状态之间的转换，以及订单资源上相关字段的参考。要构建处理流程，请参阅[接收并处理订单](/zh/developer-api/guides/receive-orders)。

## 状态

订单资源的 `status` 始终是以下九个值之一：

| 状态 | 含义 | 由谁设置 |
| - | - | - |
| `PENDING` | 已创建，等待决定 | Maple（初始状态） |
| `ACCEPTED` | 您已接单 | 您的 `accept` / `status: ACCEPTED` |
| `AUTO_ACCEPTED` | 提交时自动接单 | Maple，按 `ACCEPTED` 对待即可 |
| `READY` | 已备好，可取餐或交给骑手 | 您的 `ready` / `status: READY` |
| `IN_DELIVERY` | 配送中 | 您的 `status: IN_DELIVERY` |
| `FULFILLED` | 已完成 | 您的 `complete` / `status: FULFILLED` |
| `REJECTED` | 已拒绝，或无法提交给您 | 您的 `deny` / `status: REJECTED` |
| `STORE_CANCELLED` | 接单后由门店取消 | 您的 `cancel` / `status: STORE_CANCELLED` |
| `CUSTOMER_CANCELLED` | 顾客取消 | Maple |

`FULFILLED`、`REJECTED`、`STORE_CANCELLED` 和 `CUSTOMER_CANCELLED` 是**终态**：处于这些状态的订单不会再变化。

<Note>
  您通过[决定端点](/zh/developer-api/guides/receive-orders)来设置状态。
  `PENDING`、`AUTO_ACCEPTED` 和 `CUSTOMER_CANCELLED` 是系统状态，您只会看到，不会自己设置。
</Note>

## 流转过程

```mermaid theme={null}
stateDiagram-v2
  [*] --> PENDING
  PENDING --> ACCEPTED: accept
  PENDING --> REJECTED: deny
  ACCEPTED --> READY: ready
  READY --> IN_DELIVERY: status (delivery)
  READY --> FULFILLED: complete
  IN_DELIVERY --> FULFILLED: complete
  ACCEPTED --> STORE_CANCELLED: cancel
  READY --> STORE_CANCELLED: cancel
  FULFILLED --> [*]
  REJECTED --> [*]
  STORE_CANCELLED --> [*]
```

顺利的路径是 `PENDING → ACCEPTED → READY → FULFILLED`；外送订单在 `READY` 和 `FULFILLED` 之间还有 `IN_DELIVERY`。处于 `PENDING` 时，您要么接单，要么拒绝。接单之后，在订单完成之前您仍然可以取消（`STORE_CANCELLED`）。顾客取消（`CUSTOMER_CANCELLED`）可以打断任何非终态，并以 `order.cancelled` webhook 的形式送达。

状态转换会被校验：从当前状态看不合法的决定会被拒绝。由于每个决定都是[可安全重放的](/zh/developer-api/concepts/idempotency)，重复调用不会有影响。

## 您的决定如何对应状态

| 调用 | 得到的状态 |
| - | - |
| `POST /orders/{id}/accept` | `ACCEPTED` |
| `POST /orders/{id}/deny` | `REJECTED` |
| `POST /orders/{id}/ready` | `READY` |
| `POST /orders/{id}/complete` | `FULFILLED` |
| `POST /orders/{id}/cancel` | `STORE_CANCELLED` |
| `POST /orders/{id}/status` | 您发送的值（`ACCEPTED`、`READY`、`IN_DELIVERY`、`FULFILLED`、`REJECTED`、`STORE_CANCELLED`） |

## Webhook 何时触发

下图展示一笔订单整个生命周期中各 webhook 的位置。虚线箭头是 Maple 发给您的 webhook；实线箭头是您回调的请求。

```mermaid theme={null}
sequenceDiagram
  participant C as Customer
  participant M as Maple
  participant You as Your app
  C->>M: Places an order
  M-->>You: order.created
  opt You subscribed to validation
    M-->>You: order.validation_requested
    You->>M: validation_result (valid / invalid)
  end
  M-->>You: order.notification
  You->>M: accept
  M-->>You: order.paid
  You->>M: ready, then complete
  opt Customer or store cancels
    M-->>You: order.cancelled
  end
```

1. **`order.created`**：订单已存在。无论您是否使用验证，都会触发。
2. **`order.validation_requested`** *（仅当您已订阅）*：Maple 请您确认订单可以履行，并等待您的 `validation_result`。`invalid` 结果会在此处拒绝订单，因此它不会进入通知阶段。
3. **`order.notification`**：订单交给您履行。您 `accept`（或 `deny`），然后回报 `ready` 和 `complete`。
4. **`order.paid`**：支付已结算。它的位置不固定：通过链接支付的订单可能在通知之前就已支付，而到店付款的订单则在之后支付，因此不要假定它出现在固定的时间点。
5. **`order.cancelled`**：顾客或门店已取消。它几乎可以在订单创建后的任何时间到达，包括您已开始履行之后。收到后请停止处理。

您自己发起的状态转换（`accept`、`ready`、`complete`）不会以 webhook 的形式回传给您，也并非每次状态变化都有对应事件，详见下文。

## Webhook 不会跟踪每一次状态转换

并不是每次状态变化都有 webhook。Maple 发出的订单事件是固定的一组：`order.notification`、`order.created`、`order.paid`、`order.cancelled`，以及（如果您订阅了）`order.validation_requested`。由**您**推动的转换（`accept`、`ready`、`complete`）不会回传给您，进入 `IN_DELIVERY`，或支付变为 `refunded`、`voided`、`failed`，也都没有对应事件。

因此，**当前状态以订单资源为准，而不是事件流。** 需要了解某笔订单的现状时，请读取 `GET /v1/orders/{orderId}`。Webhook 告诉您发生了某件事；资源告诉您当前状态。见[Webhooks](/zh/developer-api/concepts/webhooks)。

## 履行类型

每笔订单都带有 `fulfillment_type`，取值为：

| 值 | 含义 |
| - | - |
| `pickup` | 顾客自取 |
| `delivery` | 订单由配送送达；`IN_DELIVERY` 适用于这种情况 |

外送订单还带有 `delivery_address`，包括街道、单元、城市、州、邮编，以及顾客在 `notes` 中的配送说明。自取订单和没有已存地址的外送订单，该值为 `null`。见[接收订单](/zh/developer-api/guides/receive-orders)。

## 支付是只读的

Maple 全程负责顾客的支付生命周期。支付**绝不是您要创建或修改的东西**，没有支付端点。您只能把它当作订单上的字段读取：

```json theme={null}
"payment_status": "paid",
"payment": { "provider": "stripe", "status": "paid", "payment_link_url": "https://..." }
```

`payment_status` 和 `payment.status` 是同一个值，取值为：

| 支付状态 | 含义 |
| - | - |
| `pending` | 等待支付 |
| `paid` | 已支付 |
| `failed` | 支付尝试失败 |
| `voided` | 预授权已撤销 |
| `refunded` | 已全额退款 |
| `partially_refunded` | 已部分退款 |

`payment_link_url` 是顾客用于付款、由 Maple 托管的链接。到店付款的订单，以及尚未创建链接之前，其值为 `null`。请把所有这些视为权威且只读的信息，见[Maple 如何运作](/zh/developer-api/how-maple-works)。


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