请求预订指定的客房。此请求必须使用 POST 方法通过 HTTPS 发送,以保护客户的付款信息。在此请求中提交的信息需遵守 EAN 的所有权欺诈和安全验证方法。

在请求中提供的信用卡信息用于直接为预订付款。收到成功回复后,客户即需为预订全额付款(额外费用除外,如客房服务费),即使提前几个月预订也是如此。

务必为有效预订使用正确的 cid/apiKey 对。这对于下达成功的订单并确保获得的任何佣金都支付到正确的帐户至关重要。

如果在 cityaddressfirstNamelastName 值方面遇到了输入验证错误,则请注意,API 目前仅支持 UTF-8 基本拉丁语拉丁语-1 增补字符集。对于使用的字符(例如 ő 或 ű)不受这些字符集支持的语言,必须进行过滤或转换,避免出现输入错误。


请求格式
XML/REST URL: POST https://book.api.ean.com/ean-services/rs/hotel/v3/res
XML 父元素: <HotelRoomReservationRequest>

如要避免 URL 长度限制问题,请将 POST 正文内的所有请求值以 application/x-www-form-urlencoded 数据的形式发送。在 URL 字符串本身内部不要发送任何参数。
对于 XML 请求,通用元素必须以用于 GET 请求的相同格式发送,请勿尝试将这些值格式化为 POST 主体中的 XML 元素。



请求参数

特定于服务的 URL 参数
名称 是否必需 说明
currencyCode 字符串 为预订请求填充此参数时,始终使用上一回复的 ChargeableRateInfo 节点返回的属性值。
使用该值的其他源可能会导致不匹配错误。
additionalData MapEntry 的容器

使用此仅用于预订的参数有助于在 EAN 联盟中心中跟踪预订。请参阅我们的跟踪预订页面获取完整的文档。



基本参数
名称 类型 是否必需 说明
apiExperience 字符串

使用此属性可识别您的请求源。针对您发送的每个请求,从下文提供的集合中选择一个适用的值。

值:
PARTNER_CALL_CENTER - 来自呼叫中心代理的请求
PARTNER_WEBSITE - 来自面向客户网站的请求
PARTNER_MOBILE_WEB - 来自手机格式网站的请求
PARTNER_MOBILE_APP - 来自手机应用程序的请求
PARTNER_BOT_CACHE - 来自缓存 bot 的请求
PARTNER_BOT_REPORTING - 来自报告 bot 的请求
PARTNER_AFFILIATE - 来自作为您自己的联盟伙伴库的 API/平台的请求

hotelId 长整型 要请求的预订对应的酒店 ID
arrivalDate 字符串

入住日期,格式为 MM/DD/YYYY。从客房回复继承值。

预订最晚可以到酒店当地时间晚上 11:59(太平洋标准时间和太平洋岛屿时间晚上 9:59)。

departureDate 字符串 退房日期,格式为 MM/DD/YYYY。从客房回复继承值。
supplierType 字符串 定义要用于执行预订的供应商。从客房回复继承值。

值:
E:Expedia Collect
rateKey 字符串 验证在预订请求中指明的参数。从客房回复继承值。使用在客房回复的第一个 Room 对象中返回的 rateKey,以实现最佳性能。

如果使用的任何值与上一客房回复中提供的值不同,则预订将失败。

如果选择允许客户在预订阶段修改任何参数,请通过新的客房请求重新发送这些参数,为此参数获取新的有效值。

指明“QueryId 无效”的错误或房价缓存错误指示键已过期或无效。请重新发送上一客房请求以获取新值,即使未更改任何参数也是如此。
roomTypeCode 字符串 指示请求的特定客房的代码。始终从上一客房回复中动态获取。

同时还发送 rateCode
rateCode 字符串 指示根据请求的特定客房配对的房价的代码。始终从上一客房回复中动态获取。

同时还发送 roomTypeCode
RoomGroup 对象 定义住客和客房计数的 Room 数组的容器。根据上一客房请求中的定义,对成人、儿童及儿童年龄使用相同的值。

对于预订,需要此对象的其他专用参数,参见下文。
RoomGroup.Room 数组 Room 节点数定义请求的客房数。包含的节点数量和住客计数/年龄参数与上一客房请求所定义的相同。
Room.numberOfAdults 整型 客房的成人住客计数。使用的值与上一客房请求中所定义的相同。
Room.numberOfChildren 整型 值 > 0 时为 客房的儿童住客计数。使用的值与上一客房请求中所定义的相同。
Room.childAges 逗号分隔的
整型列表
儿童计数 > 0 时为 儿童住客(如果有)的年龄。使用的值与上一客房请求中所定义的相同。EAN 将年龄在 0 到 17 岁之间的人视为儿童。
Room.firstName 字符串 预订中要入住的住客的完整名字。姓名必须与住客入住酒店时所出示的带照片身份证相符。

只接受无重音的拉丁 ASCII 字符(26 个字母组成的字母表)。

最多 25 个字符,不含称谓或公司名称。每个客房的住客姓名不需要是唯一的。
Room.lastName 字符串 预订中要入住的住客的完整姓氏。姓名必须与住客入住酒店时所出示的带照片身份证相符。

只接受无重音的拉丁 ASCII 字符(由 26 个字母组成的字母表)。

最多 40 个字符,不含称谓或公司名称。每个客房的住客姓名不需要是唯一的。
Room.bedTypeId 字符串 客户所选床型的代码(如未提供选择内容则为单个值)。

从客房回复中客户所选客房的 BedType ID 属性继承匹配的值。

同一客房对多个床型的选择仅为请求,如果供应情况不允许,酒店不一定满足这些请求。
Room.numberOfBeds 整型 值为 1 或 2。仅为请求,仅当客房回复内容中返回合理的 BedType 选项时提供。
Room.smokingPreference 字符串 (如果使用) 请求的吸烟偏好。如果指定的预订不需要此元素,可在您的请求中将其完全忽略。

可能的值:
NS:禁止吸烟
S:允许吸烟
E:任何一种选择

仅提供从客房回复中返回的值 - 不得将上述值用作硬性选择。包含未在回复中提供的值将导致预订失败。请勿发送多个值。
affiliateConfirmationId 字符串 设计用于跟踪预订和帮助避免重复预订的值。

在提交预订之前,生成唯一的值,例如 GUID ID(最多 36 个字符)。如果 API 检测到该值与现有预订配对,则会阻止所有后续预订出现重复。

为避免拒绝有效的预订重试,如果重新尝试预订因超时以外的错误失败,请始终创建新值
affiliateCustomerId 字符串 与合作伙伴方跟踪一起使用的其他可选客户 ID。仅在内部使用此 ID,因为在外部使用此 ID 会允许检索不属于客户的行程。
itineraryId 长整型

如果初始预订请求返回信用卡错误,则从回复中提取该值,并将其包含在后续预订请求中。

再次进行传递时,该值根据您的第一次请求生成的现有行程记录进行配对。任何重复的信用卡偏差或错误都只限于单个记录,以避免在任何统计信息中显示多个取消。

仅当您要使用 EAN 支持(您没有自己的支持代理)时,才可将该值透露给客户。

如果返回 -1,请不要重新发送该值。这表示未创建行程。发送错误消息并允许客户根据需要进行更正后,创建一个新请求再次开始。

chargeableRate 字符串 对预订的收费总额。

从客房回复返回的 ChargeableRateInfo 对象中继承 total 的值。

在提交请求后,将根据所提供客房和房价代码的最新已知房价验证该房价。如果最新房价较高,则返回错误,包含新的更高房价及其匹配的 rateKey 值。如果最新房价较低,则请求传递新的较低房价。
specialInformation 字符串

允许客户添加额外信息或请求以传递给酒店。

其中的任何信息都仅为请求并且不予保证 – 请勿使用该字段发出 B2B 客户服务请求或传递任何敏感的个人/财务信息。

最多 256 个字符,不可使用换行或回车符。未从此参数中剥离的任何换行或回车符都将导致不可恢复的错误。

sendReservationEmail 布尔型

如果发送自己的确认电子邮件,则发送为 false;否则请忽略。

仅当您已咨询客户经理或支持人员有关您自己的确认电子邮件系统的事宜后,才可使用此参数。

付款信息参数
这些参数定义用于验证客户的付款信用卡和收取帐款的信息。

付款信息通过 ReservationInfo 对象和 AddressInfo 对象提供。这两个对象中适用的值根据持卡人发卡银行的信息进行验证。

用于付款验证和处理的一些系统无法解析非拉丁字符,因此请确保对所有参数仅使用拉丁字符值,以避免数据验证错误。

请在我们信用卡类型页面的验证部分中,参阅请求和处理卡信息的最佳做法。

名称 是否必需 说明
ReservationInfo 对象 包括客户的联系信息和信用卡信息。
ReservationInfo.email 字符串 客户的电子邮件地址。会自动向此地址发送 EAN (travelnow.com) 确认电子邮件。即使您的集成将该字段视为仅供内部使用,也必须是有效的电子邮件地址。
整个地址的最大长度为 50 个字符,包括 @ 和空格。
ReservationInfo.firstName 字符串 信用卡持卡人的完整名字。
只接受无重音的拉丁 ASCII 字符(26 个字母组成的字母表)。
最多 25 个字符,不含称谓或公司名称。
ReservationInfo.lastName 字符串 信用卡持卡人的完整姓氏。
只接受无重音的拉丁 ASCII 字符(26 个字母组成的字母表)。
最多 40 个字符,不含称谓或公司名称。
ReservationInfo.homePhone 字符串

客户的家庭电话号码。需要联系客户来解决有关他们预订的问题时,供客户服务代理使用。

数字必须至少包含 5 位。仅限使用 0-9、+、- 和 ( ) 字符。

ReservationInfo.workPhone 字符串 客户的工作电话号码。数字必须至少包含 5 位。仅限使用 0-9、+、- 和 ( ) 字符。
ReservationInfo.extension 字符串 客户的工作电话分机号码(如果需要)。最多 5 个字符。
ReservationInfo.faxPhone 字符串 客户的传真号码。数字必须至少包含 5 位。仅限使用 0-9、+、- 和 ( ) 字符。
ReservationInfo.companyName 字符串 公司名称(如需用于员工差旅收据或纳税目的)
ReservationInfo.creditCardType 字符串 所使用的信用卡的类型。请查看此页面了解信用卡类型的特定值和有关验证的详细信息。
ReservationInfo.creditCardNumber 字符串 客户信用卡卡号。
ReservationInfo.creditCardIdentifier 字符串 位于卡背面的信用卡识别号或卡安全码(CSV 或 CVV)。从不在客户初始输入和预订请求后存储该值。
ReservationInfo.creditCardExpirationMonth 字符串 信用卡到期月份,格式为 MM。
ReservationInfo.creditCardExpirationYear 字符串 信用卡到期年份,格式为 YYYY。
地址信息
持卡人地址信息在独立于 ReservationInfo 中付款卡详细信息的对象中发送。开发期间,可以在该对象中使用特殊值,以执行静态测试预订
名称 是否必需 说明
AddressInfo 对象 包括持卡人的地址信息。该信息必须与信用卡提供商的记录匹配,才能成功处理付款。
AddressInfo.address1 字符串 客户所在的街道地址,最多 28 个字符。请确保正确编码特殊字符。
AddressInfo.address2 字符串 街道地址的可选第二行,最多 28 个字符。
AddressInfo.address3 字符串 街道地址的可选第三行,最多 28 个字符。
city 字符串 客户所在的城市。
stateProvinceCode 字符串 对于 US、CA、
AU 为
包含指定城市的州/省的双字符代码。在澳大利亚,您必须使用下面提供的特殊代码。

参考:
美国州代码
加拿大省/领地代码
澳大利亚省/领地代码
  • 澳大利亚首都 - AC
  • 新南威尔士州 - NW
  • 澳北区 - NO
  • 昆士兰 - QL
  • 南澳大利亚 - SA
  • 塔斯马尼亚岛 - TS
  • 维多利亚州 - VC
  • 西澳大利亚州 - WT
countryCode 字符串 指定城市所在国家或地区的双字符 ISO-3166 代码。仅可使用在 ISO-3166 解码表中指定为“正式指定”的国家或地区代码。
postalCode 字符串 客户的帐单邮政编码。最少 5 个字符,最多 10 个字符。美国预订必须仅使用 5 位数字的邮政编码。
该值必须与信用卡提供商的记录相符,否则预订将无效。
将此字段标记为“帐单邮政编码”或“帐单邮区编号”,以减少失败情况。有效字符包括字母、数字、空格、下划线 (_) 和连字符 (-)。


预订回复
确认对请求的客房预订成功,或预订未确认为成功时,提供有关预订状态的信息。

成功预订的回复还包含客户的行程编号、确认编号以及有关他们客房选择和支付价格的确认信息。

由于此回复包含客户数据,请通过 HTTPS 安全地向用户返回数据。

回复内容
父元素: HotelRoomReservationResponse


名称 说明
itineraryId 长整型 EAN 为预订分配的唯一 ID。

在 EAN 或您自己的客户服务部门与客户进行通信时,与预订确认编号一起使用。请确保明确地将两个值提供给客户。
confirmationNumbers 数组

预订的确认编号,每间预订客房对应一个确认编号。由 EAN 预订数据库生成。

该值与行程 ID 一起使用,用于 EAN 与客户之间的所有通信。如果您发送自己的电子邮件依赖 EAN 支持(您没有自己的代理),请确保将两个值清晰明确地提供给客户。如果使用代理到代理支持,请勿将该值提供给客户。

多客房预订将返回第一间客房的标准确认编号。其余客房将具有相同的确认编号,并附有连字符和一个数字,从 1 开始,例如 120467481181, 120467481181-1, 120467481181-2

processedWithConfirmation 布尔型 指示酒店在处理预订时是否已确认。

如果返回 false,则表示酒店尚未对预订返回确认编号。预订很可能以 PS 状态返回。

在这些情况下,EAN 代理将监视预订,直到其完全确认。确认电子邮件将告知客户,酒店一旦提供确认编号后,代理会立即进行转发。
errorText 字符串 EanWSError 通用元素的内容外,可能已在预订过程中生成的任何错误文本。
hotelReplyText 字符串 在预订时从酒店收到的任何信息
supplierType 字符串 确认用于处理预订的供应商系统。
reservationStatusCode 字符串 指示在预订时,供应商系统中的预订状态。为所有非确认值预测适当的客户消息。

值:
CF 已确认
CX 已取消
UC 未确认。将此状态视同 DT。API 将永不向实时预订分配此状态。
PS 待定供应商。请参阅我们的待定流程指南。
ER 错误。需要代理关注预订或信用卡被拒绝时,可能会发生错误。如果返回信用卡错误,则会适当地提示客户。如果客户尝试再次预订,会重新发送在失败的预订回复中返回的 itineraryId
DT 已删除行程(通常为测试订单或失败的订单)
existingItinerary 布尔型 被阻止重复预订的指示符,与 affiliateConfirmationId 请求参数结合使用。如果多次发送相同的确认值,则随现有成功行程返回 true
numberOfRoomsBooked 整型 确认预订的客房数。将与返回的确认编号数匹配。
drivingDirections 字符串 通常为空,建议不要显示。
checkInInstructions 字符串 酒店的入住说明。
specialCheckInInstructions 字符串 包含有关入住的重要信息,例如需要向酒店通知预期到达时间。将该信息显示在与主要入住说明相同的区域。
arrivalDate 字符串 确认入住日期
departureDate 字符串 确认退房日期
hotelName 字符串 所预订酒店的名称
hotelAddress 字符串 酒店街道地址
hotelCity 字符串 酒店所在的城市
hotelStateProvinceCode 字符串 包含指定城市的州/省的双字符代码。仅对 US、CA 和 AU 国家代码返回结果。

参考:
美国州代码
加拿大省/领地代码
澳大利亚省/领地代码
hotelCountryCode 字符串 酒店所在国家或地区的双字符 ISO-3166 代码。
hotelPostalCode 字符串 酒店邮政编码
roomDescription 字符串 对所预订客房的简短说明
rateOccupancyPerRoom 整型 确认保证在所预订客房入住的住客数。
RoomGroup 对象 定义住客和客房计数的 Room 数组的容器。确认预订的每间客房的住客和床型详情。
RoomGroup.Room 数组 节点数将与 numberOfRoomsBooked 的值匹配。
Room.numberOfAdults 整型 客房的成人住客计数。
Room.numberOfChildren 整型 客房的儿童住客计数。
Room.childAges 逗号分隔的
整型列表
儿童住客(如果有)的年龄。
Room.firstName 字符串 预订中要入住的住客的完整名字。
Room.lastName 字符串 预订中要入住的住客的完整姓氏。
Room.bedTypeId 字符串 客户所选床型的代码(如未提供选择内容则为单个值)。
Room.bedTypeDescription 字符串 确认床型选择的说明。
Room.numberOfBeds 整型 值为 1 或 2。
Room.smokingPreference 字符串 确认请求的吸烟偏好。
Room.ChargeableNightlyRates 数组 客房 NightlyRate 数组的容器。返回的房价具体针对各间客房,并且根据住宿时长按顺序返回。

对于多间客房的平均每晚费用,请使用 nightlyRatesPerRoom 提供的值。

针对 minorRev=29 及更高版本返回。
ChargeableNightlyRates.NightlyRate 对象

提供请求住宿期间一晚的房价。

指示是否存在促销房价、基本房价以及应用促销后的房价(如果适用)。仅包含属性。

对于多间客房请求,该值是所有客房每晚费用的平均值。EAN 建议使用新的每间客房 ChargeableNightlyRates 数组来显示多间客房价格。

对于 minorRev=28 及更低版本的多客房请求,此元素仅提供第一间客房的房价,而不是平均房价。

属性:

promo 布尔型 指示是否为此晚房价应用了促销价。
rate 字符串 应用促销价(如果有)后的每晚房价。
baseRate 字符串 应用促销价(如果有)前的每晚房价。
ChargeableNightlyRates.
ConvertedNightlyRates
对象 转换为客户请求的货币后的房价信息。仅当请求的货币不可用于酒店计费或在客户的市场区域内不可用于计费时返回。包含与 ChargeableNightyRates 相同的属性。针对 minorRev=29 及更高版本返回。
RateInfos RateInfo 的容器 包含为各间客房提供详细房价信息的 RateInfo 元素的数组。

如果您使用的是在 minorRev=6 或更早版本上运行的旧集成,返回的 RateInfo 将没有 RateInfos 容器。
RateInfos.RateInfo 对象 包含单个客房在多个不同对象和各个值中的所有房价信息。

属性:
priceBreakdown布尔型 指示是否包含完整价格细分,包括要收取的税和总价。
promo 布尔型 指示返回的房价是否为促销房价。
rateChange 布尔型 指示房价是否至少与住宿期间某一晚的房价不同。
RateInfo.cancellationPolicy 字符串 酒店的取消政策。必须显示。
RateInfo.CancelPolicyInfoList 数组 取消政策的详细细节,通常是确定罚款期的时间和对取消收取的罚款。
查看 CancelPolicyInfo 数组的详细信息
RateInfo.nonRefundable 布尔型 确认在客房回复中返回的值。如果在成功预订回复中返回 true,则收费金额为最终金额。仅用于 Expedia Collect 酒店。
RateInfo.ChargeableRateInfo 对象 此对象的属性包含要为预订收取的绝对总价以及房价平均值和总计。对象中的节点提供有关各晚房价和附加费的详情。

属性:
total 字符串 要为预订收取的所有每晚房价、税和附加费的总计。这是必须显示给客户的总计值,包含在预订请求中。
surchargeTotal 字符串 Surcharges 数组中 TaxAndServiceFeeExtraPersonFee 的总和。
nightlyRateTotal 字符串 此对象中包含的 nightlyRatesPerRoom 数组中所有值的总和。
maxNightlyRate 字符串 所有返回房价的最高每晚房价
currencyCode 字符串 所返回房价的货币代码
commissionableUsdTotal 字符串 用于计算合作伙伴佣金的金额,以美元为单位。每晚房价总计减去附加费。
averageRate 字符串 应用任何促销值的所有每晚房价的平均值,不含附加费。
averageBaseRate 字符串 未应用任何促销值的所有每晚房价的平均值,不含附加费。如果没有促销,返回的值将与上一值相同。
ChargeableRateInfo.nightlyRatesPerRoom 数组 NightlyRate 数组的容器。具有 size 属性,用于指示数组中的节点数,这将与请求中的晚数对应。按照住宿日期的顺序相继返回房价。
nightlyRatesPerRoom.NightlyRate 不适用 详细指明请求住宿期间一晚的房价。指示是否存在促销房价、基本房价以及应用促销后的房价(如果适用)。仅包含属性。

属性:
promo 布尔型 指示是否为此晚房价应用了促销价。
rate 字符串 应用促销价(如果有)后的每晚房价。
baseRate 字符串 应用促销价(如果有)前的每晚房价。
RateInfo.promoType 字符串 指示返回的任何促销是特定于移动设备的促销还是标准促销。对于移动促销返回 Mobile,对于其他所有促销返回 Standard
为了返回移动促销,您必须通过适当的 customerUserAgent 字符串标识您的移动网站或应用。
RateInfo.depositRequired 布尔型 指示预订时是否需要押金以确保预订的安全。
RateInfo.rateType 字符串 指示返回的房价是通过 EAN 预付还是住宿完成后在酒店支付。对于预付可订空房,返回值 MerchantStandard,对于住宿后支付则不返回任何值。
ChargeableRateInfo.Surcharges 数组 Surcharge 数组的容器。该数组逐个列出各个附加费,这些附加费组成了为 surchargeTotal 返回的值。具有 size 属性,用于指示数组中的节点数。
Surcharges.Surcharge 不适用 详细说明单个附加费的金额和类型。仅包含属性。

属性:
amount 字符串 特定附加费的金额
type 字符串 附加费的名称。
可能的值:
  • TaxAndServiceFee
  • ExtraPersonFee
  • Tax
  • ServiceFee
  • SalesTax
  • HotelOccupancyTax

只有 TaxAndServiceFeeExtraPersonFee 会加到 surchargeTotal 中。所有其他值都是 TaxAndServiceFee 值的各个组成部分。


注意:SalesTaxHotelOccupancyTax 附加费类型必须按纽约州法律显示。在最终价格明细中单独显示这些值。
RateInfo.HotelFees 数组

该元素细分为酒店收取的某些税费,这些税费不在 Surcharges 数组中另行专门详细说明。

此元素中的所有值由酒店在访客入住或退房时收取。这些不是在预订时收取的任何费用的组成部分。

在填充时,使用此元素满足主要搜索引擎和聚合器要求的房价/税/费用格式。

请注意,返回的任何费用为整个预订的总计值,包括每晚或每间客房的费用。示例:每晚 10 美元,住 4 晚,则将显示总费用 40.00

包含 size 属性,以表示包含的费用数。

HotelFees.HotelFee

包含用于单项费用的说明、金额和货币的属性。

详细说明任何 VAT、州/城市税、度假胜地费用或任何其他无法合理避免的收费的总计

使用由 ChargeableRateInfocurrencyCode 属性指示的可预订货币返回费用。

属性:

description 字符串 费用的类型,例如 VAT 或度假胜地费
amount 字符串 费用的总计值


ValueAdds ValueAdd 的容器 包含预订附带的所有增值项目。具有 size 属性,用于指示各个增值项目数。

minorRev=28 或更高版本中提供。
ValueAdds.ValueAdd 数组

包含 description 元素,说明为指定客房和房价提供的各项免费服务,例如免费早餐或无线上网。

minorRev=28 或更高版本中提供。

ConvertedRateInfo 对象 转换为客户请求的货币后的房价信息。仅当结算货币和转换货币不同时返回,即酒店不接受客户请求的货币时。包含与 ChargeableRateInfo 相同的属性。
该对象中返回的值不可预订。尝试用转换的值预订会导致错误。
RoomGroup 对象 在请求中发送的 RoomGroup 对象的内容应用到提供的房价时,确认这些内容。