订单同步

更新时间 2024-07-24 02:58:49

我的收藏

能力说明：接入担保支付、但未接入交易系统的订单，开发者必须通过订单同步接口将订单信息推送到抖音订单中心和小程序订单中心，便于用户在抖音订单中心和小程序订单中心查找订单信息，并可再次回访小程序。

注意：如果不接入订单同步接口，不符合上线要求，审核将会被驳回。

前置条件

小程序上架提审前，需要对应小程序存在一笔订单。如果接入交易系统，在交易之后，对应的订单会自动完成同步；如果未接入交易系统，需要根据该文档指引完成一次订单同步。

常见问题

为什么同步订单并返回成功，但是订单中心却无法看到订单？

可能存在三个原因：

•

首次上传非 POI 订单的小程序 APPID 需要打开订单展示权限（白名单）。小程序申请开通抖音支付后，会在小程序上架审核环节系统自动加权限；部分历史未自动开通成功的小程序将在发版审核上架后平台主动协助开通。

•

开发者请求订单同步接口时item_list参数为空

•

用户未开启小程序授权：用户未授权该普通小程序的订单展示权限，需引导用户打开，打开方式如下：

我的订单 > 右上角更多 > 授权设置 > 选择对应的小程序并打开授权

为什么我的订单只能在全部 tab 下看到？

目前**普通小程序订单（order_type=0）**还不支持 tab 归类，仅会在全部订单 tab 下可见。

为什么有时直接返回 HTTPcode 400 且错误码不为下面规范的错误码？

出现此情况一般为输入参数的字段类型设置错误，比如将 int 类型字段上传成 string 类型。请仔细检查输入字段的类型是否正确。

使用限制

订单推送接口接入之前必须接入担保支付。具体操作请参见担保支付接入指南。

接口说明

•

接口适用范围：接入交易系统的订单将不再需要本接口进行推送，交易系统将会自动推送至抖音订单中心。

•

订单类型释义：

◦

POI订单：当订单内的商品是进入了抖音商品库的商品称为 POI 订单，请参照下述订单类型上传order_detail。

◦

非 POI 订单：未做商品同步的则为非 POI 订单。请使用小程序普通订单规范上传 order_detail。

•

非 POI 订单统一为普通小程序订单，order_type 为 0

•

open_id 生成规范: 小程序开发说明 IDE 中的 open_id 生成逻辑与真机调试不同，使用 IDE 中的 open_id 做订单同步会出现错误，请使用真机调试做订单同步。

基本信息

基本信息
HTTP URL	https://developer.toutiao.com/api/apps/order/v2/push
HTTP Method	POST
权限要求	无

请求头

参数名称	类型	是否必填	描述
Content-Type	string	是	固定值 "application/json"

请求参数

参数名称	类型	是否必填	描述	示例值
client_key	string	否	第三方在抖音开放平台申请的 ClientKey 注意：POI 订单必传	awx1334dlkfjdf
access_token	string	是	服务端 API 调用标识，通过 getAccessToken 获取
ext_shop_id	string	否	POI 店铺同步时使用的开发者侧店铺 ID，购买店铺 ID，长度 < 256 byte 注意：POI 订单必传	ext_112233
app_name	string	是	做订单展示的字节系 app 名称，目前为固定值“douyin”	douyin
open_id	string	是	小程序用户的 open_id，通过 code2Session 获取	d33432323423
order_detail	string	是	json string，根据不同订单类型有不同的结构体，请参见 order_detail 字段说明（json string）
order_status	int64	否	普通小程序订单订单状态，POI 订单可以忽略 •0：待支付 •1：已支付 •2：已取消（用户主动取消或者超时未支付导致的关单） •4：已核销（核销状态是整单核销,即一笔订单买了 3 个券，核销是指 3 个券核销的整单） •5：退款中 •6：已退款 •8：退款失败注意：普通小程序订单必传，担保支付分账依赖该状态	4
order_type	int64	是	订单类型，枚举值: •0：普通小程序订单（非POI订单） •9101：团购券订单（POI 订单） •9001：景区门票订单（POI订单）	0
update_time	int64	是	订单信息变更时间，10 位秒级时间戳， update_time每次状态变更推送时需要比上次推送的值大，否则可能忽略该次状态推送。例如：某次推送订单时的update_time为1694761323，则下次推送该订单时，update_time至少为1694761324。	1694761323
extra	string	否	自定义字段，用于关联具体业务场景下的特殊参数，长度 < 2048byte

order_detail 字段说明（json string）

POI 订单

•

9101 团购券类型：

参数名称	类型	是否必填	描述	示例值
ext_order_id	string	是	开发者系统侧业务单号。用作幂等控制。该订单号是和担保支付的支付单号绑定的，即预下单时传入的 `out_order_no` 字段，长度 <= 64byte	20190101000001654bb46ba
status	int64	是	枚举值： •10：已取消（抖音订单中心可看到，状态为"已取消"） •110：待支付 •310：未使用 •340：已使用 •410：退款中 •420：退款成功 •430：退款失败	340
shop_name	string	是	商铺名字，长度 <= 256 byte	迪士尼乐园
entry_type	int64	是	订单详情页的外链跳转类型，通过该接口上传的都为 2 •1：H5 •2：抖音小程序	2
entry_schema	string	是	订单详情页的外链跳转 schema 参数，格式为 json 字符串。长度 <= 512byte，具体参数详见 entry_schema说明
create_order_time	int64	是	下单时间（13位毫秒时间戳）	1648453349123
description	string	否	订单描述，长度<=500 byte
total_price	int64	是	订单总金额（单位：分）	2000
pay_time	int64	否	支付时间（13位毫秒时间戳），未付款时不用传。	1648453349123
ext_valid_shop_id	string	否	开发者侧卡劵核销门店ID，未核销时不用传，长度 <= 256 byte
valid_poi_id_str	string	否	开发者侧卡劵核销门店对应的抖音poiId，ext_valid_shop_id未匹配抖音POI时不用传，长度<= 128 byte
ext_goods_id	string	是	开发者侧商品ID，长度<= 64 byte 备注：如果该商品没有接入抖音商品库，该字段为空	787719
goods_name	string	是	商品名称，长度 <= 256 byte	成人两日联票
goods_info	string	否	商品描述信息。向用户介绍商品，长度 <= 120byte。	可以玩任一项目
goods_cover_image	string	是	商品图片，完整的url地址长度 <= 512 byte	https://xxxxxxxxxxxxxxxxxxxxxx
goods_entry_type	int64	是	商品详情页的外链跳转类型, 通过该接口上传的都为2 1: H5 2: 抖音小程序	2
goods_entry_schema	string	是	商品详情页的外链跳转schema参数，格式为 JSON 字符串，长度 <= 512 byte，详见 entry_schema说明
start_valid_time	string	是	生效时间，yyyy-MM-dd HH:mm:ss 格式字符串，24 小时制	"2017-01-13 00:00:00"
end_valid_time	string	是	失效时间，yyyy-MM-dd HH:mm:ss格式字符串，24小时制	"2017-01-13 23:59:59"
ticket_num	int64	是	用户购买团购券的数量	2
ext_ticket_ids	list	否	开发者侧券 ID，该信息用于用户可以明确的感知是哪一张券。格式为 JSON 数组字符串，每个 ID 长度 <= 64byte	["123", "abc"]
ticket_description	list	否	券的使用说明。JSON 数组字符串，最多可以有10条，每条长度 <= 50byte。必须写明券的使用条件、领取条件、退款规则，请参考示例。	["1、本券不可兑换现金，不可找零。","2、每个用户最多可以领取1张。","3、如果订单发生退款，优惠券无法退还。"]

•

9001 门票类型：

参数名称	类型	是否必传	描述	示例值
ext_order_id	string	是	开发者侧业务单号。用作幂等控制。该订单号是和担保支付的支付单号绑定的，也就是预下单时传入的 `out_order_no` 字段，长度 <= 64byte	20190101000001654bb46ba
status	int64	是	枚举值，如下： •10：已取消（抖音订单中心可看到，状态为"已取消"） •110：待支付 •210：待确认 •340：预订成功 •410：退款中 •420：退款成功 •430：退款失败	110
shop_name	string	是	商铺名字, 长度 <= 256 byte	迪士尼乐园
entry_type	int64	是	订单详情页的外链跳转类型, 通过该接口上传的都为 2 •1：H5 •2：抖音小程序	2
entry_schema	string	是	订单详情页的外链跳转 schema 参数，格式为 JSON 字符串。长度 <= 512byte，具体参数详见entry_schema说明
create_order_time	int64	是	下单时间（13位毫秒时间戳）	1648453349123
description	string	否	订单描述，长度<=500 byte
total_price	int64	是	订单总金额（单位：分）	2000
pay_time	int64	否	支付时间（13位毫秒时间戳），未付款不用传。	1648453349123
ext_goods_id	string	否	开发者侧商品ID，长度<= 64 byte 备注：如果该商品没有接入抖音商品库，该字段为空	787719
goods_name	string	是	商品名称，长度 <= 256 byte	成人两日联票
goods_info	string	否	商品描述信息。向用户介绍商品，长度 <= 120byte。	可以玩任一项目
goods_cover_image	string	是	商品图片，完整的url地址长度 <= 512 byte	https://xxxxxxxxxxxxxxxxxxxxxx
goods_entry_type	int64	是	商品详情页的外链跳转类型, 通过该接口上传的都为2 1: H5 2: 抖音小程序	2
valid_poi_id_str	string	否	开发者侧卡劵核销门店对应的抖音poiId，ext_valid_shop_id未匹配抖音POI时不用传，长度<= 128 byte
goods_entry_schema	string	是	商品详情页的外链跳转schema参数，格式为json字符串，长度 <= 512 byte，详见 entry_schema说明
start_valid_time	string	是	生效时间，景区门票是游玩起始日期，yyyy-MM-dd HH:mm:ss 格式字符串，24小时制	"2017-01-13 00:00:00"
end_valid_time	string	是	失效时间，景区门票是游玩起始日期，yyyy-MM-dd HH:mm:ss 格式字符串，24小时制	"2017-01-13 23:59:59"
ticket_num	int64	是	用户购买票的数量，未传或小于等于 0 则默认为 1	2
ext_ticket_ids	list	否	开发者侧票 ID，该信息用于用户可以明确的感知是哪一张票。格式为 JSON 数组字符串，每个 ID 长度 <= 64byte	["123", "abc"]
ticket_description	list	否	票的使用说明。JSON 数组字符串，最多可以有10条，每条长度 <=50 byte。必须写明票的使用条件、领取条件、退款规则，请参考示例。	["1、本券不可兑换现金，不可找零。","2、每个用户最多可以领取1张。","3、如果订单发生退款，优惠券无法退还。"]

非 POI 订单

•

普通小程序订单：

参数名称	类型	是否必传	描述	示例值
order_id	string	是	开发者侧业务单号。用作幂等控制。该订单号是和担保支付的支付单号绑定的，也就是预下单时传入的 `out_order_no` 字段，长度 <= 64byte	54bb46ba
create_time	int64	是	订单创建的时间，13 位毫秒时间戳	1648453349123
status	string	是	订单状态，建议采用以下枚举值： •待支付 •已支付 •已取消 •已超时 •已核销 •退款中 •已退款 •退款失败	已支付
amount	int64	是	订单商品总数	2
total_price	int64	是	订单总价，单位为分	8800
detail_url	string	是	小程序订单详情页 path，长度<=1024 byte (备注：该路径需要保证在小程序内配置过，相对路径即可）	例如pages/order/orderDetail
item_list	list<itemStruct>	是	子订单商品列表，不可为空

•

itemStruct（item_list数组元素）字段说明：

参数名称	类型	是否必传	描述	示例值
item_code	string	是	开发者侧商品 ID，长度 <= 64 byte	test_item_code
img	string	是	子订单商品图片 URL，长度 <= 512 byte	https://xxxxxxxxxxxxxxxxxxxxxx
title	string	是	子订单商品介绍标题，长度 <= 256 byte	好日子
sub_title	string	否	子订单商品介绍副标题，长度 <= 256 byte
amount	int64	是	单类商品的数目	2
price	int64	是	单类商品的总价，单位为分	4400

请求示例

js复制

curl -X POST 'https://developer.toutiao.com/api/apps/order/v2/push'
-H 'Content-Type:application/json'
--data-raw '{
    "client_key": "awxxtttsdfdff", // string 类型， POI订单必传
    "access_token": "test_token", // string类型，必传字段，服务端 API 调用标识
    "ext_shop_id": "test_ext_shop_id", // 开发者侧店铺ID
    "app_name": "douyin", // 必传字段，做订单展示的字节系 app 名称，取值如下表所示
    "open_id": "test_open_id", // 小程序open id
    "update_time": 1648453123, // 订单信息变更时间，10位秒级时间戳
    "order_detail": "{\"detail_url\":\"https://www.xxxx.com/shop/order/orderDetail?orderId=21000240218164635217330&pad_check=df126473398e4840111ba0c620ca1c5c\",\"amount\":2,\"create_time\":1708245997095,\"total_price\":2,\"item_list\":[{\"amount\":1,\"img\":\"https://www.xxxx.com/resources/2063/1915501.jpg\",\"price\":1,\"title\":\"字节小程序语音版\"},{\"amount\":1,\"img\":\"https://www.xxxx.com/resources/2063/19155_01.jpg\",\"price\":1,\"title\":\"主卡\"}],\"order_id\":\"21000240218164635217330\",\"status\":\"订单已完成\"}", // 订单细节，根据不同订单类型有不同的结构体
    "order_type": 0, // 订单类型
    "order_status": 1,  //当order_type为0（普通小程序订单，非poi订单）时，请关注，必传
    "extra": "" ,
}'

响应参数

参数名称	类型	是否必传	描述	示例值
err_code	int64	是	错误号（请根据以下错误码及错误内容确认问题）	0
err_msg	string	是	错误信息	success
body	string	否	POI 等关联业务推送结果，非 POI 订单为空，JSON 字符串

响应示例

正常示例

js复制
//普通小程序订单
//正常返回,
{
    "err_code":0,         // 错误码
    "err_msg":"success",      // 错误提示
    "body":""   //小程序普通订单，body为空 
}

//POI订单
{
    "err_code":0,         // 错误码
    "err_msg":"success",      // 错误提示
    "body":"{\"data\":{\"description\":\"\",\"error_code\":0,\"order_id\":\"0\"}"    //正常返回，body里面的error_code也为0
}

异常示例

js复制
//普通小程序订单
{
    "err_code":40014,         // 错误码 
    "err_msg":"app_name错误，请检查该字段的枚举类型",// 错误提示，请根据错误提示查找对应原因
    "body":""  //小程序普通订单，body为空
}



//POI订单
//异常返回1
{
    "err_code":40014,         // 错误码
    "err_msg":"app_name错误，请检查该字段的枚举类型",      // 错误提示，请根据错误提示查找对应原因
    "body":""  //body为空
}

//异常返回2
{
    "err_code":40099,         // 错误码
    "err_msg":"未知错误：xxxxx",      // 错误提示，请根据错误提示查找对应原因
    "body":"{\"data\":{\"description\":\"参数异常\",\"error_code\":21005,\"order_id\":\"0\"}"  //body不为空
}

错误码

通用错误码及错误描述

err_code	err_msg	原因	解决办法
-1	系统错误，请重试	系统内部错误	请重试，如果多次未成功，联系抖音技术支持解决
40001	order_type 为不支持的订单类型	order_type 不为文档所描述的枚举值类型	请检查订单类型是否为该字段枚举值
40002	order_type 类型不匹配	order_type 错误，和首次上传的该订单类型不匹配，无法更新	将该订单的 order_type 调整为原始 type 进行上传
40003	access_token 为必填字段	access_token 为空	通过 access_token 获取
40004	access_token 错误，请检查该字段是否错误或过期	access_token解析错误，可能该字段值错误或者已经过期	通过 access_token 获取注意：重新获取 access_token会导致上一次获取的 access_token 会在 5 分钟内失效
40010	open_id 为必填字段	open_id 为空	确认字段是否传递，通过 code2Session 获取 open_id
40011	open_id 错误, 请确认生成方式是否正确	open_id 和该小程序没有绑定关系	检查 open_id 的生成方式是否和通过 code2Session 获取的 open_id 一致，生成open_id的小程序和推送订单小程序是否为同一个小程序
40012	open_id 错误, 请确认是否是在抖音/抖音极速版 app 内生成	open_id 必须在抖音/抖音极速版 app 内生成，否则不可用	检查 open_id 是否是在抖音/抖音极速版 app 内生成。注意：请勿在 IDE 调试，这样生成的 open_id 可能不正确，需要用抖音/抖音极速版真机调试进行生成
40013	app_name 为必填字段	该字段必填	确认字段是否传递
40014	app_name 错误，请检查该字段的枚举类型	app_name 值在系统内枚举中不存在	app_name 取文档中给定的枚举值
40015	timestamp 错误	时间值不符合文档中描述的时间戳取值规则	检查报文中的时间相关字段是否和文档中描述的时间戳取值规则一致
40016	update_time 早于或等于上次订单更新时间	update_time 早于或等于上次订单的更新时间	请更新 update_time，如果和上传的时间相等或小于上次该订单的更新时间，订单得不到更新
40017	update_time 错误	update_time 不符合文档中描述的 10 位时间戳取值规则	检查 update_time 是否和文档中描述的 10 位时间戳取值规则一致
40022	担保支付订单不存在	订单推送需要确认该订单是否与担保支付的支付单有绑定关系，如果没有，将返回此错误	检查 order_detail.order_id/order_detail.ext_order_id 取值是否正确
40023	该 appid 无支付权限，请确认是否开通担保支付	appid 未开通支付权限	请在开发者后台申请开通支付权限
40025	不允许推送交易系统的订单	交易系统会自动进行订单推送，不需要开发者手动推	交易系统的单请开发者去掉自己推送订单的逻辑
40043	请求包含的sku数量过多	推送订单中itemList 中元素个数过多(超过了200个)	限制item_list大小
40073	item_list 不可为空	非poi订单推送，item_list 参数为空	填充item_list信息
40099	未预先分配错误码的错误，即其他错误	未预先分配错误码	先自行确定错误内容是否能够确认，如果不能，请联系抖音技术支持例如: poiBiz预校验异常。表示poi订单状态扭转非法

POI 订单错误码及描述

err_code	err_msg	原因	解决办法
40005	POI 订单 order_detail 字段格式错误，请检查 order_detail 内部参数类型是否有误	order_detail 字段内部分字段类型不符合规范	检查 order_detail 字段内各个字段的类型是否为上述输入所描述的类型
40007	POI 订单 client_key 为必填字段	POI 订单，该字段必填	确认字段是否传递
40008	POI订单 ext_shop_id 为必填字段	POI 订单，该字段必填	确认字段是否传递
40009	POI 订单 order_detail.ext_order_id 为必填字段	POI 订单，该字段必填	确认字段是否传递
40018	POI 订单 order_detail.start_valid_time 格式错误	order_detail.start_valid_time 不符合 yyyy-MM-dd HH:mm:ss 格式字符串，24 小时制	检查 order_detail.start_valid_time 字段格式是否是 yyyy-MM-dd HH:mm:ss 格式字符串，24 小时制
40019	POI 订单 order_detail.end_valid_time 格式错误	order_detail.end_valid_time不符合 yyyy-MM-dd HH:mm:ss 格式字符串，24 小时制	检查 order_detail.end_valid_time 字段格式是否是 yyyy-MM-dd HH:mm:ss 格式字符串，24 小时制
40020	POI 订单 order_detail.create_order_time 格式错误	order_detail.create_order_time 不符合文档中描述的 13 位时间戳取值规则	检查 order_detail.create_order_time 是否和文档中描述的 13 位时间戳取值规则一致
40021	POI 订单 order_detail.status 错误	order_detail.status 没有对应的枚举值	检查 order_detail.status 是否和文档中的枚举值对应

普通小程序订单错误码及描述

err_code	err_msg	原因	解决办法
40006	order_detail 字段格式错误，请检查 order_detail 内部参数类型是否有误	普通小程序订单 order_detail 字段内部分字段类型不符合规范	检查 order_detail 字段内各个字段的类型是否为上述输入所描述的类型
40024	order_detail.order_id 为必填字段	普通小程序订单，该字段为空	确认字段是否传递

entry_schema 格式说明

描述	范例
外链跳转 schema 参数，格式为 JSON 字符串。对应的 entry_type 为 2 时，参数： •`app_id(string)`：小程序的 app_id •`is_test(int64)`：小程序是否为测试版 ◦0或不填为线上版 ◦1表示测试版 ◦线上版本不要传该参数 •`path(string)`：路径，page前不要加`/` 1.params(stirng)：JSON 字符串	"{ \"app_id\": \"ttxxxffdfabc\", \"is_test\": 1, \"path\": \"pages/orderDetail\", \"params\": \"{ \\\"ext_order_id\\\": \\\"1234\\\"}\" }"