发券
收藏我的收藏
收藏抖音侧向商家/服务商发起券码申请，务必做到接口幂等，因为会存在网络等原因或出现超时，抖音会重试发券。
使用限制
无
接口 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 | |||
申请权限 | 三方码发布 | |||
权限要求 |
| |||
服务商/商家侧 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 | 商品类型（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 | 商家营销金额,单位分 | 否 |
.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=护照） | 否 |
请求示例
{ "order_id": "12345678", "third_order_id": "8767383", "count": 2, "sku": { "sku_id": "23456", "sku_name": "手机xxx", "third_sku_id": "345678", "groupon_type": 1 }, "amount": { "original_amount": 10000, "pay_amount": 8000, "ticket_amount": 1000, "merchant_ticket_amount": 1000, "payment_discount_amount": 1000, "coupon_pay_amount": 1000 }, "contact": { "name": "张三", "phone": "13800000000" }, "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 }
响应参数
团购三方码响应参数
字段名称 | 字段类型 | 字段描述 | 必须 |
data | object | | 是 |
.error_code | int64 | 接口错误码 | 是 |
.description | string | 接口错误描述 | 是 |
.result | int | 发码结果. 0:发码中,1:成功,2:失败 | 是 |
.codes | list | 三方码列表 | 否，result返回1必填 次卡场景下，不允许多item使用同一个券码Code |
响应示例
{ "data": { "error_code": 0, "description": "success", "result": 1, "codes": ["abcd1234"] } }
景区预售券响应参数
字段名称 | 字段类型 | 字段描述 | 必需 |
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=护照） | 否 |
- 1.发码结果
- •发码中，则必须十分钟内通过凭证回调接口回调抖音侧告知结果，否则会自动取消预约
- •发码成功，则必须在响应中直接返回正确的凭证 (后面不需要回调)
- •发码失败，则抖音侧会预约失败，用户可用再次发起预约
- •接口请求成功时务必确保 error_code=0, 发放券码的结果通过 data.result 字段返回。
- •若 error_code 不为 0，不处理 data 中的数据，抖音会十分钟内多次重试发券请求。
- 2.凭证
- •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"] } ] } } }
