开始使用

ampe

ampe 介绍

ampe 入驻

产品管理

硬件接入

开发指南

运营能力接入

api 列表

常见问题

多端开发

鸿蒙

插件

安全

openid 开发指南

扩展能力

开发 > 指南 >  > 即时配送（take_out）

更新时间：2023-07-28 17:41:53

收藏

订阅更新

我的文档

设置

返回文档

商家需通过 alipay.merchant.order.sync（订单数据同步接口） 订单扩展字段 ext_info#merchant_order_status 参数更新订单状态，即时配送专用状态如下。
订单状态流转说明
订单状态流转图
说明：左侧表示起始状态，右侧表示允许的后置状态。

入参规则说明
●支持跨状态传递，如：create（下单成功）可直接跳转至 to_be_delivered（待配送）。
●不要求首次同步订单状态必须为 create（下单成功）。
●订单状态发生变更后，需要及时同步最新状态 。
●当前场景定义的订单状态(中文和英文名)如下
注意：不同订单状态，仅是 否发送服务消息 为 是 时，用户才能在 消息列表（支付宝凯发k8官方网娱乐官方首页服务提醒入口进入或凯发k8官方网娱乐官方首页底部消息 tab 进入）查看服务订单消息提醒。

状态中文名	状态英文名	是否发送服务消息
下单成功	create	是
待支付	wait_pay	否
待接单	pending	否
已接单	order_taken	是
待配送	to_be_delivered	否
配送中	in_delivery	是
已送达	delivered	是
已取消	closed	是

不同状态参数使用说明
下单成功 (create)
本文详细介绍通过接口 alipay.merchant.order.sync 同步订单状态-下单成功 (create)时需传入的商品信息及扩展字段参数信息。
接口参数 bizcontent 示例

参数说明

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
out_biz_no	string	是	否	是	外部订单号。由商家自定义。   注意：同一笔订单更新状态时，需与首次同步入参一致。
buyer_id	string	是	否	否	支付宝用户 uid。2088 开头的数字。
order_type	string	是	否	否	订单类型。固定为service_order（服务订单）。
order_create_time	string	是	否	是	订单创建时间，即该笔订单真实的创建时间。时间格式为 yyyy-mm-dd hh:mm:ss。
order_modified_time	string	是	是	否	订单修改时间，时间格式为 yyyy-mm-dd hh:mm:ss.sss。用于订单状态或数据变化较快的顺序控制，防止乱序。order_modified_time较晚的同步会被最终存储，order_modified_time相同的两次同步会被幂等处理。
source_app	string	否	否	否	订单来源，默认alipay(支付宝小程序)，钉钉来源dingtalk，其它来源枚举值定义联系支付宝订单中心添加。
ext_info	orderextinfo	是	是	否	订单扩展字段。详情可查看下文 订单扩展字段。
item_order_list	itemorderinfo	是	否	否	商品信息列表。详情可查看下文 商品信息列表。
trade_no	string	否	否	否	支付宝交易号。 此字段关联支付宝账单详情卡片，建议回传真实有效交易号。
amount	price	选填，建议传入 (当支付宝交易号trade_no或pay_amount为必传时须传入amount)	是	否	订单总金额。精确到小数点后两位，单位为 元。
pay_amount	price	选填，建议传入该参数	否	否	实际支付金额。精确到小数点后两位。单位为 元。
discount_amount	price	否	否	否	优惠金额。传入 discount_info_list  时必填。单位为 元。

订单扩展字段
开发者需通过订单扩展字段（ext_info）更新订单状态，订单业务信息，订单类型等数据，入参为 ext_key(对应参数的key)、ext_value(对应参数的value) 配合使用。参数说明如下：

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
l ext_key	string	是	否	否	订单状态 key。固定为 merchant_order_status。
l ext_value	string	是	是	否	订单状态，例： create。
l ext_key	string	是	否	否	订单类型 key。固定为 merchant_biz_type。
l ext_value	string	是	否	否	订单类型 value。本业务场景为：take_out。
l ext_key	string	是	否	是	订单详情地址 key。固定为merchant_order_link_page。
l ext_value	string	是	否	是	商家小程序对应的订单详情页路径地址 value。仅需传入小程序页面路径即可。
l ext_key	string	是	否	否	商家小程序 appid key。固定为 tiny_app_id。
l ext_value	string	是	否	否	商家小程序 appid value。传入订单归属的小程序 appid。
l ext_key	string	是	否	否	订单业务场景相关的信息 key。固定为 business_info。
l ext_value	jsonstring	是	是	否	订单业务信息详情 value。入参详情见下文 业务信息参数。

业务信息参数
业务信息参数（business_info） 的各项入参详情如下：

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
distribution_end_time	string	否	否	否	字段名称：预计配送结束时间。 字段说明：预计配送结束时间，时间格式为 yyyy-mm-dd hh:mm:ss。
rider_position	string	否	否	否	骑手位置
delivery_end_time	string	否	否	否	字段名称：预计送达结束时间 字段说明：预计送达结束时间,时间格式为 yyyy-mm-dd hh:mm:ss。
take_out_order_type	string	否	否	否	订单类型
distributor_information	string	否	否	否	配送商信息
store_address	string	否	否	否	字段名称：发货地址。 字段说明：发货门店的所在位置。
distribution_start_time	string	否	否	否	字段名称：预计配送开始时间 字段说明：预计配送开始时间,时间格式为 yyyy-mm-dd hh:mm:ss。
delivery_clerk	string	否	否	否	配送员电话
come_again	string	否	否	否	字段名称：再来一单 字段说明：商家或 isv 回流的再来一单链接
delivery_start_time	string	否	否	否	字段名称：预计送达开始时间 字段说明：预计送达开始时间,时间格式为 yyyy-mm-dd hh:mm:ss。
store_name	string	否	否	否	字段名称：发货门店 字段说明：外卖的发货门店
invoice	string	否	否	否	字段名称：开发票 字段说明：商家或 isv 回流的开票链接

商品信息列表
开发者需通过商品信息列表字段（item_order_list）传入商品图片、商品详情页等信息。参数说明如下：

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
item_name	string	是	否	是	商品名称。建议商品名称格式为：{商家名称} {商品名称}
ext_info	orderextinfo	是	否	否	商品扩展参数。该参数用于传入用户购买商品图片及商家商品详情页地址等信息。
l ext_key	string	是	否	否	商品图片 key。固定为 image_material_id。
l ext_value	string	是	否	否	商品图片 value。需传入 上传商品文件 获取的 material_id。

待支付 (wait_pay)
本文详细介绍通过接口 alipay.merchant.order.sync 同步订单状态-待支付 (wait_pay)时需传入的商品信息及扩展字段参数信息。
接口参数 bizcontent 示例

参数说明

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
out_biz_no	string	是	否	否	外部订单号。由商家自定义。   注意：同一笔订单更新状态时，需与首次同步入参一致。
buyer_id	string	是	否	否	支付宝用户 uid。2088 开头的数字。
order_type	string	是	否	否	订单类型。固定为service_order（服务订单）。
order_create_time	string	是	否	否	订单创建时间，即该笔订单真实的创建时间。时间格式为 yyyy-mm-dd hh:mm:ss。
order_modified_time	string	是	是	否	订单修改时间，时间格式为 yyyy-mm-dd hh:mm:ss.sss。用于订单状态或数据变化较快的顺序控制，防止乱序。order_modified_time较晚的同步会被最终存储，order_modified_time相同的两次同步会被幂等处理。
source_app	string	否	否	否	订单来源，默认alipay(支付宝小程序)，钉钉来源dingtalk，其它来源枚举值定义联系支付宝订单中心添加。
ext_info	orderextinfo	是	是	否	订单扩展字段。详情可查看下文 订单扩展字段。
item_order_list	itemorderinfo	是	否	否	商品信息列表。详情可查看下文 商品信息列表。
trade_no	string	否	否	否	支付宝交易号。 此字段关联支付宝账单详情卡片，建议回传真实有效交易号。
amount	price	选填，建议传入 (当支付宝交易号trade_no或pay_amount为必传时须传入amount)	是	否	订单总金额。精确到小数点后两位，单位为 元。
pay_amount	price	选填，建议传入该参数	否	否	实际支付金额。精确到小数点后两位。单位为 元。
discount_amount	price	否	否	否	优惠金额。传入 discount_info_list  时必填。单位为 元。

订单扩展字段
开发者需通过订单扩展字段（ext_info）更新订单状态，订单业务信息，订单类型等数据，入参为 ext_key(对应参数的key)、ext_value(对应参数的value) 配合使用。参数说明如下：

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
l ext_key	string	是	否	否	订单状态 key。固定为 merchant_order_status。
l ext_value	string	是	是	否	订单状态，例：wait_pay。
l ext_key	string	是	否	否	订单类型 key。固定为 merchant_biz_type。
l ext_value	string	是	否	否	订单类型 value。本业务场景为：take_out。
l ext_key	string	是	否	否	订单详情地址 key。固定为merchant_order_link_page。
l ext_value	string	是	否	否	商家小程序对应的订单详情页路径地址 value。仅需传入小程序页面路径即可。
l ext_key	string	是	否	否	商家小程序 appid key。固定为 tiny_app_id。
l ext_value	string	是	否	否	商家小程序 appid value。传入订单归属的小程序 appid。
l ext_key	string	是	否	否	订单业务场景相关的信息 key。固定为 business_info。
l ext_value	jsonstring	是	是	否	订单业务信息详情 value。入参详情见下文 业务信息参数。

业务信息参数
业务信息参数（business_info） 的各项入参详情如下：

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
distribution_end_time	string	否	否	否	字段名称：预计配送结束时间。 字段说明：预计配送结束时间，时间格式为 yyyy-mm-dd hh:mm:ss。
rider_position	string	否	否	否	骑手位置
delivery_end_time	string	否	否	否	字段名称：预计送达结束时间。 字段说明：预计送达结束时间，时间格式为 yyyy-mm-dd hh:mm:ss。
take_out_order_type	string	否	否	否	订单类型
distributor_information	string	否	否	否	配送商信息
store_address	string	否	否	否	字段名称：发货地址 字段说明：发货门店的所在位置。
distribution_start_time	string	否	否	否	字段名称：预计配送开始时间。 字段说明：预计配送开始时间,时间格式为 yyyy-mm-dd hh:mm:ss。
delivery_clerk	string	否	否	否	配送员电话
come_again	string	否	否	否	字段名称：再来一单。 字段说明：商家或 isv 回流的再来一单链接。
delivery_start_time	string	否	否	否	字段名称：预计送达开始时间。 字段说明：预计送达开始时间,时间格式为 yyyy-mm-dd hh:mm:ss。
store_name	string	否	否	否	字段名称：发货门店。 字段说明：外卖的发货门店。
invoice	string	否	否	否	字段名称：开发票。 字段说明：商家或 isv 回流的开票链接。

商品信息列表
开发者需通过商品信息列表字段（item_order_list）传入商品图片、商品详情页等信息。参数说明如下：

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
item_name	string	是	否	否	商品名称。建议商品名称格式为：{商家名称} {商品名称}
ext_info	orderextinfo	是	否	否	商品扩展参数。该参数用于传入用户购买商品图片及商家商品详情页地址等信息。
l ext_key	string	是	否	否	商品图片 key。固定为 image_material_id。
l ext_value	string	是	否	否	商品图片 value。需传入 上传商品文件 获取的 material_id。

待接单 (pending)
本文详细介绍通过接口 alipay.merchant.order.sync 同步订单状态-待接单 (pending)时需传入的商品信息及扩展字段参数信息。
接口参数 bizcontent 示例

参数说明

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
out_biz_no	string	是	否	否	外部订单号。由商家自定义。   注意：同一笔订单更新状态时，需与首次同步入参一致。
buyer_id	string	是	否	否	支付宝用户 uid。2088 开头的数字。
order_type	string	是	否	否	订单类型。固定为service_order（服务订单）。
order_create_time	string	是	否	否	订单创建时间，即该笔订单真实的创建时间。时间格式为 yyyy-mm-dd hh:mm:ss。
order_modified_time	string	是	是	否	订单修改时间，时间格式为 yyyy-mm-dd hh:mm:ss.sss。用于订单状态或数据变化较快的顺序控制，防止乱序。order_modified_time较晚的同步会被最终存储，order_modified_time相同的两次同步会被幂等处理。
source_app	string	否	否	否	订单来源，默认alipay(支付宝小程序)，钉钉来源dingtalk，其它来源枚举值定义联系支付宝订单中心添加。
ext_info	orderextinfo	是	是	否	订单扩展字段。详情可查看下文 订单扩展字段。
item_order_list	itemorderinfo	是	否	否	商品信息列表。详情可查看下文 商品信息列表。
trade_no	string	否	否	否	支付宝交易号。 此字段关联支付宝账单详情卡片，建议回传真实有效交易号。
amount	price	选填，建议传入 (当支付宝交易号trade_no或pay_amount为必传时须传入amount)	是	否	订单总金额。精确到小数点后两位，单位为 元。
pay_amount	price	选填，建议传入该参数	否	否	实际支付金额。精确到小数点后两位。单位为 元。
discount_amount	price	否	否	否	优惠金额。传入 discount_info_list  时必填。单位为 元。

订单扩展字段
开发者需通过订单扩展字段（ext_info）更新订单状态，订单业务信息，订单类型等数据，入参为 ext_key(对应参数的key)、ext_value(对应参数的value) 配合使用。参数说明如下：

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
l ext_key	string	是	否	否	订单状态 key。固定为 merchant_order_status
l ext_value	string	是	是	否	订单状态, 例: pending
l ext_key	string	是	否	否	订单类型 key。固定为 merchant_biz_type。
l ext_value	string	是	否	否	订单类型 value。本业务场景为: take_out
l ext_key	string	是	否	否	订单详情地址 key。固定为merchant_order_link_page。
l ext_value	string	是	否	否	商家小程序对应的订单详情页路径地址 value。仅需传入小程序页面路径即可。
l ext_key	string	是	否	否	商家小程序 appid key。固定为 tiny_app_id。
l ext_value	string	是	否	否	商家小程序 appid value。传入订单归属的小程序 appid。
l ext_key	string	是	否	否	订单业务场景相关的信息 key。固定为 business_info。
l ext_value	jsonstring	是	是	否	订单业务信息详情 value。入参详情见下文 业务信息参数。

业务信息参数
业务信息参数（business_info） 的各项入参详情如下：

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
distribution_end_time	string	否	否	否	字段名称：预计配送结束时间。 字段说明：预计配送结束时间，时间格式为 yyyy-mm-dd hh:mm:ss。
rider_position	string	否	否	否	骑手位置
delivery_end_time	string	否	否	否	字段名称：预计送达结束时间。 字段说明：预计送达结束时间,时间格式为 yyyy-mm-dd hh:mm:ss。
take_out_order_type	string	否	否	否	订单类型
distributor_information	string	否	否	否	配送商信息
store_address	string	否	否	否	字段名称：发货地址。 字段说明：发货门店的所在位置。
distribution_start_time	string	否	否	否	字段名称：预计配送开始时间。 字段说明：预计配送开始时间,时间格式为 yyyy-mm-dd hh:mm:ss。
delivery_clerk	string	否	否	否	配送员电话
come_again	string	否	否	否	字段名称：再来一单 字段说明：商家或 isv 回流的再来一单链接。
delivery_start_time	string	否	否	否	字段名称：预计送达开始时间。 字段说明：预计送达开始时间,时间格式为 yyyy-mm-dd hh:mm:ss。
store_name	string	否	否	否	字段名称：发货门店。 字段说明：外卖的发货门店。
invoice	string	否	否	否	字段名称：开发票。 字段说明：商家或 isv 回流的开票链接。

商品信息列表
开发者需通过商品信息列表字段（item_order_list）传入商品图片、商品详情页等信息。参数说明如下：

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
item_name	string	是	否	否	商品名称。建议商品名称格式为：{商家名称} {商品名称}
ext_info	orderextinfo	是	否	否	商品扩展参数。该参数用于传入用户购买商品图片及商家商品详情页地址等信息。
l ext_key	string	是	否	否	商品图片 key。固定为 image_material_id。
l ext_value	string	是	否	否	商品图片 value。需传入 上传商品文件 获取的 material_id。

已接单 (order_taken)
本文详细介绍通过接口 alipay.merchant.order.sync 同步订单状态-已接单 (order_taken)时需传入的商品信息及扩展字段参数信息。
接口参数 bizcontent 示例

参数说明

参数	类型	是否必填	能否更新	是否消息使用字段	参数说明
out_biz_no	string	是	否	是	外部订单号。由商家自定义。   注意：同一笔订单更新状态时，需与首次同步入参一致。
buyer_id	string	是	否	否	支付宝用户 uid。2088 开头的数字。
order_type	string	是	否	否	订单类型。固定为service_order（服务订单）。
order_create_time	string	是	否	是	订单创建时间，即该笔订单真实的创建时间。时间格式为 yyyy-mm-dd hh:mm:ss。
order_modified_time	string	是	是	否	订单修改时间，时间格式为 yyyy-mm-dd hh:mm:ss.sss。用于订单状态或数据变化较快的顺序控制，防止乱序。order_modified_time较晚的同步会被最终存储，order_modified_time相同的两次同步会被幂等处理。
source_app	string	否	否	否	订单来源，默认alipay(支付宝小程序)，钉钉来源dingtalk，其它来源枚举值定义联系支付宝订单中心添加。
ext_info	orderextinfo	是	是	否	订单扩展字段。详情可查看下文 订单扩展字段。
item_order_list	itemorderinfo	是	否	否	商品信息列表。详情可查看下文 商品信息列表。
trade_no	string	否	否	否	支付宝交易号。 此字段关联支付宝账单详情卡片，建议回传真实有效交易号。
amount	price	选填，建议传入 (当支付宝交易号trade_no或pay_amount为必传时须传入amount)	是	否	订单总金额。精确到小数点后两位，单位为 元。
pay_amount	price	选填，建议传入该参数	否	否	实际支付金额。精确到小数点后两位。单位为 元。
discount_amount	price	否	否	否	优惠金额。传入 discount_info_list  时必填。单位为 元。

订单扩展字段
开发者需通过订单扩展字段（ext_info）更新订单状态，订单业务信息，订单类型等数据，入参为 ext_key(对应参数的key)、ext_value(对应参数的value) 配合使用。参数说明如下：

参数

类型

是否必填