抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台

OpenAPI接口调用约定

收藏
我的收藏
OpenAPI 是指抖音侧提供 HTTP 接口,外部服务商/开发者发起调用,将数据传给抖音或者从抖音侧主动查询需要的数据。

1.OpenAPI请求协议说明

抖音开放接口仅支持https协议接入,指定Content-Type为:application/json,支持的有POST和GET方法。
调用流程:获取调用 access-token -> 组装参数,拼装 HTTP 请求 -> 发起 HTTP 请求 -> 获得 HTTP 响应 -> 解析结果
调用地址:抖音开放接口域名为 https://open.douyin.com
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 = ClientKey、AppSecret = ClientSecret)
    自研商家:登录抖音开放平台-->点击右上角控制台-->我的应用-->生活服务商商家应用-->点击对应应用-->基础信息(APPID = ClientKey、AppSecret = ClientSecret)
登录开发者控制台后查看应用信息,APPID 即 client_key
client_secret
应用唯一标识对应的密钥
7802f4e6f243e659d51135445fe******
登录开发者控制台后查看应用信息,AppSecret 即 client_secret
account_id
account_id 是本地生活商家账户 ID
商家:从 PC 抖音来客右上角或从抖音来客 App - 我 - 置顶个人信息获得
抖音来客 App 中获取位置如下所示
服务商:从控制台-应用详情页-授权管理获得已经授权的商家的“账户 ID”
access-token
接口调用凭证
参考文档OpenAPI凭证Client-token @孙文静,通过调用 https://open.douyin.com/oauth/client_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.响应示例

下面的示例代码以《查询订单商品快照的poi》对应的接口为例。

成功响应格式

{ "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无效的原因
    1.正式环境
    a.token最长有效期为2小时,请确认是否超过有效期,如超过有效期请重新获取
    b.请确认请求头信息是否填写正确,正确的是 Access-Token,错误的是下划线的 access_token
    c.请确认获取token时传入的ClientKey/appId,和商家授权的ClientKey/appId是否一致
    2.测试环境
    a.请确认请求头信息是否填写正确,header中x-sandbox-token的值是1,而不是x-sandbox-token=1
    b.如未解决,可联系抖音技术刷新下固定token
调用接口报错:操作无权限/应用未获商家授权/商户未授权给应用
    1.若为测试账号:测试账户不需要授权,默认就是已经授权的,如果仍报错请检查token所属授权商户与参数中相关信息是不是一致
    2.请确认来客账号绑定的应用是否有对应的接口能力,需要授权应用
    a.服务商应用授权路径:抖音开放平台>控制台>应用详情>授权管理
    b.商家授权路径:抖音来客>店铺管理>第三方应用授权
    3.商家授权的appID/client_key和获取token时传入的appID/client_key是否一致
    4.传参有门店、poi_id相关时
    a.确认门店是否被认领/匹配,是否传了和商户无关联的门店
    b.确认接口传入的poi_id和商品绑定的门店是否一致,门店是否为营业中
    5.业务场景相关
    a.如果是调用核销接口,门店认领了,但是对应的poild没有传或者门店停业/下线,也会提示应用没有授权
    b.如果是演出行业poi为虚拟poi,无法认领,目前的解决方案:核销时需要联系bd加白
    c.订单并不是本商户下面的,比如:肯德基的订单使用了华莱士的clientkey来核销;以及使用了未授权的clientkey调用接口(商品,订单,核销接口),注意⚠️:不要使用正式账号的clientkey来操作测试账号的数据
调用接口报错:服务器打瞌睡了,请稍后再试/服务器错误,请稍后重试/您的访问过于频繁,请稍后重试
类似带有建议重试的错误文案,建议以如下重试策略进行重试,接口成功返回后即可停止重试:
    1.前5次重试以5s间隔进行
    2.之后以40s间隔进行
    3.最高重试14次,如果接口依然报错,请进线抖音技术反馈
沙箱环境的OpenApi请求地址和生产环境是同一个吗
测试账号和正式环境线上都是同一个地址