到综团购预约品解决方案
收藏变更记录
变更时间 | 变更内容 | 版本号 |
6.30 | 注意本文档内字段内容为初版，可能会有些许变更 | v0.9 |
7.30 | 正式版本 | v1.0 |
概念说明：
client_key: 三方通过接口对接抖音开放平台前需要创建应用， 应用的AppId等价于client_key，二者值相同，用于唯一区分一个应用
client_secret：等价于生活服务应用中的AppSecret, 搭配client_key可通过文档 - 抖音开放平台 - 服务商平台 (open-douyin.com)获取access_token
access_token: 接口调用的凭证，携带在请求header中用于身份识别
测试账号：为了方便三方与抖音侧进行联调测试， 三方可向抖音侧BD申请测试账号（包含服务商测试账号和对应的测试商家账号），测试账号的应用和权限申请抖音侧已经提前准备好，可直接投入开发测试使用
一、接入前期准备
测试账号申请
开发测试期间，使用抖音提供的沙箱账号进行测试，测试完成后，再使用商家正式账号
可按照商家所在地与产运对接人，联系抖音侧BD建飞书群对接提供沙箱账号，绑定商家手机号，即可用商家手机号以沙箱账号身份登录来客
沙箱账号无需再走入驻开平和申请授权流程，已绑定自研商家，可登录抖音来客，自带clientKey应用，secret，固定token，接口调用权限，
服务商入驻开平
| 开放平台地址 | 接入指南 |
KA自研商家 | ||
技术服务商 | |
服务商创建应用
创建第三方生活服务商家应用：
填写相关信息，创建应用。
应用创建成功后，可进入应用详情页查看ClientKey&ClientSecret
等待应用审核完成。审核时效 3 个工作日。
商家授权技术服务商 or 绑定自研服务商
若是技术服务商，需商家在抖音来客授权给技术服务商：
若是自研商家，需商家在商家自研服务里绑定开发者：
服务商/自研需要在开发者平台/服务商平台处理授权申请
开通应用的解决方案
在应用详情中，点击解决方案，选择【到综团购预约解决方案】申请开通。审核时效 3 个工作日。
生成 access_token
通过请求参数ClientKey&ClientSecret调用/oauth/client_token/生成的token，此token不需要用户授权。示例: clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
参考 client_token 接口：https://partner.open-douyin.com/docs/resource/zh-CN/dop/develop/openapi/account-permission/client-token，body 返回 access_token
注意：需每2小时更新（开发阶段给到的测试账号不同，按对应文档说明使用，参考步骤2）
商家回调地址配置
- •spi回调地址
系统已支持线上配置SPI，技术服务商可线上配置：
参考SPI 签名机制：https://partner.open-douyin.com/docs/resource/zh-CN/local-life/develop/OpenAPI/preparation/signruleintroduce（包含加密字段解密方法）
- •webhook
订阅webhook事件：https://developer.open-douyin.com/docs/resource/zh-CN/dop/develop/webhooks/update-event-subscription-status
webhook事件名暂时未出现在订阅事件列表里，上述接口调用成功即可
webhook格式见第四章第六节（商品审核结果通知）。 webhhook只需配置一个url，商家自行根据event事件名路由，以event对应的结构体反序列化相应内容。
如若商家配置失败，可联系抖音开发处理（需提供申请了加了权限后ck对应的token ）
目前已支持线上配置webhook，在开发设置中配置：
抖音SPI调用的验签case
参考文档： https://partner.open-douyin.com/docs/resource/zh-CN/local-life/develop/preparation/signruleintroduce
注：http_body值需要读取http请求原始字符串，切勿序列化后再反序列化，否则字段顺序可能会乱
原始字符串： 111111&client_key=sandbox113×tamp=1693991210709&http_body={"currency":"CNY","occupancies":[{"first_name":null,"last_name":null,"name":"2JhtVGPmblZr1LAI7NE/og==","phone":"","license_type":0,"license_id":""}],"hotel_id":"7216656839890208829","check_out_date":"2023-09-08","number_of_units":1,"number_of_guests":2,"daily_rates":[{"period_start_date":"2023-09-07","period_end_date":"2023-09-08","original_amount":10,"amount_before_tax":10,"currency":"CNY"}],"meals":[{"meal_type":1,"meal_num":1}],"biz_type":2021,"room_id":"7247049008404203560","rate_plan_id":"1776079051954195","check_in_date":"2023-09-07","total_amount":10} sha256值: f8337d76e78dd42cb4e22fe9ec24bee6a7798eac625bec46e50537228e16ae31
二、整体说明（必读）
时序图
1.1.1 商品管理
1.1.2 库存推送
1.1.3 库存定时周期拉取
1.1.4 库存触发拉取
1.1.4 交易流程
请求header内容
调用抖音侧API接口时，需要在header填充token信息用于鉴权；抖音侧提供的测试账号和三方自行申请的正式账号token填充方式有所不同，请注意区分！
若无特殊说明，以下header的内容适用下文所有API接口
测试账号
参数名称 | 参数类型 | 必须参数 | 备注 |
» access-token | string | 必填 | |
» 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.下文API接口返回示例出于精简考虑，仅给出了data中的业务字段，其他信息可参考以上说明
6.注意：SPI请求体中包含的可选字段在一些场景下可能不会返回需要商户兼容处理
7.注意：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
三、接口-商品直连
权限申请说明
开放平台管理后台找到【到综团购预约解决方案】，点击查看详情，根据接口所在的能力来勾选开通，能力名称参考下方接口列表的能力名称
接口列表
业务场景/能力名称 | 是否必接 | 接口 | 说明 |
商品预约类价量态操作 | | | |
| | ||
| | ||
综合预约订单确认接拒单 | | | |
综合预约订单查询 | | | |
商品预约类价量态操作 | | | |
综合预约订单创建 | 必接 | 抖音侧调用第三方进行预约单创单 | |
综合预约三方订单查询 | | 抖音侧调用第三方进行订单查询（用于平台和三方状态不一致时兜底处理，如三方未返回平台接单状态，那么平台会在超时拒单前进行一次订单查询，保障状态一致） | |
综合预约订单支付通知 | | 抖音侧调用第三方进行支付结果通知(如果是支付后创单则不需要接入本接口) | |
三方码发布 | | 抖音侧先申请服务商发码，如果能同步返回结果则不需要本接口，如果异步返回结果则调用本接口通知抖音。 | |
| 审核结果为拒绝时必须要告知抖音拒绝原因，若没有原因将会返回报错，拦截本次审核结果 2、「退款」接口中抖音的请求中 certificate_id 对应 code 为空，且最终服务商侧的审核结果为拒绝，必须在回调抖音时将 code 补上，否则将返回报错，拦截本次审核结果(具体参数见下方请求参数) 3、返回结果中 error_code 为 0 代表通知成功；其他值可当作通知失败，需做重试 4、若服务商未能在收到「退款」请求后 24 小时内成功告知抖音审核结果，那么本次请求将会被自动审核通过，完成后续的退款流程 | ||
| 抖音侧向商家/服务商发起券码申请，务必做到接口幂等，因为会存在网络等原因或出现超时，抖音会重试发券。 | ||
| 抖音侧向服务商发起退款的申请。 | ||
| 用于抖音侧向商家侧同步退款状态信息变更。 | ||
团购核销 | | 抖音团购券码的核销, 需要先调用本接口, 查询订单的券列表，选择要验的券，再调用验券接口，核销券码。 | |
| 用于核销券码，同时适用于抖音团购券码与三方券码，抖音券码的核销需要先调用准备接口，再调用本接口，三方券码的核销直接调用本接口即可。 | ||
| 针对“抖音团购券码、三方券码”两种券码误核销之后的撤销操作，订单状态由“已使用”回改为“待使用”，用于验券错误需要撤回验券等场景， 有时间限制，验券超过一个小时就不可再撤销。 extra.error_code、data.error_code 均为 0 代表撤销成功。 | ||
| 在核销的异常场景情况下，对抖音码团购、次卡券进行状态查询。 | ||
| 用于批量查询抖音券码和三方券码的状态 |
