发券

我的收藏

抖音侧向商家/服务商发起券码申请，务必做到接口幂等，因为会存在网络等原因或出现超时，抖音会重试发券。

使用限制

无

接口 SLA

请求服务商接口，每个服务商各不相同

接口说明

1、发码中，必须十分钟内通过发码回调接口回调抖音侧告知发码结果，否则第10分钟抖音侧会自动发码失败，发起退款，会走服务商退款审核，此时服务商可以通过退款拒绝做补码操作。

2、发码成功，则必须在响应中直接返回正确的码 (后面不需要要求回调)。

3、发码失败，则抖音侧会发起退款申请，不走服务商退款审核，即服务商明确返回发码失败，不通过退款审核，无法做补码，直接退款给用户

（1）接口请求成功时务必确保 error_code=0, 发放券码的结果通过 data.result 字段返回。

（2）若 error_code 不为 0，不处理 data 中的数据，抖音会十分钟内多次重试发券请求。

4、金额说明：

（1）商家实收（抽佣前）=原始金额-商家营销金额；

（2）商家实收（抽佣后）此接口不提供；

（3）平台营销金额：平台补贴的金额；

（4）支付优惠金额：使用平台支付优惠的平台补贴金额。

5、SPI 响应超时时间为 8s，超过 8s 则为无效响应。

6、抖音侧重试间隔10s、30s 、60s 、120s、120s 、240s，最多重试6次

基本信息

HTTP URL	地址由服务商提供
HTTP Method	POST
申请权限	三方码发布
权限要求	•需要申请权限，路径：抖音开放平台-开发者平台/服务商平台>控制台>应用详情>解决方案 •需要url配置，路径：见下方“服务商/商家侧SPI接口配置” •需要商家授权，路径：抖音来客>店铺管理>服务应用授权

服务商/商家侧 SPI 接口配置

配置路径：开放平台-服务商平台/开发者平台-控制台-应用详情页-开发设置-SPI 回调

需配置接口：

接口	介绍(服务商配置url时可见)	需提供信息	是否必填
预下单	抖音请求三方系统预下单	回调地址：预下单URL	必填
发券	抖音请求三方系统发码	回调地址：发券URL	必填
退款	抖音请求三方系统退款审核	回调地址：退款URL	必填
信息同步	抖音向三方系统同步退款信息	回调地址：信息同步URL	必填

签名规则

签名规则参考查看这个地址的说明

请求参数

Body 请求

参数名称	参数类型	参数描述	是否必填
order_id	string	抖音侧的订单号	是
third_order_id	string	第三方侧的订单号，如果预下单成功且回传，则会在接口中给出	否
count	int	发码数量	是
start_time	int	有效期开始时间，时间戳，秒	是
expire_time	int	有效期截止时间，时间戳，秒	是
sku	object	商品信息	是
.sku_name	string	抖音商品名	是
.sku_id	string	抖音的商品ID	是
.third_sku_id	string	三方服务商侧的商品ID	是
.groupon_type	int32	商品类型 0:未知 1:团购 2:代金券 3:次卡 4:储值卡 5:周期卡 6:预约品 7:提货券 8:惠享卡	是
.voucher_type	int32	代金券类型（1=未知;1=复合代金券; 2=动态代金券;3=意向品）仅限餐饮、综合业务使用	否
.time_card	object	次卡信息	否
..times_count	int32	次卡总次数	否
open_id	string	下单人在抖音本地生活的openid	是
amount	struct	金额信息	否
.list_price	int	划线价格，单位分	否
.original_amount	int	原始金额,单位分	否
.pay_amount	int	用户实付金额,单位分	否
.ticket_amount	int	平台营销金额,单位分	否
.merchant_ticket_amount	int	商家营销金额,单位分	否
.merchant_ticket_amount_details	list(object)	商家营销金额明细	否
..funder_type	int	商家营销金额明细出资类型，1=货款出资，2=商家钱包	否
..amount	int	商家营销金额明细金额,单位分	否
.fee_amount	int	支付手续费，单位分（已下线）	否
.commission_amount	int	达人分佣金额，单位分（已下线）	否
.payment_discount_amount	int	支付优惠金额，单位分	否
.coupon_pay_amount	int	券实付金额（=用户实付金额+支付优惠金额），单位分	否
ticket_rule	object	票务规则	否
.code_sending_info	list(int)	凭证发放方式，多选1=身份 2=券号 3=券码 6=链接URL	是
.code_type	int	券码类型；2=三方码	是
.url_type	int	外部链接内容，code_sending_info包含6；1=静态二维码 2=其他
tourists	list(object)	出行人信息	否
.name	string	姓名 2024年2月29日起，若用户下单商品不属于下列一级商品类目（住宿(8000000), 游玩(18000000), 度假旅游服务(32000000), 交通出行(31000000)），该字段脱敏	否
.phone	string	联系电话 2024年2月29日起，若用户下单商品不属于下列一级商品类目（住宿(8000000), 游玩(18000000), 度假旅游服务(32000000), 交通出行(31000000)），该字段脱敏	否
.id_card	string	身份证号码 2024年2月29日起，若用户下单商品不属于下列一级商品类目（住宿(8000000), 游玩(18000000), 度假旅游服务(32000000), 交通出行(31000000)），该字段脱敏	否
.credential_type	int32	身份证件类型（1=身份证; 2=港澳通行证; 3=台湾通行证; 4=回乡证; 5=台胞证; 6=护照）	否
combination	list	券组套信息	否（组合券包必填）
.combination_id	string	组套id，代表x个子品组成一个主品	否（组合券包必填）
.certificates	list<object>		否（组合券包必填）
..certificate_id	string	抖音内部券ID，用于回调映射 = 履约内部的execute_id	否（组合券包必填）
..sku_id	string	券维度sku_id (代表子商品ID)	否（组合券包必填）
..third_sku_id	string	券维度三方服务商侧的商品ID (代表子商品ID)	否（组合券包必填）

请求示例

URL 参数示例: https://api.example.com/namek/fulfilment/create/?client_key={你的 clientKey}×tamp=1630393201049&sign={计算出来的签名}

{
    "order_id": "12345678",
    "third_order_id": "8767383",
    "count": 2,
    "sku": {
        "sku_id": "23456",
        "sku_name": "手机xxx",
        "third_sku_id": "345678",
        "groupon_type": 1,
        "voucher_type": 1
    },
    "amount": {
        "original_amount": 10000,
        "pay_amount": 8000,
        "ticket_amount": 1000,
        "merchant_ticket_amount": 1000,
        "payment_discount_amount": 1000,
        "coupon_pay_amount": 1000
    },
    "tourists": [
        {
            "name": "张三",
            "phone": "13800000000",
            "id_card": "310115199807013370",
            "credential_type": 1
        },
        {
            "name": "李四",
            "phone": "13900000000",
            "id_card": "310115199912130020",
            "credential_type": 1
        }
    ],
    "start_time": 1664553600,
    "expire_time": 1665158399,
    "combination": [
        {
            "combination_id": "com1",
            "certificates": [
                {
                    "certificate_id": "a111",
                    "sku_id": "a333",
                    "third_sku_id": "a444"

                },
                {
                    "certificate_id": "b111",
                    "sku_id": "b333",
                    "third_sku_id": "c222"

                }
            ]
        }
    ]
}

响应参数

团购三方码响应参数

字段名称	字段类型	字段描述	必须
data	object		是
.error_code	int64	接口错误码	是
.description	string	接口错误描述	是
.result	int	发码结果. 0:发码中,1:成功,2:失败	是
.codes	list	三方码列表	否，result返回1必填次卡场景下，不允许多item使用同一个券码Code
.fail_reason	string	失败原因	否
.certificates	list	券 result=1必须返回，根据请求certificates返回所有对应的凭证code	是
..certificate_id	string	抖音内部券ID	是
..code	string	服务商侧券码	是

响应示例

•

发码中

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 0
  }
}

•

发码成功

{
    "data": {
        "error_code": 0,
        "description": "success",
        "result": 1,
        "certificates": [
            {

                "certificate_id": "a111",
                "code": "a"
            },
            {

                "certificate_id": "b111",
                "code": "b"
            }
        ]
    }
}

景区预售券响应参数

字段名称	字段类型	字段描述	必需
data	object
.error_code	int64	接口错误码	是
.description	string	接口错误描述	是
.result	int	发码结果. 0:发码中 1:成功 2:失败	是
.fail_reason	string	失败原因	否
.voucher	struct	凭证	否
..entrance	struct	景区的入园项目（若入园凭证是单独的凭证，则使用此字段用来传入园凭证。若不是单独的凭证，可使用自定义项目的字段传入）	否
...project_id	string	入园项目的唯一标识,与projects中不能重复（核销时需要）	是
...id_cards	list<string>	身份证号码，最多限100个	否
...qrcodes	list<string>	二维码凭证，可以是一串数字，也可以是一个 URL，最多限 100 个。每个 URL 长度不能超过 512。	否
...credentials	list<object>	身份凭证列表，最多限100个	否
....credential_no	string	证件号	否
....credential_type	int32	证件类型（1=身份证; 2=港澳通行证; 3=台湾通行证; 4=回乡证; 5=台胞证; 6=护照）	否
...urls	list<string>	url电子凭证，最多限100个。每个URL长度不能超过512。	否
...certificate_nos	list<string>	券号凭证，最多限100个	否
..projects	list<object>	可自定义的项目（例：景区项目索道A、索道B等）	否
...project_id	string	项目唯一标识,不能重复（核销时需要）	是
...name	string	自定义的项目名称（例：景区XXXX索道）	是
...id_cards	list<string>	身份证号码，最多限100个	否
...qrcodes	list<string>	二维码凭证，可以是一串数字，也可以是一个URL，最多限100个	否
...certificate_nos	list<string>	券号凭证，在C端展示为数字串，最多限100个	否
...urls	list<string>	url电子凭证，最多限100个。每个URL长度不能超过512。	否
...credentials	list<object>	身份凭证列表，最多限100个	否
....credential_no	string	证件号	否
....credential_type	int32	证件类型（1=身份证; 2=港澳通行证; 3=台湾通行证; 4=回乡证; 5=台胞证; 6=护照）	否

发码结果

•

发码中，则必须十分钟内通过凭证回调接口回调抖音侧告知结果，否则会自动取消预约

•

发码成功，则必须在响应中直接返回正确的凭证 (后面不需要回调)

•

发码失败，则抖音侧会预约失败，用户可以再次发起预约

•

接口请求成功时务必确保 error_code=0, 发放券码的结果通过 data.result 字段返回。

•

若 error_code 不为 0，不处理 data 中的数据，抖音会十分钟内多次重试发券请求。

凭证

•

entrance和projects不能同时都为空

•

id_cards、qrcodes、certificate_nos不能同时都为空

•

id_cards、qrcodes、certificate_nos返回的各自集合长度不能超过请求的count

•

如果请求带了tourists，则返回的id_cards集合身份证信息必须包含在tourists中

响应示例

发码中

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 0
  }
}

发码成功

{
  "data": {
    "error_code": 0,
    "description": "success",
    "result": 1,
    "voucher": {
      "entrance": {
        "project_id": "1",
        "id_cards": ["310115199807013370", "310115199912130020"],
        "qrcords": ["qr_code1_096700560962", "qr_code1_806011925184"],
        "certificate_nos": ["a_096700560962", "a_806011925184"]
      },
      "projects": [
        {
          "name": "xx景区A项目",
          "project_id": "2",
          "id_cards": ["310115199807013370", "310115199912130020"],
          "qrcodes": ["qr_code2_806011925184", "qr_code2_534318095199"],
          "certificate_nos": ["b_806011925184", "b_534318095199"]
        }
      ]
    }
  }
}