生活服务商家应用 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: 请求签名，签名规则

请求体

参数名称	参数类型	必须参数	备注
» order_id	string	必填	抖音订单id
» source_order_id	string	选填	biz_type= 2012的情况下，赋值为预售订单的order_id
» 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
» early_arrival_time	string	选填	预计最早到店时间
» last_arrival_time	string	选填	预计最晚到店时间
» number_of_units	int	必填	预定间数
» number_of_guests	int	必填	入住人数
» daily_rates	list<object>	必填	单日单间价格
»» original_amount	int	必填	原始价格(分)，对于非中国大陆商家，代表税后价
»» amount_before_tax	int	选填	税前价，非中国大陆商家使用
»» currency	string	选填	发单价格币种，CNY，USD国际标准枚举值非国内大陆商家必填
»» daily_add_amount	int	选填	间夜加价金额(分)，三方需要适配间夜维度daily_rates（新的daily_rates逻辑需要加白生效）
»» promotion_info	list<object>	选填	预约单对应的单日单间营销优惠信息
»»» promotion_type_code	string	选填	预约单对应的营销及优惠一级类型code (结构见酒店常见枚举值列表3.1营销活动typeCode)
»»» promotion_id	string	选填	预约单对应的营销及优惠活动ID 信息
»»» promotion_name	string	选填	预约单对应的营销及优惠活动名称
»»» promotion_discount	int	选填	预约单对应的营销及优惠活动具体金额（分）
»» presale_promotion_info	list<object>	选填	预约单关联的原始预售券单日单间营销优惠信息
»»» coupon_promotion_id	string	选填	预约单关联的原始预售券的营销及优惠ID
»»» coupon_promotion_type	string	选填	预约单关联的原始预售券的营销及优惠类型
»»» coupon_promotion_discount	int	选填	预约单关联的原始预售券的营销及优惠金额（分）
»»» coupon_promotion_name	string	选填	预约单关联的原始预售券的营销及优惠名称
»» period_start_date	string	必填	时间段开始时间
»» period_end_date	string	必填	时间段结束时间
»» period_start_time	string	选填	开始时间点，新增选择钟点房时为必填,格式 yyyy-MM-dd hh:mm:ss
»» period_end_time	string	选填	结束时间点，新增选择钟点房时为必填，格式 yyyy-MM-dd hh:mm:ss
»» usage_duration	int	选填	使用时长选择钟点房时为必填校验逻辑： 1.时长校验：1-23 2.支持填写最小时间为1，取整数，例如：使用1小时，使用2小时
» cancel_rule	list<object>	选填	取消规则(`trip/hotel_model.CancelRule`结构见公共结构取消规则)
»» cancel_type	enum	必填	取消订单规则 (结构见公共结构取消规则)
»» cancel_time_type	enum	选填	若取消订单规则为限时取消，该字段表示取消订单需要参考的时间点，例如以入住时间为参考，判断用户是否可取消。 (结构见公共结构取消时间计算规则)
»» cancel_offset_time	object	选填	若取消订单规则为限时取消，该字段表示取消订单需要参考的时间时间长度，例如以入住时间为参考，长度6小时，则用户最晚可在入住前6小时取消。
»»» day	int	选填	日
»»» hour	int	选填	小时
»»» minute	int	选填	分钟
»» cut_type	enum	选填	取消扣费类型 (结构见公共结构取消费用计算规则)
»» cut_value	int	选填	取消扣费数额
» create_order_time_unix	int	选填	创建订单时间戳，秒
» total_amount	int	必填	总预约房型原始价格(分)，对于非中国大陆商家，代表税后价（取自三方同步到预约房型上的价格）
» amount_before_tax	int	选填	税前价，非中国大陆商家使用
» currency	string	选填	发单价格币种，CNY，USD国际标准枚举值非国内大陆商家必填
» presale_total_promotion	int	选填	预约单关联的原始预售券的总营销及优惠金额（分）
» meals	list<struct>	选填	餐食信息(`trip/trade_openapi.Meal`结构见公共结构附餐信息
»» meal_type	int	选填	餐食类型 1:早餐 2：中餐 3：晚餐 4:无餐食
»» meal_num	int	选填	餐食数量
» occupancies	list<struct>	选填	入住人列表
»» first_name	string	选填	姓
»» last_name	string	选填	名
»» name	string	必填	姓名，加密
»» phone	string	必填	联系电话，加密
»» license_type	int	选填	1,身份证2,港澳通行证3台湾通行证,4回乡证,5台胞证,6护照,7外籍护照
»» license_id	string	选填	证件 ID，加密
»»sex	int	选填	1:男，2：女
»»birthday	string	选填	出生日期，格式 yyyy-MM-dd
»»license_validity	string	选填	证件有效期，格式 yyyy-MM-dd，当证件类型不为身份证时，该字段必填
» contact_info	struct	必填	联系人信息
»» name	string	必填	姓名，加密
»» phone	string	必填	联系电话，加密
» pay_info	struct	选填	供应商在模式为支付后创单时该参数为必传参数
»» origin_amount	int		预售券原始金额，取值为商品售价，单位分
»» add_amount	int		取加价金额的应付原始金额，单位分
»» pay_amount	int		预售券实付金额 + 预约单加价实付金额，单位分
»» merchant_receivable_amount	int		预售券原始金额 + 加价原始金额 - 商家补贴，单位分
»» pay_time_unix	int	选填	支付时间戳，秒
» remark_from_douyin	string	选填	抖音平台备注格式权益订单、抖音预售券订单id：xxx、商品名称（预售券名称）：xx、原始金额：x元、加价金额：x元、实付金额：x元、商家应收金额：x元、商品搭配：xxx （住：x选x+房型名称、餐：全部可选或x选x+餐食内容、享/礼遇:全部可选或x选x+内容）、权益内容、Order from douyin 币种
» remark_from_guest	string	选填	客人备注
» sales_type	string	选填	售卖形式：默认为全日房；全日房：钟点房：hourly-room
»appointment_award	object	选填	预约激励
»» award_type	enum	选填	预约激励类型公共结构：房型升级、餐食升级、游乐升级、其他 1.当开启预约激励后为必填项； 2.激励类型仅能单选结构见公共结构预约激励类型
»» content	string	选填	权益内容： 1.文本内容小于等于40字 2.当开启预约激励后为必填项 3.当预约单的预约时间在激励时间内则订单中展示权益内容
»member_info	object	选填	会员信息
»»member_level	int	必填	会员等级
»»member_id	string	选填	会员卡号
»»member_name	string	选填	会员姓名
»»member_phone	string	选填	会员手机号（加密传输）

解密方法

根据ClientKey找到ClientSecret，将ClientSecret向左右使用字符补齐32位/裁剪至32位，补齐：补位字符：#，先补左侧再补右侧再补左侧······直到补满32位。裁剪：先裁剪左侧再裁右侧再裁左侧······直到剩余32位。（正常不需要补齐，secret默认为32位，此举是为了以防万一）

将ClientSecret作为Key，右侧16位为向量IV

将密文进行base64解码。

使用AES-256-CBC模式解密解码后的密文，对齐使用PKCS5Padding方式

详情请参考：加密字段解密方法

请求示例

{
    "order_id": "1000946099201940764",
    "source_order_id": "1000946099201940761",
    "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": 20000,
    "amount_before_tax": 20000,
    "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"
        }
    ],
    "biz_type": 2011,
    "meals": [
        {
            "meal_type": 1,
            "meal_num": 1
        }
    ],
    "occupancies": [
        {
            "first_name":"",
            "last_name":"",
            "name": "test",
            "phone": "13111111111",
            "license_type": 1,
            "license_id": "422202020202020202"
        }
    ],
    "contact_info": {
        "name": "test",
        "phone": "13111111111"
    },
    "cancel_rule": [{
        "cancel_type": 1,
        "cancel_time_type": 1,
        "cancel_offset_time": {
            "day": 1,
            "hour": 1,
            "minute": 1,
            "second": 1
        },
        "cut_type": 6948897508913326394,
        "cut_value": 2048624488842148897
    }],
    "early_arrival_time": "",
    "last_arrival_time": "",
    "create_order_time_unix": 1902790713142520557,
    "remark_from_guest": "",
    "remark_from_douyin":"权益订单，抖音预售券订单id：1016716518400664370、商品名称（预售券名称）：测试预售券餐食预约权益3、原始金额：11.00元、加价金额：0.00元、实付金额：11.00元、商品搭配：（住：2选1:1份免审-物理房测试4/1份物理房型类目测试   餐：全部可选:1份早餐   )  、快预约尊享免费升级豪华房 Order from douyin  CNY",
    "appointment_award":{
        "content":"快预约尊享免费升级豪华房",
        "AwardType":1
     }
}

响应参数

参数名称	参数类型	必须参数	备注
data	struct	必填
» error_code	int	必填	详见通用错误码
» description	string	选填	描述信息
» order_id	string	必填	抖音订单号
» order_out_id	string	选填	第三方订单 ID，成功的情况下该参数必传
» confirm_info	struct	选填	供应商在交易模式为支付后创单时该对象必须返回，否则会导致订单取消
» » hotel_confirm_number	string	选填	订单确认时必填酒店确认号（酒店预订过程中的一个关键凭证，用于：确认预订已被酒店系统接收、到店入住时核实身份、处理问题单/售后时的核查依据、避免重复预订/超售）
» » confirm_mode	int	选填	在confirm_mode对象有返回的时候必填通过后接单方式 1：同步接单，需要返回hotel_confirm_number和confirm_result 2：异步接单
» » confirm_result	int	选填	交易模式为支付后创单模式必填 0: 异步 1：接单 2：拒单

响应示例

{
   "data":{
    "error_code": 0,
    "description": "successs",
    "order_id": "1000946099201940764",
    "order_out_id": "nZJs9msX3I"
    }
}

错误码

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