通用参数

更新时间 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 注意生成token的返回值access_token 和请求交易接口的access-token值是同一个概念，字段名有差异。

平台请求开发者公共参数

注意：这里是平台调用开发者系统的时候请求头中携带的内容

字段名	类型	位置	是否必填	字段说明	取值范例
Content-Type	string	Header	是	固定值：application/json	application/json
Byte-Identifyname	string	Header	是	开发者回调路径，不包含域名	/order/create_order_callback_url
Byte-Logid	string	Header	是	抖音开平统一日志id，当出现问题时可以提供此id给抖音研发人员协助定位问题	20230504163800ABA7347CE4F5
Byte-Nonce-Str	string	Header	是	随机字符串，由字母、数字、下划线组成，区分大小写，len(Byte-Nonce-Str) <= 128，请参考-签名算法	Bhw73xUDN91kova0f3KkVegl0WPpz9BZ
Byte-Signature	string	Header	是	请求包签名，请参考-签名算法	mx0xMwumjHScvSjFHjKTvSlBJu1G2aw==
Byte-Timestamp	string	Header	是	请求时间戳，精度：秒，请参考-签名算法	1683189481

签名算法

•

外部开发者请求抖音开放平台交易系统接口

如上面的请求公共参数说明，抖音开放平台交易系统的 OpenAPI 接口均使用 access-token 参数鉴权，如无特殊说明则不需要添加额外的签名参数。

•

抖音开放平台交易系统请求外部开发者的接口

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

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

关于 xxx_entry_schema 的前置说明

在接入的 open-api 中，有些 open-api 会有一个叫 xxx_entry_schema 的参数，这个参数是小程序某个页面的跳转地址，比如在下单场景中会要求开发者传入 orderEntrySchema 的字段，因为小程序的订单会展示在抖音 app 的订单中心，用户从抖音订单中心进入小程序订单详情页的时候需要一个跳转地址，这个地址就是开发者传入的 orderEntrySchema 字段。请注意凡是使用 path+params 字段的方式传递小程序 xx 详情页跳转地址的位置，path 和 params 都必须严格符合下列规范：

名称	类型	是否必传	描述	正确示例	错误示例
path	string	是	小程序xxx详情页跳转路径，没有前导的“/”，路径后不可携带query参数，路*径中不可携带『？: & 』等特殊字符，路径只可以是『英文字符、数字、_、/ 』等组成，长度<=512byte**	page/path/index	page/path/index?id=1234page/path:hello/index
params	string	否	xx情页路径参数，自定义的json结构，内部为k-v结构，序列化成字符串存入该字段，平台不限制，但是写入的内容需要能够保证生成访问xx详情的schema能正确跳转到小程序内部的xx详情页，长度须<=512byte，params内key不可重复。	{\"id\":1192864,\"name\":\"hello\"}	{"id":1234,"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 进行唯一关联（一对一关联），开发者应保证此类型（不限于订单号，也包含退款单号、履约单号等）的单号在appid下的唯一性。
item_order_id	用户下单的单个订单里购买多份商品，交易系统会为每一份商品生成一个内部的子订单 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 字符集，所有字段都不支持二进制数据传递（非二进制安全）。

该文档是否有帮助？

本页导读

平台请求开发者公共参数

签名算法

关于 xxx_entry_schema 的前置说明

字段和格式约定

重要 ID 字段说明

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

通用参数

​平台请求开发者公共参数​

​签名算法​

​关于 xxx_entry_schema 的前置说明​

​字段和格式约定​

​重要 ID 字段说明​

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

平台请求开发者公共参数

签名算法

关于 xxx_entry_schema 的前置说明

字段和格式约定

重要 ID 字段说明

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