生活服务商家应用 OpenAPI SDK 总览

OpenAPI

接入前准备

通用接口

餐饮

大交通

酒旅

会员通手机号格式说明&国家区号拆分能力

酒店通用错误码

酒店行业日历房解决方案

酒店日历房常见枚举值列表

酒店静态信息匹配/创建/更新能力

酒店静态信息自助获取能力

物理房型静态信息匹配/创建/更新

营销规则价格推送

物理房型上下架能力

主动拉取价量态

营销价量态拉取

营销规则推送

营销库存推送

日历房线上开票

日历房上下架能力

营销规则价格模式推送

营销查询

入住/离店状态同步能力

日历房交易正向

酒店会员管理

日历房交易逆向

售卖房型创建/更新能力

物理房型静态信息自助获取能力

房价/房态/房量更新

代理商-酒店静态信息自助获取

酒店账单详情查询

酒店行业新预售券解决方案

度假行业解决方案

景区行业日历票解决方案

景区团购（在线预约）

景区团购三方码方案

景区行业团购|在线预约解决方案

综合

历史版本文档（不推荐）

酒店日历房可订检查

我的收藏

接口说明

抖音侧调用第三方进行可订检查。如果不可订需要返回价量信息进行价量更新。

基本信息

Scope	life.capacity.trip_trade_order
权限要求	酒店日历房解决方案-日历房正向交易
回调场景	酒店日历房可订检查

请求头

•

Content-Type：application/json

•

X-Bytedance-Logid: 请求 logid，用于问题排查用。

•

x-life-clientkey: 服务商应用的 client_key。

•

X-life-sign: 请求签名，签名规则。

请求体

参数名称			参数类型	必须参数	备注
rate_plan_id			string	必填	抖音售卖房型ID
biz_type			int	必填	2011：酒店预售券 2012:酒店预约单 2021:日历房
check_in_date			string	必填	入住日期 yyyy-MM-dd
check_out_date			string	必填	离店日期 yyyy-MM-dd
daily_rates			list	选填	单日单间价格（加白后可支持多间夜场景下按间夜拆分）
	original_amount		int	必填	原始价格(分)，对于非中国大陆商家，代表税后价支持传0和-1，表示清除价格
	amount_before_tax		int	选填	税前价，非中国大陆商家使用
	currency		string	选填	发单价格币种，CNY，USD国际标准枚举值非国内大陆商家必填
	period_start_date		string	必填	时间段开始时间yyyy-MM-dd
	period_end_date		string	必填	时间段结束时间yyyy-MM-dd
	period_start_time		string	选填	开始时间点，新增选择钟点房时为必填，格式 yyyy-MM-dd hh:mm 钟点房第一次可订检查（提单）时无此时间，第二次可订检查（下单）时会传此时间为必填
	period_end_time		string	选填	结束时间点，新增选择钟点房时为必填，格式 yyyy-MM-dd hh:mm 钟点房第一次可订检查（提单）时无此时间，第二次可订检查（下单）时会传此时间为必填
	usage_duration		int	选填	使用时长选择钟点房时为必填。钟点房第一次可订检查（提单）时无此时间，第二次可订检查（下单）时会传此时间为必填校验逻辑： 1.时长校验：1-23 2.支持填写最小时间为1，取整数，例如：使用1小时，使用2小时
	promotion_info		list<object>	选填	营销信息
		promotion_type_code	string	选填	营销规则一级类型code (结构见公共结构营销活动typeCode)
		promotion_id	string	选填	抖音营销规则ID
		promotion_discount	int	选填	营销折扣金额（分）
		promotion_template_id	string	选填	营销模版ID
		promotion_name	string	选填	优惠名称
	after_promotion_amount		int	选填	促后价格
total_after_promotion_amount			int	选填	总房型促后价格（分）
meals			list	选填	餐食信息
	meal_type		Int	选填	餐食类型 1:早餐 4:无餐食
	meal_num		int	选填	餐食数量数量必须大于0，如果则不传
number_of_units			int	必填	预定间数
number_of_guests			int	必填	入住人数默认2可订时候还没具体入住人
total_amount			int	必填	总房型原始价格(分)，对于非中国大陆商家，代表税后价
amount_before_tax			int	选填	税前价，非中国大陆商家使用
currency			string	选填	发单价格币种，CNY，USD国际标准枚举值非国内大陆商家必填
occupancies			list<struct>	选填	入住人列表
	first_name		string	选填	姓
	last_name		string	选填	名
	name		string	必填	姓名
	phone		string	必填	联系电话，加密 (手机号可能为"")
	license_type		int	选填	1 -身份证 2-港澳通行证 3-台湾通行证 4-回乡证 5-台胞证 6-护照,7-外籍护照,8-外国人永久居留证,9-港澳台居民居住证,10-中华人民共和国旅行证
	license_id		string	选填	证件 ID，加密
	sex		int	选填	1:男，2：女
	birthday		string	选填	// 出生日期，格式 yyyy-MM-dd
	license_validity		string	选填	// 证件有效期，格式 yyyy-MM-dd，当证件类型不为身份证时，该字段必填
cancel_rule			list<object>	选填	取消规则
	cancel_type		enum	必填	取消订单规则 (结构见公共结构取消规则)
	cancel_time_type		enum	选填	若取消订单规则为限时取消，该字段表示取消订单需要参考的时间点，例如以入住时间为参考，判断用户是否可取消。目前只支持2，即只支持以入住时间为参考 (结构见公共结构取消时间计算规则)
	cancel_offset_time		object	选填	若取消订单规则为限时取消，该字段表示取消订单需要参考的时间时间长度，例如以入住时间为参考，长度6小时，则用户最晚可在入住前6小时取消。
		day	int	选填
		hour	int	选填	范围[0-24） (超过24应进位至day) •该字段表示以24点为基准往前偏移的小时数 •例如传入6，表示24点前6个小时，即18:00点
		minute	int	选填
	cut_type		enum	选填	取消扣费类型(结构见公共结构2.2.3)
	cut_value		int	选填	取消扣费数额。范围 [0,90]，即扣款百分比区间为 0%～90%
member_info			object	选填	会员信息
	member_level		int	必填	会员等级
	member_id		string	选填	会员卡号
	member_name		string	选填	会员姓名
	member_phone		string	选填	会员手机号（加密传输）
	member_email		string	选填	会员邮箱（加密传输）
open_id			string	选填	抖音用户ID
crowd_config			list<enum>	选填	人群配置 1：平台新客 2：商家新客 3：商家日历房新客 4：门店新客 5：品牌新客 6:
sales_type			int	选填	售卖形式：默认为全日房； •全日房：1 •钟点房：2
book_time_rule			object	选填	预定时间规则
	is_time_nextday		bool	必填	预定时间段是否跨天
	time_span		object	必填	预定时间段
		from	string	必填	可预定开始时间，格式：HH:mm
		to	string	必填	可预定结束时间，格式：HH:mm

请求示例

{
    "rate_plan_id": "1763526448072717",
    "check_in_date": "2023-04-20",
    "check_out_date": "2023-04-23",
    "number_of_units": 1,
    "number_of_guests": 1,
    "total_amount": 10000,
    "amount_before_tax": 10000,
    "currency":"CNY",
    "daily_rates": [
        {
            "period_start_date": "2023-04-20",
            "period_end_date": "2023-04-21",
            "original_amount": 1000,
            "amount_before_tax": 1000,
            "currency":"CNY",
            "after_promotion_amount":1000,
            "promotion_info":[
                {
                  "promotion_type_code":1,
                  "promotion_id":"222",
                  "promotion_discount":1,
                  "apply_member_level":1
                }
            ]
        },
        {
            "period_start_date": "2023-04-21",
            "period_end_date": "2023-04-22",
            "original_amount": 1000,
            "amount_before_tax": 1000,
            "currency":"CNY",
            "after_promotion_amount":1000,
            "promotion_info":[
                {
                  "promotion_type_code":1,
                  "promotion_id":"222",
                  "promotion_discount":1,
                  "apply_member_level":1
                }
            ]
        },
        {
            "period_start_date": "2023-04-22",
            "period_end_date": "2023-04-23",
            "original_amount": 1000,
            "amount_before_tax": 1000,
            "currency":"CNY",
            "after_promotion_amount":1000,
            "promotion_info":[
                {
                  "promotion_type_code":1,
                  "promotion_id":"222",
                  "promotion_discount":1,
                  "apply_member_level":1
                }
            ]
        },
    ],
    "total_after_promotion_amount":10000,
    "biz_type": 2021,
    "cancel_rules":[
     {
        "cancel_type":2,
        "cancel_time_type":2,
        "cancel_offset_time":{
               "day":0,
                "hour":6,
                 "minute":0
        },
        "cut_type":1,
        "cut_value":10
         }
   ],
    "meals": [
        {
            "meal_type": 1,
            "meal_num": 1
        }
    ],
    "occupancies": [
        {
            "first_name":"",
            "last_name":"",
            "name": "test",
            "phone": "13111111111",
            "license_type": 1,
            "license_id": "422202000000000000"
        }
    ],
    "early_arrival_time": "",
    "last_arrival_time": "",
    "create_order_time_unix": 1682006400000,
    "member_info":{
      "member_level":1,
      "member_id":"",
      "member_name":"",
      "member_phone":"",
      "member_email":"",
      "open_id": 1
    },
    "crowd_config":[2]
}

响应参数

参数名称					参数类型	必须参数	备注
data					struct	必填
	error_code				int	必填	错误码
	description				string	选填	描述信息
	ari				struct	选填	价量信息同商品价量同步接口结构（因价量态不一致，导致可订检查失败，需要将价量态信息回传）
	rate_plan_id				抖音售卖房型ID	必填	抖音售卖房型ID
	stock_and_amount				list<struct>	选填	商品的日历库存和价格
		promotion_amount			int	选填	单间单日促后价格
		timerange			string<Struct>	必填	时间范围，[start,end]为闭区间，多段日期之间不能重复
			start		string	必填	开始日期 eg. 2022-01-01，不得小于今日
			end		string	必填	结束日期 eg. 2022-01-04，不得超过距今365天
		price_member_levels			list<object>	选填	营销后价格
			bind_member_level		int	选填	适用的会员等级,如果营销规则设置了会员适用等级，此处必须传入适用的会员等级
			price		int	必填	营销后价格
		promotion_inventory			int	选填	营销库存
		promotion_id			string	选填	营销ID
		original_amount			int	选填	单间单日价格
		available			bool	选填	房态开关
		inventory			int	选填	房量
		amount_before_tax			int	选填	单间单日税前价
		currency			string	选填	发单价格币种，CNY，USD国际标准枚举值非国内大陆商家必填
		days_of_week			list<struct>	选填	指定周几设定价格
		fplos			string	选填	fplos=“0111011”，则表示允许连住2天,3天,4天,6天,7天；但是不允许连住1天,5天； •抖音支持最长传入14天 •flops中只要有“1”存在，那么总房态available就应该置为true
		length_of_stay			int	选填	连住天数。适用于连住（LosRate）场景下，不同连住天数具有单独的连住ARI。 •length_of_stay字段值应大于1，当不传或者传入1时，不会被认定为LosRate模式，而是当作单日ARI处理 •length_of_stay字段值最大不能超过7天
		los_rate_break_down			list<object>	选填	连住模式下单日价格明细列表 •列表长度需要和length_of_stay的值相等 •按列表顺序设定每天价格，即当length_of_stay = 3时，los_rate_break_down[0]为第一天的价格，los_rate_break_down[1]为第二天的价格，依此类推。
			day_original_amount		int	选填	单天售卖原价
			day_amount_before_tax		int	选填	单天售卖税前价
		cancel_rules			list<object>	选填	取消规则
			cancel_type		enum	必填	取消订单规则 (结构见公共结构2.2.4)
			cancel_time_type		enum	选填	若取消订单规则为限时取消，该字段表示取消订单需要参考的时间点，例如以入住时间为参考，判断用户是否可取消。目前只支持2，即只支持以入住时间为参考 (结构见公共结构2.2.2)
			cancel_offset_time		object	选填	若取消订单规则为限时取消，该字段表示取消订单需要参考的时间时间长度，例如以入住时间为参考，长度6小时，则用户最晚可在入住前6小时取消。
				day	int	选填
				hour	int	选填	范围[0-24） (超过24应进位至day) •该字段表示以24点为基准往前偏移的小时数 •例如传入6，表示24点前6个小时，即18:00点
				minute	int	选填
			cut_type		enum	选填	取消扣费类型 (结构见公共结构2.2.3)
			cut_value		int	选填	取消扣费数额 •范围[0,90]，即扣款百分比区间为0%～90%
		meals			list< object >	选填	餐食信息
			num		int	必填	餐食数额
			type		enum	必填	餐食类别，早/中/晚，不能重复传递，若有多餐更改对应数额 (结构见公共结构2.2.6)
		stay_rules			object	选填	连住规则（仅动态模式需要填）
			min_los		int	选填	最小连住天数（若有值，需保证>=1）
			max_los		int	选填	最大连住天数

		book_rules			object	选填	预约规则（动态价格模式必填，静态价格模式置空即可）
			min_advance_time		object	选填	最晚提前预定限制
			max_advance_time		object	选填	最早提前预定限制 •最大值支持365天
			check_in_from		string	选填	最早入住时间，仅支持整点，当和酒店入住时间保持一致可不传
			check_out_to		string	选填	最晚离店时间，仅支持整点，当和酒店入住时间保持一致可不传
		check_in_to			string	选填	最晚入住时间，仅支持整点，当和酒店入住时间保持一致可不传
			applicable_people		list< object >	选填	适用人群，限制内宾或外宾（不填默认为内外宾） (结构见公共结构2.2.5)
		max_quantity_limt			int	选填	每单限购间数
	product				struct	选填	（因商品信息不一致，导致可订检查失败，需要将商品信息回传）
		meals			list< object >	选填	餐食信息
			num		int	必填	餐食数额
			type		enum	必填	餐食类别，早/中/晚，不能重复传递，若有多餐更改对应数额 (结构见公共结构2.2.6)
		settle_type			enum	必填	收款方式 (结构见公共结构2.2.7)
		out_rate_plan_id			string	必填	外部售卖房型ID
		rate_plan_id			string	必填	抖音售卖房型ID
		active			bool	必填	是否上架商品
		rate_plan_name			string	必填	售卖房型名称（商品名称）
member_info					struct	选填	最新的会员信息（会员信息不一致时需要返回）
	logged_out				int	选填	1：已注销或不是会员 0或不填：为会员
	member_level				int	选填	会员等级(抖音mapping的)，比如：1、2、3、4

响应示例

// 可订成功返回
{
  "data":{
    "error_code": 0,
    "description": "成功"
  }
}

// 可订失败返回

{
    "data":{
        "error_code":8,
        "description":"价格不一致",
        "member_info": {
            "logged_out": 0,
            "member_level": 1
        },
        "ari":{
            "stock_and_amount":[
                {
                    "promotion_amount":12,
                    "promotion_inventory":12,
                    "promotion_id":"3333333",
                    "rate_plan_id":"cpM90IabYM",
                    "timerange":{
                        "start":"2023-06-01",
                        "end":"2023-06-03"
                    },
                    "original_amount":100,
                    "amount_before_tax":1,
                    "available":false,
                    "inventory":10,
                    "room_id":"7zj9VniZFe",
                    "days_of_week":[
                        1
                    ],
                    // 仅动态模式必传
                    "stay_rules":{
                        "min_los":2,
                        "max_los":10
                    },
                    // 仅动态模式必传
                    "book_rules":{
                    // 表示用户需要提前【1，30】天预约
                        "min_advance_time":{
                            "day":1
                        },
                        "max_advance_time":{
                            "day":30
                        },
                        "check_in_from":"12:00",
                        "check_in_to":"15:00",
                        "check_out_to":"10:00",
                        "max_quantity_limt":10,
                        "applicable_people":[
                            1,
                            2
                        ]
                    },
                    // 仅动态模式必传
                    "cancel_rules":[
                        {
                            "cancel_type":2,
                            "cancel_time_type":2,
                            "cancel_offset_time":{
                                "day":0,
                                "hour":6,
                                "minute":0
                            },
                            "cut_type":1,
                            "cut_value":10
                        }
                    ],
                    // 仅动态模式必传
                    "meals":[
                        {
                            "type":1,
                            "num":1
                        }
                    ]
                }
            ],
            "product":{
                "out_rate_plan_id":"xqY0nrjDE9",
                "rate_plan_id":"cpM90IabYM",
                "category_id":8001001,
                "active":true,
                "rate_plan_name":"qJLMFeIF9g",
                "meals":[
                    {
                        "type":9154884479274135424,
                        "num":5285092696482027979
                    }
                ],
                "settle_type":1
            }
        }
    }
}

错误码

枚举id	参数名称	备注
0	成功
1	房型不存在/失效
2	入住总人数超过上限
3	不符合最大/最小连住天数限制
4	入住时期内已满
5	日期格式错误
6	姓名/联系电话格式错
7	重复提交预定请求	如订单已经生成后收到重复请求，请返回成功，不要返回错误
8	价格与酒店实际价格不一致
9	订单不存在或状态异常
10	日期格式错误
11	手机号/证件号码已达到购买上限
12	购买该产品必须填写身份证号码
13	其他异常（服务商自定义）
14	会员信息不一致
15	~~订单已入住不可取消~~
100	需要重试	三方如果需要重试传该code，目前在创单和支付通知场景生效