发券
收藏接口说明
三方码发券SPI,抖音通知三方发码，如果为同步发码则返回三方码，异步发码则根据发码通知的凭证单的映射关系异步发放三方码
抖音侧服务商接单成功后向服务商发起发放凭证申请。
业务说明：
- 1.发码成功，则必须在响应中直接返回正确的码 (后面不需要要求回调)。
- 2.发码失败[result=2]，则抖音侧会发起退款申请，不会调用退款审核接口；即服务商侧明确返回发码失败，不会调用退款审核，如服务商无法补码，抖音侧直接为用户退款
- a.接口请求成功时务必确保 error_code=0, 发放券码的结果通过 data.result 字段返回。
- b.若 error_code 不为 0，则不处理 data 中的数据，抖音侧会在十分钟内多次重试发券请求。
- 3.若在10min内请求不到服务商返回的码，抖音侧会自动退货并发起退款流程
- 4.同步发码返回明确失败的情况下，抖音侧会触发自动退款，该场景下不会发起退款申请
- 5.发码接口响应超时时间为 8s，超过 8s 则为无效响应
- 6.抖音侧重试间隔10s、30s 、60s 、120s、120s 、240s，最多重试6次
- 7.目前航司没有对接补码机制，未来在退款接口会增加补码能力
基本信息
研发同学填写
HTTP URL | 地址由服务商提供 |
HTTP Method | POST |
scope | life.capacity.tripartite.code |
权限要求 | 需要申请权限 ，路径：抖音开放平台-服务商平台>控制台>应用详情>解决方案需要url配置，路径：联系抖音对接技术人员，做配置需要商家授权，路径：抖音来客>店铺管理>第三方应用授权 |
请求方式
抖音侧向 开发者侧发起POST类型的请求
请求头
- •Content-Type：
application/json- •X-Bytedance-Logid: 请求logid， 用于问题排查用
- •x-life-clientkey: 服务商应用的client_key
- •x-life-sign: 请求签名，签名规则
请求参数
v1.0.1版本，请求参数没有留资信息，用于未来预留
参数名称 | 参数类型 | 参数描述 | 是否必填 | 是否加密 |
order_id | string | 抖音侧的订单号 | 是 | |
count | int | 团购券：发码数量（1份1码） | 是 | |
open_id | string | 下单人在抖音本地生活的openid | 否 | |
start_time | int | 有效期开始时间，时间戳，秒 | 是 | |
expire_time | int | 有效期截至时间，时间戳，秒 | 是 | |
sku | object | 商品信息 | 是 | |
.sku_name | string | 抖音商品名 | 是 | |
.sku_id | string | 抖音的商品ID | 是 | |
.third_sku_id | string | 三方服务商侧的商品ID | 是 | |
amount | object | 金额信息 | 否 | |
.original_amount | int | 原始金额,单位分 | 否 | |
.pay_amount | int | 用户实付金额,单位分 | 否 | |
.ticket_amount | int | 平台营销金额,单位分 | 否 | |
.merchant_ticket_amount | int | 商家营销金额,单位分 | 否 | |
.list_price | int | 划线价格，单位分 | 否 | |
.payment_discount_amount | int | 支付优惠金额，单位分，平台补贴的一种 | 否 | |
.coupon_pay_amount | int | 券实付金额（=用户实付金额+支付优惠金额），单位分 | 否 | |
tourists | list<object> | 出行人信息 | 否 | |
.phone | string | 手机号 | 否 | 否 |
| | | | |
金额说明
- 1.商家实收（抽佣前）=原始金额-商家营销金额；
- 2.商家实收（抽佣后）此接口不提供；
- 3.平台营销金额：平台补贴的金额；
- 4.支付优惠金额：使用平台支付优惠的平台补贴金额。
请求示例
一单一份
{ "order_id":"12345678", "count":1, "sku":{ "sku_name": "团购券", "sku_id":"23456", "third_sku_id":"345678" }, "amount":{ "original_amount":10000, "pay_amount":8000, "ticket_amount":1000, "merchant_ticket_amount":1000, "payment_discount_amount":1000, "coupon_pay_amount":1000 }, "tourists": [ { "phone": "13800001111" } ], "start_time":1664553600, "expire_time":1665158399 }
一单多份
{ "order_id":"12345678", "count":3, "sku":{ "sku_name": "团购券", "sku_id":"23456", "third_sku_id":"345678" }, "amount":{ "original_amount":10000, "pay_amount":8000, "ticket_amount":1000, "merchant_ticket_amount":1000, "payment_discount_amount":1000, "coupon_pay_amount":1000 }, "tourists": [ { "phone": "13800001111" } ], "start_time":1664553600, "expire_time":1665158399 }
响应参数
字段名称 | 字段类型 | 字段描述 | 是否必填 |
data | object | | |
.error_code | int64 | 接口错误码 | 是 |
.description | string | 接口错误描述 | 是 |
.result | int | 发码结果. 0:发码中 1:成功 2:失败 | 是 |
.fail_reason | string | 失败原因 | 否 |
.codes | list<string> | 三方码列表 | 否 |
发码结果
- •发码中，则必须十分钟内通过凭证回调接口回调抖音侧告知结果，否则会自动取消预约
- •发码成功，则必须在响应中直接返回正确的凭证 (后面不需要回调)
- •发码失败
- ◦接口请求成功时务必确保 error_code=0, 发放券码的结果通过 data.result 字段返回。
- ◦若 error_code 不为 0，不处理 data 中的数据，抖音会十分钟内多次重试发券请求。
回传失败排查：
响应示例
正常示例
- •发码中（需要对接异步链路）
{ "data": { "error_code": 0, "description": "success", "result": 0 } }
- •发码成功
- ◦1单1份单人机票 （即每份1个出行人）
{ "data": { "error_code": 0, "description": "success", "result": 1, "codes": ["a_096700560962"] } }
- ◦1单3份单人机票
{ "data": { "error_code": 0, "description": "success", "result": 1, "codes": ["a_096700560962"，"b_096700560962"，"c_096700560962"] } }
- •发码失败
{ "data": { "error_code": 0, "description": "发码失败", "result": 2, "fail_reason": "商品不存在" } }
