OpenAPI接口调用约定
OpenAPI 是指抖音侧提供 HTTP 接口,外部服务商/开发者发起调用,将数据传给抖音或者从抖音侧主动查询需要的数据。
1.OpenAPI请求协议说明
抖音开放接口仅支持https协议接入,指定Content-Type为:application/json,支持的有POST和GET方法。
调用流程:获取调用 access-token -> 组装参数,拼装 HTTP 请求 -> 发起 HTTP 请求 -> 获得 HTTP 响应 -> 解析结果
Header 的更多说明【Header 说明】部分。
Header头说明
请求头 | 值设置 | 示例 | 是否必填 | 描述 |
access-token | 参考文档OpenAPI凭证Client-token 生成的token | clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ | 是 | OpenAPI调用凭证 |
content-type | 固定值"application/json" | application/json | 是 | 数据协议类型 |
Rpc-Transit-Life-Account | 来客商户根账户ID | 100010001 | 否 参考具体的接口文档要求进行传输 | 来客商户根账户ID |
X-Stress-Tag | 请求为压测触发的回调,设置该header参数,且值为1 | 1 | 否 非压测场景触发的请求无需传输 | 标识请求源为压测触发的回调 |
2.SDK
为了帮助开发者更加便捷地使用抖音开放能力,简化在接入抖音开放平台时的操作步骤, 开放平台提供了统一的服务端 OpenAPI SDK。开发者可使用OpenAPI SDK,快捷地接入抖音开放平台提供的服务端接口,提升开发效率。需要注意的是SDK中的Token参数需要用户自己注入。当前OpenAPI SDK支持三种编程语言:
- •Java
- •Go
- •NodeJS
Java接入
包引入
在 pom.xml 文件添加仓库和依赖,最新版本为
1.0.6 ,推荐使用最新版本<repository> <id>douyin-openapi-repo</id> <url>https://artifacts-cn-beijing.volces.com/repository/douyin-openapi/</url> </repository>
<dependency> <groupId>com.douyin.openapi</groupId> <artifactId>sdk</artifactId> <version>1.0.6</version> </dependency>
代码示例
import com.aliyun.tea.TeaException; import com.douyin.openapi.client.Client; import com.douyin.openapi.client.models.*; import com.douyin.openapi.credential.models.Config; public class Main { public static void main(String[] args) { try { Config config = new Config().setClientKey("test_app_id").setClientSecret("test_app_secret"); Client client = new Client(config); CouponQueryCouponMetaRequest sdkRequest = new CouponQueryCouponMetaRequest() .setCouponMetaId("test_id") .setBizType(new Integer(1)) .setAccessToken("test_access_token"); CouponQueryCouponMetaResponse sdkResponse = client.CouponQueryCouponMeta(sdkRequest); System.out.println(sdkResponse); } catch (TeaException e) { System.out.println(e.getMessage()); } catch (Exception e) { System.out.println(e.getMessage()); } } }
Go接入
包引入
go get github.com/bytedance/douyin-openapi-sdk-go
代码示例
import ( "fmt" "testing" credential "github.com/bytedance/douyin-openapi-credential-go/client" openApiSdkClient "github.com/bytedance/douyin-openapi-sdk-go/client" ) func TestCouponQueryCouponMeta(t *testing.T) { // 初始化SDK client opt := new(credential.Config). SetClientKey("test_app_id"). SetClientSecret("test_app_secret") sdkClient, err := openApiSdkClient.NewClient(opt) if err != nil { t.Fatal(fmt.Sprintln("sdk init err:", err)) } // 构建请求参数 couponMetaId := "7373678331264630820" bizType := 1 sdkRequest := &openApiSdkClient.CouponQueryCouponMetaRequest{ CouponMetaId: &couponMetaId, BizType: &bizType, } // token获取与注入 // credential包提供了默认的token获取方法,但是该实现方式是基于单实例的,如果用户多实例场景使用会出现token互刷的问题。 // 开发者如果有多实例部署的需求可以自行实现token获取的逻辑 credentialHandler, err := credential.NewCredential(opt) if err != nil { t.Fatal(fmt.Sprintln("credential init err:", err)) } token, err := credentialHandler.GetClientToken() if err != nil { t.Fatal(fmt.Sprintln("token get err:", err)) } sdkRequest.AccessToken = token.AccessToken // sdk调用 sdkResponse, err := sdkClient.CouponQueryCouponMeta(sdkRequest) if err != nil { t.Fatal(fmt.Sprintln("sdk call err:", err)) } t.Log(sdkResponse) }
NodeJS接入
包引入
运行以下命令:
npm add @open-dy/open_api_sdk npm add @open-dy/open_api_credential
代码示例
import Client, { MessageGetUserMessageRequest } from '@open-dy/open_api_sdk'; import CredentialClient from '@open-dy/open_api_credential'; interface ClientTokenResponse { data?: { access_token?: string, description?: string, error_code?: number, expires_in?: number } } // 传入 clientKey 和 clientSecret 获取 tokenconst credentialClient = new CredentialClient({clientKey: 'xxx', clientSecret: 'xxx'}); const { accessToken } = await credentialClient.getClientToken(); // 传入 clientKey 和 clientSecret const client = new Client({ clientKey: 'xxx', clientSecret: 'xxx' }); // 拼接请求入参const params = new MessageGetUserMessageRequest({accessToken:accessToken, startTime:xxx, endTime: xxx, type: xxx, username: xxx, pageNum: xxx, pageSize: xxx }); // 调用方法发起请求const messageRes = await client.messageGetUserMessage(params); console.log('messageRes', messageRes);
3.参数说明
通用参数说明
这里通用参数中包含Header中字段,通用参数不区分解决方案和业务,对接抖音开发生活服务业务时通用概念的信息
字段 | 含义 | 示例值 | 获取方式 |
client_key | 应用唯一标识 | aw05az2qjv****** | 注:APPID,ClientKey都是该含义
登录开发者控制台后查看应用信息,APPID 即 client_key |
client_secret | 应用唯一标识对应的密钥 | 7802f4e6f243e659d51135445fe****** | 登录开发者控制台后查看应用信息,AppSecret 即 client_secret |
account_id | account_id 是本地生活商家账户 ID | | 商家:从 PC 抖音来客右上角或从抖音来客 App - 我 - 置顶个人信息获得
服务商:从控制台-应用详情页-授权管理获得已经授权的商家的“账户 ID” |
access-token | 接口调用凭证 | | |
open_id | 用户 id 加密为 open_id | | 用户 id 在不同应用中对应的 open_id 不同,一般由抖音开放平台通过 SPI(回调)或Webhook消息推送至开发者 |
业务请求参数
业务请求参数是调用具体某个接口时需要的和业务相关的参数,通常不同的接口有不同的业务参数。需要参考具体接口定义文档进行设置。
假如一个POST请求的接口参数定义了两个业务参数:id和name,传参信息如下:
{ "id":81786433290919, "name":"hello" }
响应参数说明
OpenAPI请求响应结果通用参数中(除具体的业务数据外),若具体接口文档中无特殊说明则都遵循以下规则:
- 1.返回体中有data, extra, base_resp字段,其中base_resp三方可忽略,data用于传输数据,extra用于携带附属信息; data.error_code和extra.error_code值相同,可任取其一用于状态判断
- 2.error_code为0,表示请求成功; error_code为非0状态时,表示请求失败,可结合description查看失败原因, 失败时抖音侧可能不会返回业务字段
- 3.部分接 口业务字段中可能会有业务状态码, 判断顺序:HTTP请求状态码>$.data.error_code>业务状态码(如有,参考接口返回参数中定义的$.data下的业务错误码信息)
响应参数中,公共参数字段说明:
参数 | 类型 | 描述 |
data | Struct | 业务数据 |
error_code | Int32 | 错误码,0为成功,非0代表有错误 |
description | String | 错误信息描述 |
extra | Struct | 扩展信息 |
error_code | Int32 | 错误码 |
description | String | 错误码描述 |
sub_error_code | Int32 | 子错误码 |
sub_description | String | 子错误码描述 |
now | Int64 | 调用时间,毫秒级时间戳 |
logid | String | 抖音日志 id,可用于排查问题 |
加密字段解密方法
响应返回的业务数据中,针对加密字段进行解密方法参考文档:
注意
接口开发时,请认真阅读具体接口的文档说明,了解文档中的接口说明、使用限制、基本信息,开发严格按照请求参数、响应参数说明,排查问题可参考文档中的错误码等信息。
4.响应示例
成功响应格式
{ "data": { "poi_list": [ { "longitude": 0.723053656112516, "latitude": 0.079472136560064, "poi_id": 4418348657269527600, "poi_name": "psoUkR6AFX", "address": "6E1M7JT6TG" } ], "error_code": 0, "description": "" }, "extra": { "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "", "logid": "202412112134332BEA1F1E7DB8F93AE378", "now": 1733924073 } }
异常响应格式
{ "data": { "error_code": 2100004, "description": "系统繁忙,此时请开发者稍候再试" }, "extra": { "logid": "20220616135636010225243100059D654D", "now": 1655358997504, "error_code": 2100004, "description": "系统繁忙,此时请开发者稍候再试", "sub_error_code": 0, "sub_description": "unknown error, please retry" } }
5.错误码定义
错误码定义请点击查看:平台返回通用错误码,更多错误码说明需见具体OpenAPI接口文档说明
6.cURL请求示例
POST请求
curl --location 'https://open.douyin.com/goodlife/v1/hermes/delivery/delivery_info/save/' \ --header 'access-token: clt.cb1fc0cf41e3963a8e3a338f576f5064OE3adziUns57Lxs8NYXwYTY****' \ --header 'Content-Type: application/json' \ --data '{ "poi_id": 7281257194203383, "delivery_info": { "effective_scope_type": 1 } }'
GET请求
curl --location 'https://open.douyin.com/goodlife/v1/x_goods/dish/online/get/?product_ids=[8178750709248]&dish_type=14&account_id=111' \ --header 'access-token: clt.cb1fc0cf41e3963a8e3a338f576f5064OE3adziUns57Lxs8NYXwYTY****' \ --header 'Content-Type: application/json'
7.限流
限流说明
所有接口还受到通用限流策略约束,以防止恶意攻击和系统过载。
- •QPS 限制:当您在短时间内请求过于频繁,超过了平台设定的阈值,会收到
请求太过频繁,请稍后再试 错误。- •智能计数:对于解密类接口,网关有一项优化策略:同一密文在一小时内被多次请求解密,只会被计入限流值一次。这意味着,如果您因为业务逻辑问题重复解密少量相同密文,对限流的影响会较小。但请注意,这并不改变配额的消耗规则。
- •退避重试:当收到 请求太过频繁 错误时,请不要立即重试。建议采用指数退避策略(Exponential Backoff),例如,等待 1s, 2s, 4s, ... 后再重试,并设置最大重试次数,避免加剧系统拥堵。
限流值查看
路径:抖音开放平台/服务商平台->控制台->生活服务商家应用->开发配置-接口限流
注:只能看到应用开通权限的接口情况(根据接口类型进行区分)
若不满足业务场景,需要调整限流值,可联系抖音技术
8.接口在线调试
抖音开放平台为开发者提供了在线调试接口的能力。开发者可以在调试台内,通过工具提供的接口请求和返回数据服务,可以在线测试各种接口请求参数和返回结果的情况。按照指示输入相应的正确参数,即可快速获取该接口成功调用后的调用结果。
支持的调试功能包括:
- 1.输入API的入参以验证接口调用结果,同时可查看接口响应结果的具体表现
- 2.调试台内支持自动获取授权凭证,按照接口文档要求,完善Header(请求头)和入参(请求体),以验证接口调用结果,同时可查看接口响应结果的具体表现。
- 3.对于需要多个OpenAPI按照先后顺序串行调用的场景,调试台支持“链式调用”,开发者可以将多个API加入到调试链中串行执行。
使用路径
开发者可以在OpenAPI对应的接口文档右上角,点击按钮“在线调试”进入调试台
同时可以查看代码示例和权限情况:
如需使用“链式调用”等更多模块,可点击按钮“体验完整功能”
操作手册
了解更多操作细节,可参考文档:OpenAPI调试台
9.接口中通用名词说明
这里给出开放接口文档中,常见通用的名词解释说明:名词解释
10.常见问题
问题 | 建议方案 |
access-token无效、access_token过期 | 请参考如下步骤排查access-token无效的原因
|
调用接口报错:操作无权限/应用未获商家授权/商户未授权给应用 |
|
调用接口报错:服务器打瞌睡了,请稍后再试/服务器错误,请稍后重试/您的访问过于频繁,请稍后重试 | 类似带有建议重试的错误文案,建议以如下重试策略进行重试,接口成功返回后即可停止重试:
|
沙箱环境的OpenApi请求地址和生产环境是同一个吗 | 测试账号和正式环境线上都是同一个地址 |
