接口说明

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

该接口供服务商将用户服务的外部订购数据导入服务市场平台侧。

业务场景

服务商使用接口导入订购数据时，根据服务规格的不同需要指定不同的请求参数：

如果服务规格是时间类型，需要在请求参数中指定用户购买的使用时长
如果是次数/条数类型，需要在请求参数中指定用户购买的有效使用次数/条数

在调用对外接口【查询用户的服务购买信息】时，返回的服务使用有效期/次数/条数信息为用户在平台侧购买的使用时长/有效次数/有效条数和服务商导入的订购数据的使用时长/有效次数/有效条数的叠加。示例：

用户 1 月 1 号在平台侧购买了服务 A 规格 1 的 10 天的使用时长，服务商导入的订购数据为用户在 1 月 5 号购买了服务 A 规格 1 的 5 天的使用时长，则累加后的有效期为 1 月 1 号到 1 月 16 号 23:59
用户 1 月 1 号在平台侧购买了服务 A 规格 1 的 10 天的使用时长，服务商导入的订购数据为用户在 2 月 1 号购买了服务 A 规格 1 的 5 天的使用时长，则累加后的有效期为 2 月 1 号到 2 月 6 号 23:59

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

使用限制

该接口仅适用于平台应用类服务
服务商只能对自己创建的服务进行操作
服务商在导入外部订购数据时，对应的服务和规格在平台侧必须已上线

基本信息

名称	描述
HTTP URL	https://open.douyin.com/market/service/user/insert/purchase/info/
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展开全部子属性

open_id必填String

示例：ba253642-0590-40bc-9bdf-9a1334b94059

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

out_trade_no必填String

示例：1

外部开发者单号id，用于唯一标识同一服务同一规格当前导入的订购数据和保证当前导入操作的幂等性，如服务商自己内部的订单号，最大长度为128

period_type必填Enum

示例：1

服务规格的周期类型，可选值：

1：时间类型
2：次数/条数类型

展开子属性

purchase_time必填Int64

示例：1651409686000

服务订购时间的毫秒级时间戳，系统将以此时间，开始叠加订购时长。purchase_time必须小于等于接口调用时间

service_id必填String

示例：7021602203591118688

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

service_mode_id必填String

示例：free

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

durationInt64

示例：1

订购时长值，适用于时间类型的服务规格，单位为天：

当duration大于0，表示用户在purchase_time时购买了对应天数的服务
当duration=-1时，表示用户购买的服务周期为永久

usage_timesInt64

示例：1

用户在服务商侧购买的服务有效使用次数/条数，适用于次数/条数类型的服务规格，usage_times必须大于0

请求示例
curl --location --request POST 'https://open.douyin.com/market/service/user/insert/purchase/info/' \
--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": "free",
    "out_trade_no": "1680613917339688",
    "purchase_time": 1657093625000,
    "period_type": 1,
    "duration": 1
}'

响应参数

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	参数不合法	检查请求参数

导入外部订购数据在线调试

接口说明

使用限制

基本信息

请求参数

响应参数

错误码

导入外部订购数据