开发者接口发券__抖音开放平台

接口说明

使用接口发券需注意：

为保证用户直播间体验，当券模板存在发放中的「主播发放计划」时，不允许通过「接口发券」向用户发券；
为避免打扰用户，「接口发券」只允许向7天内使用过小程序的用户进行发放；
接口QPS限制为100/appid。

使用限制

当前券模板状态为生效且库存充足，且已经通过创建开发者接口发券活动创建过接口发券活动。

基本信息

名称	描述
HTTP URL	https://open.douyin.com/api/promotion/v1/coupon/send_coupon_to_designated_user/
HTTP Method	POST
Scope	promotion.coupon.admin

请求头

名称	字段类型	是否必填	示例	描述
access-token	String	是	clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ	调用https://open.douyin.com/oauth/client_token/生成的token
content-type	String	是	application/json	固定值"application/json"

请求参数

Body

名称	字段类型	是否必填	示例	描述
activity_id	String	是	721807xxxxxx5644204	接口发券活动id，调用/api/promotion/v1/coupon/create_developer_activity/返回的activity_id字段获取
app_id	String	是	ttec789ac573xxxxxx01	小程序appid
open_id	String	是	ba253642-0590-40bc-xxx	用户在小程序的open_id。该字段通过 /api/apps/v2/jscode2session 接口返回的 openid 字段获取
merchant_coupon_id	String	否	uniq_coupon	接口发券幂等键，开发者自行生成，给单用户发放多张券时必传

请求示例

curl --location 'https://open.douyin.com/api/promotion/v1/coupon/send_coupon_to_designated_user/' \
--header 'access-token: clt.xxx' \
--header 'Content-Type: application/json' \
--data '{
    "app_id":"ttec789ac573xxxxxx01",
    "open_id":"ba253642-0590-40bc-xxx",
    "activity_id": "721807xxxxxx5644204",
    "merchant_coupon_id": "uniq_coupon"
}'

响应参数

Body

名称	字段类型	是否必填	示例	描述
data	Struct	是
err_msg	String	是	"access_token无效"	错误描述
err_no	Int32	是	28001003	错误码
log_id	String	是	"202405291440576E078D8757B9"	日志id

响应示例

正常响应示例

{
  "err_no": 0,
  "err_msg": "",
  "log_id": "20230602141441E708D3A77C64701C88EB",
  "data": {
    "coupon_info": {
      "coupon_id": "70924xxxx555366",
      "coupon_status": 10,
      "discount_amount": 1000,
      "discount_type": 2,
      "merchant_meta_no": "45ed-8f3d",
      "min_pay_amount": 2000,
      "valid_begin_time": 1685686441,
      "coupon_name": "奶茶立减10元券",
      "receive_time": 1685686482,
      "valid_end_time": 1685772841
    }
  }
}

异常响应示例

{
  "err_no": 29005012,
  "err_msg": "尝试过于频繁",
  "log_id": "20230602111931B8431F7C63978600E24C"
}

错误码

http状态码	错误码	错误码描述	排查建议
200	28001005	系统内部错误，请重试	请求重试，若依然无解请向平台提交反馈
200	28001003	access_token无效	重新请求生成access_token
200	28001008	access_token过期,请刷新或重新授权	重新请求生成access_token
200	28001006	网络调用错误，请重试	重试即可
200	28001007	参数不合法	根据错误信息检查请求参数是否填写正常

开发者接口发券在线调试

接口说明

使用限制

基本信息

请求头

请求参数

Body

请求示例

响应参数

Body

响应示例

正常响应示例

异常响应示例

错误码

开发者接口发券