酒店新预售券SAAS对接方案
收藏概念说明：
client_key: 三方通过接口对接抖音开放平台前需要创建应用， 应用的AppId等价于client_key，二者值相同，用于唯一区分一个应用
client_secret：等价于生活服务应用中的AppSecret, 搭配client_key可通过文档 - 抖音开放平台 - 服务商平台 (open-douyin.com)获取access_token
access_token: 接口调用的凭证，携带在请求header中用于身份识别
测试账号：为了方便三方与抖音侧进行联调测试， 三方可向抖音侧技术支持同学申请测试账号（包含测试商家账号和对应的开放平台应用），测试账号的应用和权限申请抖音侧已经提前准备好，可直接投入开发测试使用
一、接入前期准 备
服务商入驻开平
| 开放平台地址 | 接入指南 |
KA自研商家 | ||
技术服务商 | |
服务商创建应用
创建第三方生活服务商家应用：
填写相关信息，创建应用。
应用创建成功后，可进入应用详情页查看ClientKey&ClientSecret
等待应用审核完成。审核时效 3 个工作日。
商家授权技术服务商 or 绑定自研服务商
若是技术服务商，需商家在抖音来客授权给技术服务商：
若是自研商家，需商家在商家自研服务里绑定开发者：
服务商/自研需要在开发者平台/服务商平台处理授权申请
开通应用的解决方案【for 技术服务商】
在应用详情中，点击解决方案，选择对应的解决方案申请开通。审核时效 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，技术服务商可线上配置：
目前已支持线上配置webhook，在开发设置中配置：
二、整体说明（必读）
请求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请求结果，若无特殊说明则都遵循以下规则3.返回体中有data, extra, base_resp字段,其中base_resp三方可忽略，data用于传输数据，extra用于携带附属信息； data.error_code和extra.error_code值相同，可任取其一用于状态判断
4.error_code为0，表示请求成功； error_code为非0状态时，表示请求失败，可结合description查看失败原因， 失败时抖音侧可能不会返回业务字段
5.部分接口业务字段中可能会有业务状态码， 判断顺序：http请求状态码>error_code>业务状态码
6.下文API接口返回示例出于精简考虑，仅给出了data中的业务字段，其他信息可参考以上说明
- •成功示例
{ "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, }, }
三、接口清单
能力名称 | 是否必接 | 接口 | 说明 |
酒店静态信息匹配/创建/更新 | |
| |
| | 酒店静态信息匹配成功后通知服务商。 | |
| | 酒店匹配状态查询 | |
酒店静态信息自助获取 | | 抖音酒店查询（不适用于代理商） | |
物理房型静态信息匹配/创建/更新 | | 创建或更新抖音物理房型 | |
| | 物理房型审核通过/拒绝后通知服务商。 | |
| | 查询物理房型审核状态 | |
物理房型静态信息自助获取 | | 门店下物理房型查询 | |
物理房型上下架 | | 对物理房型进行上下架或者删除，单批次最多5个，单商家限制每秒最多操作40个房型 | |
房价/房态/房量更新 | | 保存价量态房量，该接口最多支持单次传递50组房量房态 | |
| | 保存价量态价格，该接口最多支持单次传递50组房价 | |
| | 商家侧日历库存或价格有变更触发接口商用 | |
主动拉取价量态 | | 抖音侧调用第三方主动拉取价量态信息。 | |
预售券线上开票 | | | |
住宿预售券交易正向 | | 抖音侧调用第三方进行可订检查。如果不可订需要返回价量信息进行价量更新 | |
| | 抖音侧调用第三方创建酒店预售订单。 | |
| | 抖音侧调用第三方创建酒店订单。 | |
| | 抖音侧通知第三方支付成功。供应商交易模式为支付后创单的情况下抖音不会调用该spi | |
| | 抖音侧通知第三方支付成功后，第三方需要在商品上单中设置的接单时间内通知抖音侧接单结果。超时会拒单 | |
住宿预售券交易逆向 | | 抖音侧通知第三方取消订单。 | |
| | 抖音侧请求第三方申请退款后，第三方异步回调审核结果。 | |
| | 抖音侧完成退款后，通知第三方实际退款结果。 | |
入住/离店状态同步 | | 三方通知调用用户的入住状态 | |
酒店会员管理 | | 更新酒店会员数据 | |
| | | |
| | | |
| | 抖音生活服务调用对接方绑定会员接口进行会员注册或者绑定。 如果该会员在对接方系统中尚未注册，则对接方需根据请求参数信息进行注册，并返回用户默认初始化信息。 如果该会员在对接方系统中已经是会员，则返回用户有效会员信息。 暂时无法在飞书文档外展示此内容 | |
| | 抖音生活服务调用对接方进行抖音渠道会员解绑。 | |
| | 抖音生活服务调用对接方进行会员数据查询 | |
| | 用户在抖音端内发起会员的换绑手机号，同步通知到商家侧。 | |
住宿预售券创建和更新 | | 保存或更新预售券预定商品信息，单次最多传入20个商品，即单商家每秒最多保存200个商品 | |
| | 保存或更新预售券信息 | |
| | 通知三方预售券审核结果 | |
酒旅商品上架和下架信息推送 | | 售卖房型上下架，售卖房型创建后自动上架，无需调用该接口。该接口最多支持单次传递20个商品id，单商家每秒最多保存200个商品。 | |
KA核销对账 | | 商家通过接口查询自己账单详情。 |
