订单

订单生命周期

订单经历的每一种状态、您的决定如何推动状态变化，以及订单携带的履行和支付字段。

订单会经历一组明确定义的状态。Maple 创建订单，并处理支付和面向顾客的状态转换；您通过接单和回报进度来推动履行。本页是所有状态、状态之间的转换，以及订单资源上相关字段的参考。要构建处理流程，请参阅接收并处理订单。

状态

订单资源的 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 是终态：处于这些状态的订单不会再变化。

流转过程

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 的形式送达。

状态转换会被校验：从当前状态看不合法的决定会被拒绝。由于每个决定都是可安全重放的，重复调用不会有影响。

您的决定如何对应状态

调用	得到的状态
`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；实线箭头是您回调的请求。

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

order.created：订单已存在。无论您是否使用验证，都会触发。
order.validation_requested （仅当您已订阅）：Maple 请您确认订单可以履行，并等待您的 validation_result。invalid 结果会在此处拒绝订单，因此它不会进入通知阶段。
order.notification：订单交给您履行。您 accept（或 deny），然后回报 ready 和 complete。
order.paid：支付已结算。它的位置不固定：通过链接支付的订单可能在通知之前就已支付，而到店付款的订单则在之后支付，因此不要假定它出现在固定的时间点。
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。

履行类型

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

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

外送订单还带有 delivery_address，包括街道、单元、城市、州、邮编，以及顾客在 notes 中的配送说明。自取订单和没有已存地址的外送订单，该值为 null。见接收订单。

支付是只读的

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

"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 如何运作。