通用参数

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

我的收藏

开发者请求公共参数

所有 OpenAPI 接口均需要设置这几个字段，API 文档中将不再重复解释。

字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
access-token	string	Header	是	调用/oauth/client_token/生成的token，此token不需要用户授权。示例: clt.xxx

平台请求公共参数

注意：这里是平台调用开发者扩展点时发送给开发者的请求

字段名	类型	位置	是否必填	字段说明	取值范例
Content-Type	string	Header	是	固定值：application/json	application/json
Byte-Identifyname	string	Header	是	开发者回调路径，不包含域名	/order/create_order_callback_url
Byte-Logid	string	Header	是	日志id，请参考-签名算法	20230504163800ABA7347CE4F5
Byte-Nonce-Str	string	Header	是	随机字符串，请参考-签名算法	Bhw73xUDN91kova0f3KkVegl0WPpz9BZ
Byte-Signature	string	Header	是	请求包签名，请参考-签名算法	mx0xMwumjHScvSjFHjKTvSlBJu1G2aw==
Byte-Timestamp	string	Header	是	请求时间戳，精度：秒，请参考-签名算法	1683189481

签名算法

外部开发者请求代运营交易系统接口

如上面的请求公共参数说明，代运营交易系统的 OpenAPI 接口均使用 access-token 参数鉴权，不需要添加额外的签名参数。

代运营交易系统请求外部开发者的接口

当代运营交易系统需要回调开发者接口时，比如预下单回调、支付完成通知等场景，代运营交易系统会在 header 中添加签名参数，开发者需要对签名参数进行校验。

具体的签名算法请参考-签名算法-签名验证。

响应公共参数

extra 信息

名称	类型	是否必填	描述	示例值
error_code	int	是	错误码，0为成功	0
description	string	是	错误码描述	success
sub_error_code	int	是	子错误码	0
sub_description	string	是	子错误码描述	success
logid	string	是	请求id	2022092115392201020812109511046
now	int	是	时间戳	1663815603

关于 xxx_entry_schema 的前置说明

在接入的 open-api 中，有些 open-api 会有一个叫 xxx_entry_schema 的参数，这个参数是小程序某个页面的跳转地址，比如在下单场景中平台调用开发者预下单接口后会要求开发者返回一个叫 order_entry_schema 的字段，因为小程序的订单会展示的抖音 app 的订单中心，用户从抖音订单中心进入小程序订单详情页的时候需要一个跳转地址，这个地址就是开发者返回的 order_entry_schema 字段。请注意凡是使用 path+params 字段的方式传递小程序 xx 详情页跳转地址的位置，path 和 params 都必须严格符合下列规范，后续相关文档字段说明中将不再在各处对此规范约束进行说明：

名称	类型	是否必传	描述	正确示例	错误示例
path	string	是	小程序xxx详情页跳转路径，没有前导的“/”，*路径后不可携带query参数，路径中不可携带『？: & 』等特殊字符，路径只可以是『英文字符、数字、_、/ 』等组成**，长度<=512byte	page/path/index	page/path/index?id=1234 page/path:hello/index
params	string	否	xx情页路径参数，自定义的json结构，序列化成字符串存入该字段，平台不限制，但是写入的内容需要能够保证生成访问xx详情的schema能正确跳转到小程序内部的xx详情页，长度须<=512byte，params内key不可重复。	{"id":1234,"name":hello}	{"id":1234,"id":2334,"name":hello}

名称

类型

是否必传

描述

正确示例

错误示例

path

string

是

小程序xxx详情页跳转路径，没有前导的“/”，路径后不可携带query参数，路径中不可携带『？: & *』等特殊字符，路径只可以是『英文字符、数字、_、/ 』等组成，长度<=512byte

page/path/index

page/path/index?id=1234

page/path:hello/index

params

string

否

xx情页路径参数，自定义的json结构，序列化成字符串存入该字段，平台不限制，但是写入的内容需要能够保证生成访问xx详情的schema能正确跳转到小程序内部的xx详情页，长度须<=512byte，params内key不可重复。

{"id":1234,"name":hello}

{"id":1234,"id":2334,"name":hello}

字段和格式约定

重要 ID 字段说明

抖音开平交易系统内部使用的单号输出给开发者时，一般以 xxx_id 进行命名，如 order_id、item_order_id、refund_id 等。
开发者系统的单号输出给开发者一般以 xxx_no 进行命名，如 out_order_no、out_refund_no 等。

ID 字段	说明
order_id	用户下单时，交易模板为用户的交易订单生成的交易订单号，即抖音开放平台系统内部的订单号。
out_order_no	开发者系统生成的交易单号。用户下单时，抖音开放平台交易模板会将下单的请求发送到开发者的系统，此时请求参数里会携带交易模板内部系统生成的交易单号 order_id。当开发者系统确认并返回给抖音开放平台交易系统成功时，此返回中应携带开发者系统为本次交易生成的订单号，也就是 out_order_no。同时，在开发者处理请求的时候，应自行将交易模板系统的内部订单号 order_id 和自己系统生成的订单号 out_order_no 进行唯一关联（一对一关联）。
item_order_id	用户下单的单个订单里券的数量可能是 N 张，对应这 N 张券，交易模板会为每一张券生成一个内部的虚拟券 ID，即 item_order_id，这个券 ID 在核销和退款流程里会被用到。

ID 字段

说明

order_id

用户下单时，交易模板为用户的交易订单生成的交易订单号，即抖音开放平台系统内部的订单号。

out_order_no

开发者系统生成的交易单号。

用户下单时，抖音开放平台交易模板会将下单的请求发送到开发者的系统，此时请求参数里会携带交易模板内部系统生成的交易单号 order_id。

当开发者系统确认并返回给抖音开放平台交易系统成功时，此返回中应携带开发者系统为本次交易生成的订单号，也就是 out_order_no。同时，在开发者处理请求的时候，应自行将交易模板系统的内部订单号 order_id 和自己系统生成的订单号 out_order_no 进行唯一关联（一对一关联）。

item_order_id

用户下单的单个订单里券的数量可能是 N 张，对应这 N 张券，交易模板会为每一张券生成一个内部的虚拟券 ID，即 item_order_id，这个券 ID 在核销和退款流程里会被用到。

重要字段的格式和约束说明

对于系统涉及到的订单号类 ID，如果没有特殊说明则默认合法格式如下：

<= 64 byte
由 ASCII 英文字符、数字组成，区分大小写

用户、商户、商家等身份类id标志，如果没有特殊说明则默认合法格式如下：

<= 32 byte
由 ASCII 英文字符、数字组成，区分大小写

金额的单位，统一为分。
URL 类字段长度必须 <= 512 byte，支持 UTF-8 字符集，不支持 Unicode 字符。
时间类型的相关字段有 string 和 int 两种类型：

string 类型时间如无特殊说明，则格式为 yyyy-MM-dd HH:mm:ss。
int 型时间则为系统时间戳，单位为毫秒，即 1970 年 1 月 1 日到当前时间所走过的毫秒数。

开发者传递的透传字段，长度不得超过 2048 byte，格式不限，不支持二进制数据。
所有接口默认支持字符集为 UTF-8，不支持 Unicode 字符集，所有字段都不支持二进制数据传递（非二进制安全）。

下一篇：小程序文档指引

文档评论

登录后可参与评论