通用参数

收藏

我的收藏

请求公共参数

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

字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
Byte-Authorization	string	Header	是	签名参数，详见签名算法

响应公共参数

字段名	类型	字段说明
err_no	int	错误码，详见后文错误码列表，成功时为 0。 目前系统在快速迭代，请尽量不要依赖非成功错误做逻辑。
err_tips	string	错误提示，这个字段会给出具体的错误原因。

关于 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"}

字段和格式约定

重要 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，如果没有特殊说明则默认合法格式如下：
• <= 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 字符集，所有字段都不支持二进制数据传递（非二进制安全）。

签名参数

签名参数均在 Header 头中，具体参数详见签名算法。