接口说明

Scope: market.service.user 需要申请权限不需要用户授权

服务商可使用该接口与抖音开放平台同步用户的服务剩余使用次数/条数信息。

为了方便服务商对创建的服务进行测试，允许服务商在服务创建/修改界面中配置用户白名单。对于测试环境和 open_id 为白名单中的用户，使用下面的逻辑进行返回：

环境	是否为白名单用户	处理逻辑
测试环境（请求参数：is_test_env = true）	是	不实际扣除次数/条数，固定返回成功
测试环境（请求参数：is_test_env = true）	否	返回扣除失败
正式环境（请求参数：is_test_env = false）	是/否	根据用户实际剩余使用次数/条数返回是否扣减成功

注意事项：抖音的 OAuth API 以 https://open.douyin.com 开头

使用限制

该接口适用于服务周期为“按次服务”和“按条服务”的平台应用类服务
服务商只能传入自己创建的服务 id
请求参数中用于确保扣除操作幂等的 out_trade_no 对于同一个服务需要由接口调用方保证唯一
请求参数中用于确保扣除操作幂等的 out_trade_no 的有效期为一个月，使用 out_trade_no 进行次数扣减成功后，一个月内，使用相同 out_trade_no 调用扣除次数接口，保证幂等

基本信息

名称	描述
HTTP URL	https://open.douyin.com/market/service/user/remaintimes/decr/
HTTP Method	POST
Scope	market.service.user
权限要求	需要申请服务市场服务订购相关权限（scope：market.service.user），申请路径：抖音开放平台控制台 > 移动应用（或网站应用） > 应用详情 > 能力管理 > 特殊权限不需要用户授权

请求参数

请求头

access-token必填String

示例：clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ

调用https://open.douyin.com/oauth/client_token/生成的token

content-type必填String

示例：application/json

固定值"application/json"

Body

count必填Int32

示例：1

要扣除的次数/条数，要求大于0

is_test_env必填Bool

示例：true

是否为测试环境

true为测试环境，在服务未发布前或需要测试时使用测试环境参数
false为正式环境，需要传入的服务已发布

open_id必填String

示例：ba253642-0590-40bc-9bdf-9a1334******

查询订阅信息目标用户的唯一标识，通过/oauth/access_token/获取

out_trade_no必填String

示例：1680613917******

外部开发者单号id，用于保证当前扣除操作的幂等，由接口的调用方保证对于同一个服务唯一，最大长度为128

service_id必填String

示例：7021602203591******

服务id，服务的唯一标识，可在发布“平台应用类”功能中【应用配置页】和【服务详情页】中获取

service_mode_id必填String

示例：7094522041323******

服务规格id，由服务商在创建服务时指定，可在发布“平台应用类”功能中【应用配置页】和【服务详情页】获取

请求示例
curl --location --request POST 'https://open.douyin.com/market/service/user/remaintimes/decr/' \
--header 'access-token: clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1******' \
--header 'Content-Type: application/json' \
--data-raw '{
    "open_id": "ba253642-0590-40bc-9bdf-9a1334******",
    "service_id": "7021602203591******",
    "service_mode_id": "standard_1",
    "out_trade_no": "1680613917339688",
    "count": 1,
    "is_test_env": true
}'

响应参数

Body展开全部子属性

data必填Struct

展开子属性

extraStruct

展开子属性

响应示例
正常响应示例异常响应示例
{
  "data": {
    "error_code": 0,
    "description": ""
  },
  "extra": {
    "error_code": 0,
    "description": "",
    "sub_error_code": 0,
    "sub_description": "",
    "logid": "202008121419360101980821035705926A",
    "now": 1597213176393
  }
}

切换单列布局

错误码

HTTP 状态码	错误码	错误码描述	排查建议
200	2190008	access_token过期，请刷新或重新授权	参考生成 client_token 获取接口（https://developer.open-douyin.com/docs/resource/zh-CN/dop/develop/openapi/account-permission/client-token）调用的凭证 client_access_token
200	2190002	access_token无效	检查请求头的access-token参数
200	2100007	无权限操作	检查请求参数的service_id
200	2100004	系统繁忙，此时请开发者稍候再试	稍后重试
200	2100005	参数不合法	检查请求参数

开发者文档

扣除用户服务的剩余使用次数/条数

接口说明

使用限制

基本信息

请求参数

响应参数

错误码

扣除用户服务的剩余使用次数/条数在线调试

接口说明

使用限制

基本信息

请求参数

响应参数

错误码

扣除用户服务的剩余使用次数/条数