三方码能力
收藏接口更新日志
更新日期 | 更新说明 |
2022年6月1日 | 创建文档 |
2022年6月24日 | 补充接口描述说明 |
2022年11月12日 | 新增次卡核销能力：三方码次卡对接时调用接口不变，各接口针对次卡做了适配调整点。
|
2022年11月20日 | 1、新增预下单接口：优先级高于下单确认。 2、发券接口新增字段：
3、发券回调接口支持回调失败的场景，即异步发券可以返回发券失败。
|
2023年5月26日 | 除景区外，三方码申请入口下线，仅建联商家可适用三方码能力。 |
2023年9月21日 | |
2024年1月16日 | 更新三方码必接接口规范说明以及压测验收流程。 |
业务场景
1、主要针对有自己券码体系的商家或者服务商，用户在抖音下单，然后发商家的券码。
2、三方码目前暂不开放，仅支持景区业务支持进行申请。
3、三方码次卡对接说明：
（1）创建商品时，商品类型选择次卡，其余配置与三方码团购券一致。
（2）三方码次卡对接时调用接口不变，各接口针对次卡做了适配调整点：
接口 | 调整说明 |
验券接口 | 支持次卡商品一次核销请求核销多份，多次卡商品，可以一次请求只核销一份，如果需要一次核销多份，list中传多个相同encrypted_codes |
撤销核销接口 | 支持次卡商品按次数撤销核销，增加times_card_cancel_count和 cancel_token |
退款接口 | 增加次卡商品总次数（.total_count）、已核销次数（.verify_count） |
信息同步接口 | 增加次卡商品总次数（.total_count）、已核销次数（.verify_count） |
接入前期准备
根据以下文档完成开发者账号开通认证、生活服务应用的创建、申请解决方案和接口权限。
需要申请的能力
三方码发布、门店管理、团购核销、团购对账
业务流程
对接接口
接口 | 接口路径 | 调用方 | 是否必接 | 接口说明 |
预下单接口 | 回调场景(配置SPI回调地址时可见)：抖音请求三方系统预下单 | 抖音 | 是 | 用户支付前向第三方预下单，服务商需要告知抖音是否可以下单，可下单需要回传第三方订单号。 |
发券接口 | 回调场景(配置SPI回调地址时可见)：抖音请求三方系统发码 | 抖音 | 是 | 抖音侧向商家/服务商发起券码申请，务必做到接口幂等，必须具有补码能力。 |
发券回调接口 | 商家 | 否 | （非必需）抖音侧先申请服务商发码，如果能同步返回结果则不需要本接口，如果异步返回结果则调用本接口通知抖音 | |
验券接口 | 商家 | 是 | 同时适用于抖音券码与三方券码，抖音券码的核销需要先调用准备接口，再调用本接口，三方券码的核销直接调用本接口即可。 | |
撤销核销接口 | 商家 | 综合、餐饮必接，景区可选择性接入。 | 误核销之后的撤销操作，有时间限制，验券超过一个小时就不可再撤销。 | |
退款接口 | 回调场景(配置SPI回调地址时可见)：抖音请求三方系统退款审核 | 抖音 | 是 | 抖音侧向服务商发起退款的申请，务必做到接口幂等。 |
审核回调接口 | 商家 | 否 | （非必需）退款申请后，商家/服务商统一退款或拒绝退款的回调通知，若在退款申请时能明确给出结果则不需要再回调。 | |
信息同步接口 | 回调场景(配置SPI回调地址时可见)：抖音向三方系统同步退款信息 | 抖音 | 是 | 商家在抖音APP进行退款审核操作或者退款被自动审核(24小时超时, 运营强制退等)时，动作并非由服务商发起，如果服务商系统需要感知这部分信息，可实现该接口，抖音侧会同步审核信息 |
订单状态查询接口 | 抖音 | 是 | 抖音生活服务侧主动查询服务商侧订单状态信息并进行订单状态更新，确认两边数据状态一致。 |
对接前注意事项
服务商/商家侧接口配置
配置路径：开放平台-服务商平台/开发者平台-控制台-应用详情页-开发设置-SPI 回调
公共信息
公共请求头：
每个接口都需要，不再每个接口中再单独提及。
参数 | 描述 | 必须 |
Content-Type | application/json | 是 |
调用路径为服务商 调用 抖音的接口，会传递该请求头。
参数 | 描述 | 必须 |
access-token | 是 | |
log_id | 抖音侧的问题排查标示 | 是 |
签名规则
平台验收注意事项
- 1.平台关注以上表格必接接口是否接入，如未接必接接口，则无法验收通过。
- 2.平台验收接入服务商/自营商家性能情况，以防止流量太大导致接口崩溃等问题，最低准入门槛：50，需提供接口压测报告或直接和平台进行压测。
- 3.接口异常case：例如三方码发码补码、退款等也将纳入验收流程，如不符合则验收无法通过。
- 4.验收后，服务商/自营商家需了解平台关于三方码相关应急预案处理机制，以减少后续事故处理造成的体验问题。
FAQ
是否可以支持部分退？
一笔订单购买多张券时，未核销的券可以进行退款
一张券是否可以验证多次？
不可以
一笔订单，最多可以购买几张券
10 张
一笔订单，是否有多个团购商品
一笔订单只有 1 个团购商品，可以购买多份（多张券）
核销后支持撤销核销吗？
支持，1 小时内可以撤销核销，超过 1 小时无法发起撤销核销
核销后支持退款吗？
不支持
用户退款后多久到账
用户发起退款，需要在商家后台券退款管理进行操作退款，如不操作，默认 24 小时退款
错误码
调用关系为服务商调用抖开的接口，有以下平台错误码可以用。
注：除了 0 为成功其它均为失败。
错误码 | 错误消息 |
2190002 | access_token 无效 |
2190003 | 用户未授权该 API |
2190004 | |
2190008 | access_token过期,请刷新或重新授权 |
2119001 | 参数不合法 |
2119002 | 系统繁忙，请稍候再试 |
2119003 | 请求太过频繁，请稍后再试 |
2119004 | client-info 不合法 |
2119005 | 应用未获商家授权 |
