状态
订单资源的status 始终是以下九个值之一:
FULFILLED、REJECTED、STORE_CANCELLED 和 CUSTOMER_CANCELLED 是终态:处于这些状态的订单不会再变化。
您通过决定端点来设置状态。
PENDING、AUTO_ACCEPTED 和 CUSTOMER_CANCELLED 是系统状态,您只会看到,不会自己设置。流转过程
顺利的路径是PENDING → ACCEPTED → READY → FULFILLED;外送订单在 READY 和 FULFILLED 之间还有 IN_DELIVERY。处于 PENDING 时,您要么接单,要么拒绝。接单之后,在订单完成之前您仍然可以取消(STORE_CANCELLED)。顾客取消(CUSTOMER_CANCELLED)可以打断任何非终态,并以 order.cancelled webhook 的形式送达。
状态转换会被校验:从当前状态看不合法的决定会被拒绝。由于每个决定都是可安全重放的,重复调用不会有影响。
您的决定如何对应状态
Webhook 何时触发
下图展示一笔订单整个生命周期中各 webhook 的位置。虚线箭头是 Maple 发给您的 webhook;实线箭头是您回调的请求。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,取值为:
外送订单还带有
delivery_address,包括街道、单元、城市、州、邮编,以及顾客在 notes 中的配送说明。自取订单和没有已存地址的外送订单,该值为 null。见接收订单。
支付是只读的
Maple 全程负责顾客的支付生命周期。支付绝不是您要创建或修改的东西,没有支付端点。您只能把它当作订单上的字段读取:payment_status 和 payment.status 是同一个值,取值为:
payment_link_url 是顾客用于付款、由 Maple 托管的链接。到店付款的订单,以及尚未创建链接之前,其值为 null。请把所有这些视为权威且只读的信息,见Maple 如何运作。