开发
API

小程序订单同步

简介

开发者可通过订单同步接口将订单信息推送到抖音订单中心,便于用户查找订单信息,并提供回访小程序的入口。

订单类型

平台对接入的小程序提供了如下图所示的通用订单模板,可以满足小程序的日常订单复访需求。对于其他具体业务,例如生活服务,需要使用其他类型的订单进行业务的闭环。

订单订单类型适用场景order_type 枚举值
小程序订单普通订单无特殊业务诉求的小程序接入0
景区门票服务生活服务订单本地行业-景区门票9001
预售券订单生活服务订单本地行业-预售券200
团购券订单生活服务订单本地行业-团购券9101
住宿订单生活服务订单本地行业-住宿140

接口定义

POST https://developer.toutiao.com/api/apps/order/v2/push

输入参数

// Content-type:application/json
{
    "client_key": "", // string 类型, POI订单必传
    "access_token": "", // string类型,必传字段,服务端 API 调用标识,
    "ext_shop_id": "", // 外部商户ID
    "app_name": "douyin", // 必传字段,做订单展示的字节系 app 名称,取值枚举: 抖音-douyin
    "open_id": "", // 小程序open id
    "update_time": 0, // 订单信息变更时间,13位毫秒级时间戳
    "order_detail": "", // 订单细节,根据不同订单类型有不同的结构体
    "order_type": 0, // 订单类型 0 - 小程序订单
    // 订单产生场景
    "scene": "",
    "launch_from": "",
    "location": "",
    "extra": ""
}
名称类型必填描述
client_keystringPOI 订单必传第三方在开放平台申请的 ClientKey
access_tokenstring服务端 API 调用标识,字节小程序 getAccessToken (bytedance.com)
ext_shop_idstringPOI 订单必传POI 外部商户 ID,购买店铺 id
app_namestring做订单展示的字节系 app 名称,取值枚举: 抖音-douyin
open_idstring小程序用户的 open id
order_detailstring根据不同订单类型有不同的结构体
order_typeint订单类型,取值:0 - 小程序订单
update_timeint订单信息变更时间,10 位毫秒级时间戳
extrastring自定义字段,用于关联具体业务场景下的特殊参数
scenestring订单生成时的场景值
locationstring
launch_fromstring

输出

返回值为 JSON 形式,返回信息如下:

名称数据类型描述
err_codenumber错误号
err_msgstring错误信息
bodystring生活服务关联业务推送结果与业务信息,json 字符串。小程序订单可忽略

具体对应关系为:

错误号描述
0请求成功
-1系统错误
40002access_token 错误
40003openid 错误
40014http 参数错误
40016appname 错误
40022business_line 错误

接入流程

该接口的普通小程序订单接入流程中,有白名单逻辑,需要先将测试用的 uid 加白,然后录屏展示订单全流程给平台确认后开全量,测试用户 uid 获取方式:抖音 app->我 tab->右上角更多->设置页面下拉至底部->version 点三下,uid 加白请联系 赵邦。白名单测试阶段,只有 uid 加白的用户可以在订单中心中看到订单。在功能开发完成后,提供录屏经验收无误,可以开启全量订单显示。

Q&A

  1. 同步订单并且返回了成功,但是却没有在订单中心中看到订单:请检查 uid 是否开白。确认开白后,核实开白的过期时间,是否白名单配置超过了有效期。
  2. 为什么我没有找到小程序订单的枚举: 普通小程序订单
  3. 为什么我的订单只能在全部 Tab 下看到: 目前小程序订单还不支持 Tab 归类,只会在全部订单 Tab 下可见
  4. 为什么我推送了订单,自己却看不到:IDE 中的 open id 生成逻辑与真机调试不同,如果使用 IDE 中的 open id,则会导致订单推送给错误的用户
  5. 关于“抖音开放平台”和“小程序开发者平台”: 本次对接,需要申请独立的两套开发者账号;“抖音开放平台”用于店铺、SPU 和订单数据同步,“字节跳动小程序开发者平台”用于小程序开发
  6. 传入参数错误可能会直接返回 HTTPcode 400,出现此情况请首先参照实例改变参数或者联系相关同学排查。

订单详情 order_detail 格式定义

小程序订单 detail 格式规范

以下参数均在 JSON body 中。

名称必填数据类型描述
order_idstring订单 id
create_timenumber订单创建的时间,UNIX 时间戳
statusstring订单状态
amountnumber订单商品总数,number 类型
total_pricenumber订单总价,必须为 Number 类型,单位为分
detail_urlstring小程序订单详情页 path
detail_url_backendstring订单详情页备用 url,订单详情页 path 不可用时生效
item_listlist子订单商品列表,不可为空

item_list 字段

名称必填数据类型描述
item_codestring子订单 id
imgstrin子订单商品图片 url,建议尺寸 800*800,大小 500Kb
titlestring子订单商品介绍标题
sub_titlestring子订单商品介绍副标题
amountnumber单类商品的数目,必须为 number 类型
pricenumber单类商品的总价,必须为 Number 类型,单位为分

小程序订单中,对已存在的订单进行重复 push。会以 AppID 与 OrderID 进行判断。对非空值进行更新。

其他类型

景区门票、团购券、预售券、住宿类型订单请联系相关人员一同接入。

点击纠错
评价此篇文档