度假行业解决方案
收藏业务介绍
场景简介
预售券
预售券是支持用户“先买券，后预约使用”，方便用户囤货和商家卖货的一种商品类型
可参考以下商品类型差异：•日历产品：选择日期固定价格、固定使用用户后下订（需求推进中）
•团购券：用户购买后直接去商家核销使用，无需预约（旅行社行业暂不支持）
日历套餐
日历套餐：选择日期固定价格、明确使用用户后下订；当前仅支持酒景套餐类商品
可参考以下商品类型差异：•预售券：支持用户“先买券，后预约使用”，是方便用户囤货和商家卖货的一种商品类型
•团购券：用户购买后直接去商家核销使用，无需预约（旅行社行业暂不支持）
名词解释
client_key: 三方通过接口对接抖音开放平台前需要创建应用，该应用的 AppId 等价于 client_key，二者值相同，用于唯一区分一个应用
client_secret：等价于生活服务应用中的AppSecret, 搭配client_key可通过文档 - 抖音开放平台 - 服务商平台 (open-douyin.com)获取access_token
access_token: 接口调用的凭证，携带在请求header中用于身份识别
测试账号：为了方便三方与抖音侧进行联调测试，三 方可向抖音侧 BD 申请测试账号（包含服务商测试账号和对应的测试商家账号），抖音侧已经提前准备好测试账号的应用和权限，该账号可直接投入开发测试使用
接入前准备
测试账号申请
开发测试期间，使用抖音提供的沙箱账号进行测试，测试账号需绑定商家手机号，绑定后即可用商家手机号以沙箱账号身份登录抖音来客，测试完成后，再使用商家正式账号
沙箱账号申请流程：需要与所负责区域对齐api接入需求后，由BD建群邀请商家技术等相关人员进群后，与群内的TS同学对接申请。
沙箱账号已绑定自研商家，用户可使用该账号登录抖音来客，账号自带 clientKey 应用、secret、固定 token 及接口调用权限，无需再走入驻开放平台和申请授权流程
开通认证开发者账号
- •技术服务商：技术服务商接入指南
- •自研：自研商家接入指南
创建生活服务应用
参考文档：生活服务应用创建指南
创建第三方生活服务商家应用：
填写相关信息，创建应用。
应用创建成功后，可进入应用详情页查看ClientKey&ClientSecret
等待应用审核完成。审核时效 3 个工作日。
开通解决方案及能力
开通流程
2、在右上角点击「控制台」，在「我的应用」页面选择「生活服务商家应用」，然后点击目标应用。
3、在应用左侧导航栏点击「解决方案」，在「解决方案」页面「度假行业解决方案」的「操作」列点击「查看详情」。
4、在【度假行业解决方案】面板中选择所需的能力，点击「申请开通」，等待平台审核。审核通过后，即可使用相关能力。审核时效 3 个工作日。
特别说明：在申请度假解决方案时，不管是日历票还是预售券，都需一并申请右侧红框的能力。
否则商家在发布商品并选择对接直连系统时会搜索不到授权的开放平台应用
商家授权技术服务商 or 绑定自研服务商
若是技术服务商，商家需在抖音来客授权给技术服务商：
若是自研商家，商家需在商家自研服务中绑定开发者：
服务商/自研需要在开发者平台/服务商平台处理授权申请
开发指南
请求header内容
调用抖音侧 API 接口时，需要在 header 填充 token 信息用于鉴权；抖音侧提供的测试账号和三方自行申请的正式账号 token 填充方式有所不同，请注意区分。
若无特殊说明，以下 header 的内容适用于下文所有 API 接口
测试账号
参数名称 | 参数类型 | 必须参数 | 备注 |
» access-token | string | 必填 | 使用douyin.xxx或者ka.xxx前缀的token （申请测试账号时，由抖音侧提供） |
» Content-Type | 固定值 | 必填 | application/json |
» X-Sandbox-Token | 固定值 | 必填 | 1 |
正式账号
参数名称 | 参数类型 | 必须参数 | 备注 |
» access-token | string | 必填 | |
» Content-Type | 固定值 | 必填 | application/json |
API接口说明
本文档所有 api 请求结果，若无特殊说明都遵循以下规则1.返回体中有 data,extra,base_resp 字段。其中 base_resp 三方可忽略，data 用于传输数据，extra 用于携带附属信息；data.error_code 和 extra.error_code 值相同，可任取其一用于状态判断
2.error_code 为 0，表示请求成功；error_code 为非 0 时，表示请求失败，可结合 description 查看失败原因，失败时抖音侧可能不会返回业务字段
3.部分接口业务字段中可能会有业务状态码， 判断顺序：HTTP请求状态码>error_code>业务状态码
4.错误码说明详见：旅行社直连相关枚举& 常见错误码_抖音开放平台
5.下文API接口返回示例出于精简考虑，仅给出了data中的业务字段，其他信息可参考以上说明
6.加密字段解密参见：解密方法
7.注意：SPI 请求体中包含的可选字段在一些场景下可能不会返回，需要商户兼容处理
8.注意：SPI请求体中包含的字段在不存在的情况下可能会返回NULL值，需要商户处理好兼容逻辑
•spi 或 openapi 接口的 HTTP 方法均为 post
成功示例
{ "base_resp": { // 可忽略 "status_code": 0, "status_message": "success" }, "extra": { "error_code": 0, "description": "success", "sub_error_code": 0, "sub_description": "", "logid": "20230614120842393C34F06C7FBA04F355", "now": 1686715725 }, "data": { "业务字段1":"业务值1", "业务字段2":"业务值2", "error_code": 0, "description": "success" } }
失败示例
{ "base_resp": { //可忽略 "status_message": "时间范围不合法,格式为`2006-01-02`,且最大时间不能超过距今365天,起始时间不能超过结束时间,起始时间不能早于今天", "status_code": 299000044 }, "extra": { "error_code": 3000001, "description": "时间范围不合法,格式为`2006-01-02`,且最大时间不能超过距今365天,起始时间不能超过结束时间,起始时间不能早于今天", "sub_error_code": 0, "sub_description": "", "logid": "202306141347349C568D61A00C5319C55A", "now": 1686721655 }, "data": { "description": "时间范围不合法,格式为`2006-01-02`,且最大时间不能超过距今365天,起始时间不能超过结束时间,起始时间不能早于今天", "error_code": 3000001, }, }
spi返回值结构
返回字段需在 data 结构体内，必须按照下图格式返回（返回值需全部在 data 的属性 key 内）。可直接参考 spi 接口返回值样例
{ "data": { "error_code": 0, "description": "success", "XXXX":"XXXXX" } }
重试规则
- •重试次数：12次
- •重试间隔：5s
开发者自测、验收、上线流程
补充自测-验收-上线流程及验收文档抖音码验收文档：暂不需要验收如果有对接群，需在对接群内与抖音侧 TS 同学沟通验收流程，验收通过后方可上线有验收工具的话这里可以附验收工具操作 SOP ，手工验收的就附手工验收 SOP
业务对接流程
接口-交易链路
以下是一些强弱依赖的稳定性说明
抖音通知服务商创建订单，若三方系统没有创单成功，没有返回 out_order_id，抖音侧这笔订单还可以进行预约。由于服务商系统中没有这笔订单，用户发起预约后，商家确认接单时，服务商无法执行接单操作，这笔预约订单只有超时取消操作
兜底解法：
- ◦抖音系统会在创单失败后，连续重试大概15次（一直失败后无后续自动补偿机制）。服务商修复好后可告知抖音进行接口人工补偿
- ◦当服务商无法接单时，系统会根据商品上配置的接单时长计算最晚接单时间，到期后直接取消该预约单
创单和支付支持可选交易模式，需要对接时沟通支付后创单还是先创单再支付（预售默认支付后创单）。如果是支付前创单，需要以最终支付结果通知为准，创单时用户可能未支付完成。
支付后创单时，创单请求结构体内才会有支付信息，否则请监听支付通知
若需要支付前创单，请告知抖音侧技术支持同学，需针对沙箱账号或正式 clientKey 维度更改配置。（需走线上发布流程）
预售券
时序图
正向交易
逆向交易
接口清单
能力 | 是否必接 | 接口文档 | 描述 |
旅行社poi查询 | 必须对接 | 三方系统查询抖音创建的订单所关联商品的poi信息，内部自行匹配后在消费凭证中返回对应的poiid | |
酒旅旅行社-预售券价量态操作 | 选接 | 商家在来客后台创建商品成功后，通过接口调整预售券的价格库存信息 | |
选接 | 商家在来客后台创建商品成功后，通过接口调整预售券关联预约商品的价格库存信息 | ||
选接 | 商家在来客后台创建商品成功后，可以通过接口查询到商品基础信息、商品状态以及预售商品及可预约商品的价格库存信息 | ||
旅行社确认接口 | 必须对接 | 抖音侧通知第三方支付成功后，第三方需要在商品上单中设置的接单时间内通知抖音侧接单结果，超时会拒单。采用异步确认 | |
酒旅-旅行社支付结果通知 | 必须对接 | 抖音侧通知第三方支付成功。供应商交易模式为支付后创单的情况下抖音不会调用该 spi | |
酒旅-旅行社创建订单 | 必须对接 | 抖音侧调用第三方创建旅行社预约订单 | |
酒旅-旅行社订单取消通知 | 必须对接 | 用于预售订单/预约单取消时，抖音侧通知三方系统取消订单（SPI）。 | |
酒旅-旅行社退款结果通知 | 必须对接 | 订单退款时，抖音侧通知三方系统退款结果。当订单退款时，如果订单中没有第三方订单号，则无需通知三方系统。（SPI） | |
酒旅-旅行社创建预售订单 | 必须对接 | 创建预售券订单 SPI。 | |
酒旅预售券商品上架和下架信息推送 | 选接 | 商家在来客后台创建商品成功后，通过接口操作上下架状态变更。 | |
选接 | 商家在来客后台提交商品审核，或通过直连操作修改价格库存信息并审核通过时，抖音侧推送至商家（SPI） | ||
KA核销对账 | 选接 | 商家通过接口查询自己账单详情。 |
度假日历套餐
时序图
正向交易
逆向交易
接口清单
能力 | 是否必接 | 接口文档 | 描述 |
旅行社poi查询 | 必须对接 | 三方系统查询抖音创建的订单所关联商品的poi信息，内部自行匹配后在消费凭证中返回对应的poiid | |
旅行社日历品价量态操作 | 建议对接 | 商家在来客后台创建商品成功后，通过接口调整日历套餐的价格库存信息 最大日期范围不超过当天起360天（含） 价库实时生效，无需审核 | |
建议对接 | 商家在来客后台创建商品成功后，可以通过接口查询到商品基础信息、商品状态以及价格库存信息；查询范围 360 天内；仅返回可售日期+不可售日期且已设置价库的日期 | ||
建议对接 | 商家在来客后台创建商品成功后，通过接口调整日历套餐的价格库存信息 | ||
旅行社日历品操作 | 建议对接 |
| |
建议对接 | 商家在来客后台提交商品审核，或通过直连操作修改价格库存信息并审核通过时，抖音侧推送至商家 | ||
旅行社日历品行业交易商家接单 | 必须对接 | 抖音侧通知第三方支付成功后，第三方需要在商品上单中设置的接单时间内通知抖音侧接单结果，超时会拒单。采用异步确认。 | |
旅行社日历品行业交易可定检查 | 必须对接 | 用于可定检查。当且仅当明确告知可定检查失败时拒绝用户下单，其余情况默认放行 | |
旅行社日历品行业交易创建订单 | 必须对接 | 用户下单后，抖音侧调用第三方创建旅行社日历套餐订单 | |
旅行社日历品行业交易支付结果通知 | 非一步订单必须对接 | 抖音侧通知第三方支付成功。供应商交易模式为支付后创单的情况下抖音不会调用该 spi | |
旅行社日历品行业交易退款成功通知 | 必须对接 | 订单退款时，抖音侧通知三方系统退款结果。当订单退款时，如果订单中没有第三方订单号，则无需通知三方系统 | |
旅行社日历品-订单取消通知 | 必须对接 | 用于预售订单/预约单取消时，抖音侧通知三方系统取消订单 | |
KA核销对账 | | 商家通过接口查询自己账单详情。 |
