中国航信酒店平台接口开发指南.docx
中国航信酒店平台接口开发指南V1.0.1中国民航信息网络股份有限公司2010年6月变更记录DateVersionDescriptionAuthor2010/061.0.0版本发布杨同波2010/061.0.1概述中增加了业务建议；hotelBE接口参考文档扩展房健2011/041.0.2增加了对缓存接口的补充描述房健目录变更记录21概述42开发步骤52.1申请使用接口的帐号：52.2对酒店接口进行开发的步骤：62.2.1阅读hotelbe接口文档,熟悉酒店的相关业务知识62.2.2设计本地表结构，缓存酒店的信息62.2.3 接收hotelce的酒店消息通知62.2.4 查询通知消息73技术支持114 参考文档141概述对于需根据自己业务规则调整数据的渠道，需采用缓存数据+动态查询预订的机制。首先，静态信息（如城市列表、酒店名称、ID等内容）和动态信息（如价格、房态等信息）通过缓存数据接口定期获得（如每周定时获取一次，更新到渠道本地数据库中）；其次，查询实时价格和预订等通过HotelBE接口完成；最后，异步的变价等通知信息需渠道建立通知监听服务接收HotelCE通知消息。本文档描述了中航信平台酒店接口开发指南,内容涉及平台相关的多个系统。平台接口后台应用通过MQ服务提供，UTF-8编码格式。客户通过DirectLink统一访问地址，可以访问平台酒店的多个应用接口。每条指令都包括两部分：请求和返回，都有统一的XML格式，请求指令以<OTRequest>为根节点，返回指令以<OTResponse>为根节点。指令的具体格式请参照不同应用的相关接口文档。l 外网测试服务地址：http:/202.106.139.49:9090/directlink/tbeController.do l 生产服务地址： 提交指令均以httpPost请求的方式，参数名为request，即将请求XML串放到request参数中。UTF-8编码格式。每个应用的接口指令通过其中的application元素区分该指令所要访问的平台应用，每条指令的application必须填写正确，否则请求的指令不能被相应的应用所处理，application区分大小写。本文涉及三个应用：l hotelcache:缓存接口，提供给平台渠道缓存酒店数据。l hotelbe：交易接口，提供给平台渠道查询预订酒店。l hotelce：通知接口，提供给酒店发送相关信息给平台，同时平台会将酒店相关信息发给特定的渠道。另外，需要注意的是，由于业务可能会有扩展，在新接口的基础上会增加个别字段，而一些第三方插件在从xml到对象转换时，对新增加字段的解析有可能会出现问题，所以在开发时，对请求的返回结果的解析最好采用逐级逐节点的解析，尽量不要采用第三方插件把xml转换成对象，否则由此产生的问题，需要渠道端再次修改才能适用！2开发步骤您可以通过以下步骤使用中航信的酒店平台接口：2.1申请使用接口的帐号：您需要向分支申请使用接口，获得申请接口的认证信息。（1） 申请成为TravelHub平台渠道航旅通的Office已经默认作为平台的渠道。渠道code等同于officeCode（2）申请接口认证信息申请认证信息需要说明：l 开通测试还是生产系统申请流程： 航信各分支机构处填写<<酒店预订技术接口(hotelbe)申请单>>，分支机构业务负责人签字后发送传真至010-82861705，并发申请单电子版至chenxing 。总部收到传真领导签字审核通过后三个工作日内开通接口，并将接口认证信息发送到申请单中的负责人邮箱。（3）认证信息的格式接口的认证信息放在指令的<IdentityInfo >元素中.如下：<IdentityInfo><OfficeID>代理Office号</OfficeID><UserID>用户名</UserID><Password>用户密码</Password><Role>角色</Role></IdentityInfo>该认证信息要放在接口指令中，directLink会对每一条请求指令进行权限验证。2.2对酒店接口进行开发的步骤：2.2.1阅读hotelbe、数据缓存等接口文档,熟悉酒店的相关业务知识HotelBE是TravelHub平台面向下游渠道的实时交易接口，主要供渠道通过单酒店查询、预订等指令和平台就具体酒店动态数据、订单等信息进行交互。HotelBE接口技术文档中着重讲了指令的格式和调用方式，技术实现上相对简单。开发接口前了解指令中每个元素的含义，熟悉酒店预订相关的业务知识是非常必要的。参考文档: <<中国航信HotelBE数据缓存接口描述>>、<< 调用HotelBE推荐方案>>、<< HotelBE接口文档>>2.2.2设计本地表结构，缓存酒店的信息 由于酒店的信息量大，不仅包括酒店的静态信息，例如名称、地址、描述、电话、邮编、传真、行政区域、地标、房型描述等，而且包含动态信息，例如房型价格、配额、担保政策、预订政策等。因此接口客户必须对酒店的信息进行本地缓存，以提高客人的查询的速度和效率。客户需在熟悉业务的基础上，结合接口文档设计本地的表结构，缓存酒店的所有信息。本地化缓存后，客户可以自己本地设置酒店的促销级别，灵活地展现客人查询后酒店的展示顺序和必要的信息。利用HotelBE数据缓存接口中的酒店信息查询、酒店房价信息查询等指令（具体参考中国航信HotelBE数据缓存接口描述），客户可以把查到的酒店信息缓存在本地数据库中。2.2.3 接收hotelce的酒店消息通知本地话缓存数据后，客人在客户网站的酒店查询操作都是查询本地的数据库。当酒店的信息发生变化时，酒店会发消息给平台，平台会给特定的渠道发送消息通知。客户在收到消息通知后，解析收到的XML，并对本地的数据进行更新。我们这里发送的形式是：渠道提供的消息接收地址?messageXML=（消息XML串）&msgID=（消息ID）例如：l 房型可用性通知：酒店可能会对关闭某些房型，或者上线销售新的房型。l 房价通知：酒店可能调整房型的价格。l 政策通知：酒店可能调整预订或者担保等政策。消息通知的类型和具体格式含义，请参照hotelce相关文档。2.2.4 查询通知消息某些情况下，可能导致客户没有收到必要的信息，而导致本地数据没有及时更新，例如：l 客户的消息处理服务中断不可用l 网络原因导致消息丢失或者不可到达因此，客户可以调用指令查询某个时间段或符合一定条件的消息，由于消息的数量较大，我们可能对查询的条件进行限制，以减小对系统的压力，提高传输效率。代理可发送消息查询指令查询某个时间段的所有通知消息，这样可以避免有些消息没有收到导致的数据同步不一致的问题。代理通过发送httpPost请求，把查询的指令放到名为request的参数中。调用方法等同于调用HBE主动查询指令的方法。生产请求地址格式：测试请求地址：http:/202.106.139.49:9090/directlink/tbeController.do?request=.2.2.4.1通知消息ID查询指令通过该指令查询一段时间内的通知消息的ID示例：<OTRequest><TransactionName>QueryNotifyMsgIDRQ，固定值，必填</TransactionName><Header><Application>notify，固定值，必填</Application></Header><IdentityInfo>接口认证信息 <OfficeID> office号</OfficeID> <UserID> userid</UserID> <Password> password</Password></IdentityInfo><QueryNotifyMsgIDRQInfo> <BeginTime>起始时间，YYYYMMDDTTMM，例如201006040800</BeginTime> <EndTime>终止时间，YYYYMMDDTTMM，例如201006042459</EndTime> <MsgName>消息名称</MsgName> < MessageType></ MessageType > </QueryNotifyMsgIDRQInfo></OTRequest>返回消息格式：<OTResponse><TransactionName>QueryNotifyMsgIDRS</TransactionName><Header/><IdentityInfo/> <Code>20000</Code><Description>success</Description><MsgInfos Number="消息总数"><MsgId>消息ID,可重复元素</MsgId></ MsgIDInfos ></OTResponse>l <Application>notify</Application>为必填项l <TransactionName>QueryNotifyMsgIDRS</TransactionName>为必填项l 查询限制：起始时间必须是同一天。2.2.4.2通知消息查询指令 通过该指令查询一段时间内的通知消息示例：<OTRequest><TransactionName>QueryNotifyMsgRQ</TransactionName><Header><Application>notify</Application></Header><IdentityInfo>接口认证信息 <OfficeID> office号</OfficeID> <UserID> userid</UserID> <Password> password</Password></IdentityInfo><QueryNotifyMsgRQInfo><MsgId>消息ID</MsgId> <BeginTime>起始时间，格式YYYYMMDDTTMM</BeginTime> <EndTime>终止时间，格式YYYYMMDDTTMM</EndTime> <MsgName>消息名称</MsgName>< MessageType >消息类型</ MessageType > </QueryNotifyMsgRQInfo></OTRequest>l <Application>notify</Application>为必填项l 若MsgId不为空,则按照消息ID查询消息，其他查询条件无效n MSGID是消息的ID，是唯一区分消息的标识。n Hotelce的消息ID: 日期(8位，YYYYMMDD)_服务编号(6位数字)_CE_数字序号(6位数字)。例如20100730_202124_CE_008690表示2010年7月30日服务号为202124的通知服务生成的第8690条hotelce消息。同一天可能有多个服务号，一般为2个服务，同一个服务每天发送的消息数字序号从000001开始递增排列。l 时间跨度为10分钟，即查询时间段为10分钟。查询时间的分钟位只能是10的倍数，例如查询2010年月30日11点10分到2010年月30日11点20分的消息。BeginTime 为201003301110，EndTime为201003301120l MsgName 要查询的通知消息类别名称，可取值及表示含义如下：Ø TransactionName为指令名称，例如SP_HotelOrderStatusNotifRQ；当取值为OldICSMessage时查询老HBE的房价类通知消息Ø < MessageType >消息类型</ MessageType >，该元素查询老HBE接口的通知消息时用到；查询hotelce通知消息时取值为空。返回消息格式：<OTResponse><TransactionName>QueryNotifyMsgRS</TransactionName><Header/><IdentityInfo/> <Code>20000</Code><Description>success</Description><MsgInfos Number="消息总数"><MsgInfo><MsgId>消息ID</MsgId><Time>消息时间</Time><MsgTsName>消息名称，例如OldICSMessage</MsgTsName><MsgContent>消息内容</MsgContent></MsgInfo></MsgInfos></OTResponse>返回示例：<OTResponse><TransactionName>QueryNotifyMsgRS</TransactionName><Header/><IdentityInfo/> <Code>20000</Code><Description>success</Description><MsgInfos Number="3"><MsgInfo ><MsgId>20100411135527_notify_85688800</MsgId><Time>20100411135527</Time><MsgTsName>OldICSMessage</MsgTsName><MsgContent><HotelAvailNotifyRQ><HotelAvailMessage><PropertyID>1EAJQ</PropertyID><RoomTypeCode>DB003</RoomTypeCode><BeginDate>20100428</BeginDate><EndDate>20100428</EndDate><Availability>-3</Availability><Remark></Remark><MessageType>HA</MessageType></HotelAvailMessage></HotelAvailNotifyRQ></MsgContent></MsgInfo><MsgInfo><MsgId>20100411135528_notify_5581345</MsgId><Time>20100411135528</Time><MsgTsName>OldICSMessage</MsgTsName><MsgContent><HotelAvailNotifyRQ><HotelAvailMessage><PropertyID>1EAJQ</PropertyID><RoomTypeCode>DB003</RoomTypeCode><BeginDate>20100428</BeginDate><EndDate>20100428</EndDate><Availability>-3</Availability><Remark></Remark><MessageType>HA</MessageType></HotelAvailMessage></HotelAvailNotifyRQ></MsgContent></MsgInfo><MsgInfo><MsgId>20100411135530_notify_18507021</MsgId><Time>20100411135530</Time><MsgTsName>OldICSMessage</MsgTsName><MsgContent><HotelAvailNotifyRQ><HotelAvailMessage><PropertyID>1EAJQ</PropertyID><RoomTypeCode>DB001</RoomTypeCode><BeginDate>20100428</BeginDate><EndDate>20100428</EndDate><Availability>-3</Availability><Remark></Remark><MessageType>HA</MessageType></HotelAvailMessage></HotelAvailNotifyRQ></MsgContent></MsgInfo></MsgInfos></OTResponse>3技术支持相关的业务问题请致电航旅通客服电话400-810-9191。hotelbe接口技术支持以电子邮件为主，电话只处理紧急问题，比如下单全部失败，接口无法访问等紧急严重问题，其他问题请转邮件咨询。我们承诺邮件技术支持三个工作日内给回复。咨询邮件请参照下述的格式，以提高问题解决的效率。邮件发送至 yjsun ;邮件技术咨询问题描述参照以下格式：使用hotelbe接口的用户认证信息：问题描述（文字性说明）：出现问题的接口访问地址，请求串和返回串一个技术咨询邮件示例：使用接口的用户认证信息： <IdentityInfo> <OfficeID>NATEST</OfficeID> <UserID> NATEST 00C</UserID> <Password>123</Password> </IdentityInfo>2: 问题描述：调用单酒店查询接口查不到酒店信息3： 出现问题的请求串和返回串：访问地址: 请求串：<OTRequest><Header><SessionID></SessionID><Invoker></Invoker><Encoding></Encoding><Locale></Locale><SerialNo></SerialNo><TimeStamp> </TimeStamp><Application>hotelbe</Application></Header><HotelAvailRQ> <HotelAvailCriteria> <HotelSearchCriteria> <HotelRef HotelCode="SOHOTO0014"/> </HotelSearchCriteria> <RatePlanCandidates> <RatePlanCandidate> <VendorsIncluded> <Vendor VendorCode="SOHOTO"/> </VendorsIncluded> </RatePlanCandidate> </RatePlanCandidates> <StayDateRange CheckInDate="2010-07-13" CheckOutDate="2010-07-18"/> </HotelAvailCriteria></HotelAvailRQ> <TransactionName>TH_HotelSingleAvailRQ</TransactionName> <IdentityInfo> <OfficeID>NATEST</OfficeID> <UserID>CHENJUN</UserID> <Password>123</Password> </IdentityInfo> <Source> <OfficeCode>NATEST</OfficeCode> </Source></OTRequest> 返回串： <OTResponse><TransactionName> TH_HotelSingleAvailRS</TransactionName> <ErrorInfo> <Code>00001</Code> <Description>服务器没有响应</Description> </ErrorInfo></OTResponse>4 参考文档HotelBE接口文档HotelCE接口文档HBE二类指令（老HBE通知消息）
