1. 关于抖音【酒店日历房】的业务简介

1.1 什么是酒店日历房？

抖音日历房是一种支持用户即时预订，满足用户有明确出行目的时预订酒店的诉求，同时可满足酒店商家收益管理诉求的新型商品类型。

1.2 酒店日历房重点功能

1.商户侧可根据酒店实际入住情况，进行实时动态更新信息，完成和抖音数据实时交互，满足收益管理需求。

2.用户侧无需先买券后预约，预订即明确入离日期，提高商家售卖后的转化率。

3.整体核销率高，保障商家资金安全，提高周转效率。

1.3 日历房、预售券、团购券能力对比

模块	功能点	直连日历房	直连预售券	团购券
商家入驻	注册账户 & 认领门店 &亮照 & 开通结算账户等	抖音来客	抖音来客	抖音来客
商品管理	有无预售券	无	接口 or 抖音来客（手工）	s
商品管理	商品类型	新增日历房商品类型	预订商品（预售券对应可以预约的商品）	无（线下沟通，线下预约）
商家经营	撮合 & 直播等	抖音来客	抖音来客	抖音来客
商家经营	营销产品能力	支持提报涡轮，秒杀，货补等功能	支持提报涡轮，秒杀，货补等功能	支持提报涡轮，秒杀，货补等功能
交易履约	用户预约	用户选择日期直接锁定库存	用户线上预约锁定库存	用户线下咨询，电话预约预约即核销
	商家接单	酒店在线直接接单	系统直连无需人工搬单	人工线下与用户沟通人工搬单至酒店系统
	核销	离店后T+1 0点核销	离店后T+1自动核销	预约即核销（通过二维码）
结算分账	分账提现（与账户账期相关，BD可代为申请+1/3/5)	核销日+账期日到账	核销日+账期日到账	核销日+账期日到账

1.4名称解释

名词	定义
client_key	三方通过接口对接抖音开放平台前需要创建应用，应用的AppId等价于client_key，二者值相同，用于唯一区分一个应用
client_secret	等价于生活服务应用中的AppSecret, 搭配client_key可通过文档 - 抖音开放平台 - 服务商平台 (open-douyin.com)获取access_token
access_token	接口调用的凭证，携带在请求header中用于身份识别
测试账号	为了方便三方与抖音侧进行联调测试，三方可向抖音侧BD申请测试账号（包含服务商测试账号和对应的测试商家账号），测试账号的应用和权限申请抖音侧已经提前准备好，可直接投入开发测试使用
POI	“Point of Interest”，即兴趣点，在地理信息系统中，任何一个有效的地理指标关联的有效地理信息，都是一个POI。它是生活服务主要的信息和功能的载体和入口。在抖音发布视频/图片，可以添加POI标签；用户在消费视频内容时，可以选择点击POI标签进入到POI详情页，具体了解POI的详细内容。在酒旅行业POI则可以认为是酒店门店
物理房型/MSPU/SPU	商家标品。在酒店行业用来描述商家的出售的房型信息，例如：房型名称、房型图片、床型、面积等。
商品/Product/售卖房型/售卖计划/RatePlan/RP	抖音生服售卖商品。与物理房型关联的同时包含一些规则(属性)和描述信息，比如预定规则、餐食规则、取消规则等。
价量态/房价房量房态/ARI	抖音商品的价格和库存管理表述。对应酒店行业即房价、房量、房态。
日历房	抖音生服商品的一种类型，只适用于酒店行业，满足用户即时预订的需求。
预售券	抖音生服商品的一种类型，适用于多行业，满足用户先购买后预约的需求。
预定商品	抖音生服商品的一种类型，适用于多行业，在酒店行业特指与预售券关联，用户购买预售券后可以预约的酒店售卖房型。
日历/Calendar	抖音生服描述商品价格、库存、属性的一种维度，即日历维度。用来表示在不同日期下，抖音商品不同的价格、库存、属性。
达人	本地行业的创作者，短视频和直播等内容的供给方，为商家提供分销渠道。
佣金计划	商家面向达人发布的一种任务，达人在接受任务后通过短视频或直播的方式帮助商家达成商品销售的目的，达人则会获取一定比例的佣金。目前佣金计划会与抖音商品进行关联。
通用计划	佣金计划的一种，特点：1.所有达人可接；2.商家达人不用建联
定向计划	佣金计划的一种，特点：1.指定达人可接；2.商家达人线下建联
佣金有效期	针对短视频定向计划，表示达人在上传带货短视频成功后，在指定的有效期时间范围内的可以计算佣金
计划维度	目前支持门店维度和商品维度。门店维度表示该门店维度下创建的商品都按照门店维度佣金计划计算佣金。商品维度则对指定商品设置佣金计划。

2.接入前准备

服务商入驻开平

	开放平台地址	接入指南
KA自研商家	https://developer.open-douyin.com/	https://partner.open-douyin.com/docs/resource/zh-CN/dop/ability/life-service-ability/life.capacity/ka.guide
技术服务商	https://partner.open-douyin.com/	https://partner.open-douyin.com/docs/resource/zh-CN/dop/ability/life-service-ability/life.capacity/guide/

服务商创建应用

参考文档 https://partner.open-douyin.com/docs/resource/zh-CN/dop/ability/life-service-ability/life.capacity/guide/

创建第三方生活服务商家应用：

填写相关信息，创建应用。

应用创建成功后，可进入应用详情页查看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，技术服务商可线上配置：

参考SPI 签名机制：https://partner.open-douyin.com/docs/resource/zh-CN/dop/develop/openapi/life-service-open-ability/life.capacity/beforeinsert/signruleintroduce

目前已支持线上配置webhook，在开发设置中配置：

参考webhook 消息推送：https://partner.open-douyin.com/docs/resource/zh-CN/dop/develop/openapi/life-service-open-ability/life.capacity/beforeinsert/massages.push

二、整体说明（必读）

域名说明

抖音日历房测试环境和正式环境不通过域名做区分，接口域名统一为： https://open.douyin.com

请求header内容

若无特殊说明，以下header的内容适用下文所有API接口

测试账号

参数名称	参数类型	必须参数	备注
» access-token	string	必填	使用douyin.xxx或者ka.xxx前缀的token （申请测试账号时，由抖音侧提供）
» Content-Type	固定值	必填	application/json
» X-Sandbox-Token	固定值	必填	1

正式账号

参数名称	参数类型	必须参数	备注
» access-token	string	必填	根据这个地址获取的token
» 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中的业务字段，其他信息可参考以上说明

•

成功示例

{
    "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,
    },
}

错误码说明

错误码段	错误类型	是否可重试
0	请求成功	无需重试
1000011	请求限流	降频重试（控制并发数）
3000001 - 3999999 其中3000001为抖音的默认错误码	业务错误	3000001可重试，其他的不建议重试
4000001 - 4999999	参数错误	不可重试
5000001 - 5999999	系统错误	可重试