文档中心 > 酒景直连

酒景订单接入

更新时间：2025/06/23 访问次数：4719

一、流程图

正向时序图

image

创单(支付订单)超时逻辑补偿时序图

image

取消订单时序图

image

退款时序图

image

二、接口说明

注：
1.可以只接2.1，2.4或者2.2，2.4
2.接入2.2需要同时接入2.3

2.1预校验

飞猪调用接入方
请求参数
HotelTicketOrderRequestDTO

字段 类型 是否必填 说明
fliggyOrderId String 是 飞猪订单号
orderId String 否 接入方订单号
hotelTicketOrderProduct HotelTicketOrderProduct 是 订单产品相关信息
startDate String 是 入住时间;yyyy-MM-dd
endDate String 是 离开时间;yyyy-MM-dd
touristGroup TouristGroup 是 入住团信息
subProducts List<CommonSubProduct> 否 子产品信息
extendParams Map<String,Object> 否 mode:1:二次预约，2:日历 扩展参数{“mode”:“1”}

订单产品信息：HotelTicketOrderProduct

字段 类型 是否必填 说明
productId String 是 接入方产品编码(产品ID)
price Long 是 产品单价。单位：分
quantity Integer 是 订单购买产品件数
sessions List<Session> 否 场次信息。
totalPrice Long 是 订单总价

场次：Session

字段 类型 是否必填 说明
sessionId String 是 场次ID
price Long 是 产品单价。单位：分

入住团：TouristGroup

字段 类型 是否必填 说明
totalPersonNumber Integer 是 订单总人数
adultNumber Integer 是 成人数
childNumber Integer 是 儿童数
contact Contact 是 联系人信息
travellers List<Traveller> 是 出行人信息集合 通常指房间绑定的出行人信息

联系人：Contact

字段 类型 是否必填 说明
name String 是 姓名
email String 否 邮箱
mobile String 是 电话

游玩人：Traveller

字段 类型 是否必填 说明
name String 是 姓名
email String 否 邮箱
mobile String 否 电话
certificateType Integer 是 证件类型
certificateId String 是 证件号
travellerType Integer 否 说明：0=成人，1=儿童，2=婴儿，3=老人，4=其他，注：若出行人的身份号和出生日期都为空，则无法判断出行人的年龄，则该出行人的年龄类型属于“其他”

通用子产品：CommonSubProduct

字段 类型 是否必填 说明
type Integer 是 子产品类型。type=4,5,6,7,8
code String 是 子产品编码
travelDate String 是 出行日期；yyyy-MM-dd
singlePackageNum Integer 是 单个套餐该子产品数量
total Integer 是 子产品总数

酒店子产品：HotelSubProduct

字段 类型 是否必填 说明
type Integer 是 子产品类型。type=2
code String 是 子产品编码
travelDate String 是 出行日期；yyyy-MM-dd
singlePackageNum Integer 是 单个套餐该子产品数量
total Integer 是 子产品总数
roomTypeCode String 是 房间类型
bedTypeCode String 否 床型
endDate String 是 离开日期；yyyy-MM-dd
adultNum String 否 成人数
childrenNum String 否 儿童数

餐饮子产品：CateringSubProduct

字段 类型 是否必填 说明
type Integer 是 子产品类型。type=3
code String 是 子产品编码
travelDate String 是 出行日期；yyyy-MM-dd
singlePackageNum Integer 是 单个套餐该子产品数量
total Integer 是 子产品总数
period Integer 否 餐段代码

门票子产品：TicketSubProduct

字段 类型 是否必填 说明
type Integer 是 子产品类型。type=1
code String 是 子产品编码
travelDate String 是 出行日期；yyyy-MM-dd
singlePackageNum Integer 是 单个套餐该子产品数量
total Integer 是 子产品总数
travellerIdentifiers List<TravellerIdentifier> 否 该产品对应出行人

门票子产品出行人信息：TravellerIdentifier

字段 类型 是否必填 说明
certificateType Integer 是 证件类型
certificateId String 是 证件号

返回数据

字段 类型 是否必填 说明
code Integer 是 返回码。0为成功，其他为失败
message String 否 失败需要返回具体错误信息

请求示例

{
	"endDate": "2022-05-09",
	"fliggyOrderId": "TB123456",
	"hotelTicketOrderProduct": {
		"price": 12300,
		"productId": "abc_123",
		"quantity": 1,
		"totalPrice": 12300
	},
	"startDate": "2022-05-08",
	"subProducts": [{
		"code": "ab",
		"period": 1,
		"singlePackageNum": 1,
		"total": 1,
		"travelDate": "2022-05-08",
		"type": 3
	}, {
		"adultNum": 2,
		"bedTypeCode": "gh",
		"code": "cd",
		"endDate": "2022-05-09",
		"roomTypeCode": "ef",
		"travelDate": "2022-05-08",
		"type": 2
	}],
	"touristGroup": {
		"adultNumber": 2,
		"contact": {
			"mobile": "18888888888",
			"name": "姓名1"
		},
		"totalPersonNumber": 2,
		"travellers": [{
			"certificateId": "632323190605268561",
			"certificateType": 0,
			"name": "游客1"
		}, {
			"certificateId": "632323190605268562",
			"certificateType": 0,
			"name": "游客2"
		}]
	}
}

响应示例

{"code":0,"message":"OK"}

2.2 预下单(占单)接口

飞猪调用接入方
实现2.2，必须实现2.3来释放占用库存
接口方法定义：com.alitrip.travel.gateway.client.GwHotelTicketOrderService#preOrder
请求参数：与2.1 预校验接口一致
返回数据

字段 类型 是否必填 说明
code Integer 是 返回码。0为成功，其他为失败
message String 否 失败需要返回具体错误信息
data HotelTicketOrderResponse 否 成功则需要返回

HotelTicketOrderResponse

字段 类型 是否必填 说明
orderId String 是 对接方订单号

请求示例

{
	"endDate": "2022-05-09",
	"fliggyOrderId": "TB123456",
	"hotelTicketOrderProduct": {
		"price": 12300,
		"productId": "abc_123",
		"quantity": 1,
		"totalPrice": 12300
	},
	"startDate": "2022-05-08",
	"subProducts": [{
		"code": "ab",
		"period": 1,
		"singlePackageNum": 1,
		"total": 1,
		"travelDate": "2022-05-08",
		"type": 3
	}, {
		"adultNum": 2,
		"bedTypeCode": "gh",
		"code": "cd",
		"endDate": "2022-05-09",
		"roomTypeCode": "ef",
		"travelDate": "2022-05-08",
		"type": 2
	}],
	"touristGroup": {
		"adultNumber": 2,
		"contact": {
			"mobile": "18888888888",
			"name": "姓名1"
		},
		"totalPersonNumber": 2,
		"travellers": [{
			"certificateId": "632323190605268561",
			"certificateType": 0,
			"name": "游客1"
		}, {
			"certificateId": "632323190605268562",
			"certificateType": 0,
			"name": "游客2"
		}]
	}
}

响应示例


{
	"code": 0,
	"data": {
		"orderId": "1212425"
	},
	"message": "OK"
}

2.3 取消预下单(占单)接口

飞猪调用接入方
5分钟未对订单进行支付则会调用该接口取消订单
实现2.2，必须实现2.3来释放占用库存，没有实现2.2则该接口非必接
请求参数

字段 类型 是否必填 说明
fliggyOrderId String 是 飞猪订单号
orderId String 否 对接方订单号

返回参数

字段 类型 是否必填 说明
code Integer 是 返回码。0为成功，其他为失败
message String 否 失败需要返回具体错误信息

请求示例

{
	"fliggyOrderId": "TB123456",
	"orderId": "1212425"
}

响应示例

{
	"code": 0,
	"message": "OK"
}

2.4 创单（支付订单）

飞猪调用接入方
必接
请求参数：与2.1预校验接口一致
返回数据

字段 类型 是否必填 说明
code Integer 是 返回码。0为成功，其他为失败
message String 否 失败需要返回具体错误信息
data HotelTicketOrderResponse 是 成功则需要返回

HotelTicketOrderResponse

字段 类型 是否必填 说明
orderId String 是 对接方订单号
status Integer 是 订单状态。1(出票中),通过发码通知接口出票；2(已出票)，无须调用发码通知接口。
vouchers List<HotelTicketVoucher> 否 订单状态为2(已出票)且有凭证则返回

出票状态：1-出票中；2-已出票
凭证信息：HotelTicketVoucher

字段 类型 是否必填 说明
type Integer 是 凭证类型 1：票码， 2：券码
bizType Integer 是 业务类型：1：门票， 2：酒店
code String 是 凭证码
certificateId String 否 证件号
img byte[] 否 二维码图片
url String 否 凭证链接
availableNums Integer 是 每张票或券可使用次数（如针对一码多刷，往返索道3张票1个码，每张票可使用次数为2，则该码可以刷6次
usageNums Integer 是 已使用次数
canUse Boolean 否 凭证是否可用

请求示例

{
	"endDate": "2022-05-09",
	"fliggyOrderId": "TB123456",
	"hotelTicketOrderProduct": {
		"price": 12300,
		"productId": "abc_123",
		"quantity": 1,
		"totalPrice": 12300
	},
	"startDate": "2022-05-08",
	"subProducts": [{
		"code": "ab",
		"period": 1,
		"singlePackageNum": 1,
		"total": 1,
		"travelDate": "2022-05-08",
		"type": 3
	}, {
		"adultNum": 2,
		"bedTypeCode": "gh",
		"code": "cd",
		"endDate": "2022-05-09",
		"roomTypeCode": "ef",
		"travelDate": "2022-05-08",
		"type": 2
	}],
	"touristGroup": {
		"adultNumber": 2,
		"contact": {
			"mobile": "18888888888",
			"name": "姓名1"
		},
		"totalPersonNumber": 2,
		"travellers": [{
			"certificateId": "632323190605268561",
			"certificateType": 0,
			"name": "游客1"
		}, {
			"certificateId": "632323190605268562",
			"certificateType": 0,
			"name": "游客2"
		}]
	}
}

响应示例

// 发码回调发码的创单成功响应
{
	"code": 0,
	"data": {
		"orderId": "1212425",
    "status":3
	},
	"message": "OK"
}

// 创单发码的创单成功响应
{
	"code": 0,
	"data": {
		"orderId": "1212425",
		"status": 4,
		"vouchers": [{
			"availableNums": 1,
			"canUse": true,
			"code": "123454234",
			"type": 1,
			"usageNums": 0
		}]
	},
	"message": "OK"
}

// 创单成功且状态为4(已出票)的响应
{
	"code": 0,
	"data": {
		"orderId": "1212425",
    "status":4
	},
	"message": "OK"
}

2.5 申请退款

飞猪调用接入方
必接
请求参数

字段 类型 是否必填 说明
fliggyOrderId String 是 飞猪订单号
orderId String 否 接入方订单号

响应参数

字段 类型 是否必填 说明
code Integer 是 返回码。0为成功，其他为失败
message String 否 失败需要返回具体错误信息
data HotelTicketOrderResponse 是 成功则需要返回

HotelTicketOrderResponse

字段 类型 是否必填 说明
orderId String 否 对接方订单号
status Integer 是 退款状态：1(退款成功), 2(退款拒绝),3(退款中), 其他则以失败结果返回即可
refundRefusedReason String 否 退款拒绝原因。退款状态是退款拒绝时必填。

退款状态：1-退款成功；2-退款拒绝；3-退款中
请求示例

{
	"fliggyOrderId": "TB123456",
	"orderId": "1212425"
}

响应示例

// 退款成功  
{
	"code": 0,
	"data": {
		"orderId": "1212425",
    "status":1
	},
	"message": "OK"
}

// 退款成功 ,需要异步回调 
{
	"code": 0,
	"data": {
		"orderId": "1212425",
    "status":3
	},
	"message": "OK"
}


// 退款失败   
{
	"code": 60003,
	"message": "订单未支付或者已使用订单不允许退款"
}

 // 拒绝退款
{
	"code": 0,
	"data": {
		"orderId": "1212425",
    "status":2,
    "refundRefusedReason":"订单设置不允许退款"
	},
	"message": ""
}

2.6 查询订单状态及凭证

飞猪调用接入方
必接，用来同步数据状态

请求参数

字段 类型 是否必填 说明
fliggyOrderId String 是 飞猪订单号
orderId String 否 接入方订单号

响应数据

字段 类型 是否必填 说明
code Integer 是 返回码。0为成功，其他为失败
message String 否 失败需要返回具体错误信息
data HotelTicketOrderResponse 是 成功则需要返回

HotelTicketOrderResponse

字段 类型 是否必填 说明
orderId String 否 对接方订单号
status Integer 是 订单状态
vouchers List<HotelTicketVoucher> 否 有凭证则返回

订单状态：0-已创单;2-出票中; 3-已出票;4-已核销; 5-退款中; 6-已退款; 7-未支付关单;8-出票失败;9-退款失败;
凭证信息：HotelTicketVoucher

字段 类型 是否必填 说明
type Integer 是 凭证类型 1：票码， 2：券码
bizType Integer 是 业务类型：1：门票， 2：酒店
code String 是 凭证码
certificateId String 否 证件号
img byte[] 否 二维码图片
url String 否 凭证链接
availableNums Integer 是 每张票或券可使用次数（如针对一码多刷，往返索道3张票1个码，每张票可使用次数为2，则该码可以刷6次
usageNums Integer 是 已使用次数
canUse Boolean 否 凭证是否可用

请求示例

{
	"fliggyOrderId": "TB123456",
	"orderId": "1212425"
}

响应示例

// 有凭证
{
	"code": 0,
	"data": {
		"orderId": "1212425",
		"status": 4,
		"vouchers": [{
			"availableNums": 2,
			"canUse": true,
			"code": "123454234",
			"type": 1,
			"usageNums": 0
		}]
	},
	"message": "OK"
}

// 无凭证
{
	"code": 0,
	"data": {
		"orderId": "1212425",
		"status": 4
	},
	"message": "OK"
}

2.7. 创单（支付订单）结果异步通知接口 （TOP）

接入方调用飞猪
接口：alitrip.travel.hotelticket.order.create

2.8订单核销异步通知接口 （TOP）

接入方调用飞猪
接口：alitrip.travel.hotelticket.order.verify

2.9 退款结果异步通知接口（TOP）

接入方调用飞猪
接口：alitrip.travel.hotelticket.order.refund

FAQ

关于此文档暂时还没有FAQ
有用(0) 我要提问
返回
顶部
阿里巴巴集团 | 淘宝网 | 天猫 | 聚划算 | 全球速卖通 | 阿里巴巴国际交易市场 | 1688 | 阿里妈妈 | 阿里旅行·去啊 | 阿里云计算 | YunOS | 阿里通信 | 万网 | 高德 | 优视 | 友盟 | 酷盘 | 虾米 | 天天动听 | 来往 | 钉钉 | 11Main | 支付宝
关于淘宝 合作伙伴 营销中心 联系客服 开放平台 诚征英才 联系我们 网站地图 法律声明 © 2016 Taobao.com 版权所有
网络文化经营许可证：文网文[2010]040号 | 增值电信业务经营许可证：浙B2-20080224-1 | 信息网络传播视听节目许可证：1109364号