Skip to main content
errand_create 传入 callback_url 后,订单状态变化时平台主动 POST JSON 到该地址。收到后返回 HTTP 200 即可(响应体不校验)。 除配送过程中的状态推进外,支付成功开始呼叫骑手(dispatching)、呼叫骑手失败(dispatch_failed,已付款项全额退回)、待支付单超 2 分钟未支付自动关闭(cancelled)同样会推送。只有你自己调用取消接口取消成功不再推送——接口响应里已经给了结果。
**回调是提醒,不是事实源。**单次投递、不重试,网络抖动就会丢;订单的真实状态一律以 errand_get_order 为准。下发时机由配送方决定,平台不承诺送达时限——请勿据此设置超时判断,需要确定状态时主动查询。
事件可能重复或不按顺序到达——配送方推送失败会重试。请按 order_id 做幂等处理,并用 time 判断先后:收到比已处理事件更早的 time 时应忽略。 三类事件的字段各不相同,请按 event 分支处理,不要假设某个字段一定存在。
回调需要先在配送方侧完成推送地址配置才会下发——接入前请与平台确认是否已为你的账号开通,不要把回调当作订单状态的唯一来源。其中 rider_changed(骑手变更)默认关闭,需单独开通。

公共字段(三类事件都有)

status_changed —— 状态推进

订单状态发生变化时下发,是最常用的一类。

exception —— 配送异常报备

配送过程中出现意外情况时下发。这类事件只是知会,订单状态不变(不会因为一次异常报备就变成失败),后续可能恢复正常配送。建议展示给用户并询问如何处理。

rider_changed —— 骑手变更

换了骑手时下发,通常直接带上新骑手;个别情况下不带 rider 字段。需要实时位置、或本次没带骑手时,调 errand_get_rider。

异常原因取值(error_reason)