艺龙酒店API接口文档

1、艺龙网信息技术（北京）有限公司艺龙酒店api接口文档文档历史：文档整理文档版本日 期说明李继东1.1.02010-11-10在elong hotel组提供的文档基础上进行了重新整理李继东1.1.12011-1-081、增加了即时确认信息接口（第五部分第3个的instantconfirm接口）2、酒店静态文件中增加的酒店特殊信息提示（静态文件hotel_cn.xml中的availpolicy字段）3、启用了新的api测试环境地址4、酒店的部分含早产品在api接口中的展示（gethotellist接口和gethotelorderlist接口）李继东1.1.22011-2-1修改了bookingru

2、le返回值说明李继东1.1.32011-2-281、优化静态数据文件更新方式，提供新版的静态文件更新方式（见第三部分静态文件更新）2、增加了多订单号查询接口（见第五部分第6接口）赵春风1.1.42011-03-071. 完善开发流程说明2. 修订预订规则，担保规则，附加服务，促销规则等规则描述一、概述3二、基本开发步骤3三、静态数据31、通过hotelid调用酒店信息文件更新方式42、打包下载更新方式43、静态文件字段说明5四、代理商登录接口login11五、api动态接口121. 酒店价格查询接-gethotellist132. 提交订单接口 submithotelorder243. 获取订

3、单及时确认信息接口instantconfirm304订单查询接口 gethotelorderlist325. 根据orderid获取订单gethotelorderdetailbyorderid366、根据订单号id获得多个订单信息447. 订单取消接口 cancelhotelorderbyid49六、接口返回的错误信息50七、api测试工具介绍51一、概述 api接口是艺龙提供给合作方使用的酒店数据仓库，接口提供两部分数据，一部分是api接口静态数据，此数据主要包含酒店的基础信息等内容；另外一部分为动态数据，主要包括艺龙酒店价格的实时查询、订单实时提交、酒店订单查询、订单详细信息查询、订单取消

4、功能。 注意：由于订单变更涉及到太多组合条件，api接口暂时不提供订单变更功能；如需要进行酒店订单变更，可以先取消原来订单，然后再重新下取新单。 在使用艺龙api接口进行接入前，建议先在本地建立酒店信息、地理位置信息等数据库，把酒店静态数据、地理位置静态数据通过程序解析到本地数据库，然后通过各个酒店的cityid、hotelid（酒店id）、cityid等查询条件来查看酒店的实时价格做订单处理操作。 开发时需要注意如果某些节点没有数据，生成请求xml时该节点也需要包含，不能省略，否则接口会返回错误二、基本开发步骤1、 向艺龙销售人员索取api测试环境账号和说明文档，做接口接入工作前的准备，同时

5、提供上线后预期的搜索量和成单量，并发数等相关性能指标， 艺龙会根据实际情况进行上线前的系统准备，准备时间一般在2周左右2、 下载api接口文档静态数据（最好采用flashget、迅雷等下载工具下载），通过程序来解析数据格式，并把解析到的数据导入到本地（或服务器）上的数据库中3、 确定开发语言及需要调用的动态接口，并阅读动态接口文档参数，对通过动态接口调用到的数据规划自己页面的展示方式4、 通过艺龙api测试环境调试接口（仅使用部分接口就调试部分动态接口），对所需要的接口争取均能调试通过，需要重点测试各种场景下的担保订单(首晚/全额，日期担保/房量担保)， 不同预订规则下的预订场景，否则上线后可

6、能会产生问题，需要配合艺龙方进行不同的场景测试，直至得到艺龙销售人员验收通过5、 测试环境验证通过后，向艺龙销售人员申请开通api正式环境账号， 艺龙销售人员确认系统功能测试完毕，艺龙系统接入准备完毕， 排定双方的上线日期后开通生产环境帐户6、 更改代码中api正式环境http地址以及api账号，把已开发好的系统切入到正式环境，在正式环境下一两个订单做简单测试（测试订单时请联系相关销售人员，测试场景需涵盖主要担保规则和预订规则，订单入住日期要在测试日期推后较长时间，以保证可以取消和不产生担保扣款，测试完的订单要及时进行取消, 否则产生的赔款由代理商自己负责）7、 测试正常后，把自己网站或系统接

7、入正式api接口上线监控2-3周，发现问题请及时和对口销售或艺龙技术支持人员反馈三、静态数据目前，静态数据文件的初始化更新支持两种方式，一种为通过hotelid调用酒店信息文件更新方式，一种为打包下载更新方式（此种方式将逐步放弃不用） 1、通过hotelid调用酒店信息文件更新方式（1）、api静态数据文件包含以下： hotellist.xml 提供了艺龙所有酒店的hotelid、酒店中英文名称、上线时间、到期时间等信息，具体字段定义见“静态文件字段说明”，下载地址为：http:/114-/xml/hotellist.xml 每一家酒店均有一个xml文件（以hotel

8、id作为文件名） 提供了艺龙每一家酒店详细的酒店基础信息数据，包括酒店名称、id、地址、介绍等内容，具体字段定义同hotel_cn.xml文件中的字段定义，下载地址为：中文版本为：http:/114-/xml/perhotelcn/hotelid.xml英文版本为：http:/114-/xml/perhotelen/hotelid.xml 获取指定酒店信息请替换上面链接中的hotelid其他静态数据文件：包括geo_cn.xml(英文版对应geo_en.xml)、hotelbaseinfocodes_cn.xml(英文版对应hotelbase

9、infocodes_en.xml)同打包下载更新方式静态文件（2）、静态数据文件的初始化及更新 初始化：首先下载hotellist.xml文件到本地，通过hotellist文件解析出每家酒店的hotelid，然后通过调用每一家酒店的xml文件把酒店静态信息解析到本地数据库 更新：首先下载hotellist.xml文件到本地，通过hotellist.xml文件解析出艺龙到期酒店的hotelid，然后删除本地数据库此家酒店的基础信息数据；再通过hotellist.xml文件解析出艺龙新签酒店的hotelid，再调用每一家新签酒店的xml文件把酒店静态信息解析到本地数据库 （3）、数据更新频率 本更

10、新频率为hotellist.xml、各个酒店单独的xml文件为每天更新一次；而geo_cn.xml、hotelbaseinfocodes_cn.xml则为每周更新一次（更新时间为每周六） 2、打包下载更新方式（1）、api静态数据文件包含三个， 三个文件均以静态xml文件方式来提供，其中hotel_cn.xml提供的每一家酒店的基础信息，包括酒店名称、id、地址、介绍等内容geo_cn.xml提供了每一城市的地理位置信息，包括行政区、商业区等内容hotelbaseinfocodes提供了接口中部分参数字典信息 三个静态文件下载地址为：http:/114-/xml/文件

11、名中文版本文件名为 geo_cn.xml, hotel_cn.xml, hotelbaseinfocodes_cn.xml英文版本文件名为 geo_en.xml, hotel_en.xml, hotelbaseinfocodes_en.xml（2）、静态数据文件的更新 由于静态文件日常更新较慢，并且数据变化比较小；因此，艺龙系统将在每周六凌晨2点对此三个静态文件进行一次更新，更新方式为累积更新。 对于静态文件的更新，艺龙建议合作方每一周或两周更新一次，更新时可以先清空本地数据库，然后进行插入操作。 由于这三个文件中，hotel_cn.xml比较大（160mb-200mb之间），建议先用下载工具

12、（迅雷、flashget）把此文件下载到本地，然后通过程序解析的方式把此文件解析到本地数据库。 3、静态文件字段说明 、hotellist.xml文件名称描述备注addtime此酒店签约时间日期格式，带时间deltime此酒店删除作废时间日期格式，带时间hotel_id酒店id可据此去perhotelcn文件夹下取酒店信息（peihotelcn下文件命名方式：hotel_id+.xml）hotel_name酒店中文名hotel_name_en酒店英文名isreserve此酒店是否可用0表示可用，1、 2表示酒店已删除modifytime此酒店最近一次修改时间暂时不生效 、hotel_cn.xm

13、l文件（示例文件见附件） 名称描述备注id酒店id八位数字来表示dateupdated酒店最新更新时间name酒店名称address酒店地址zip酒店邮编category酒店星级-1，0均代表经济型酒店typology酒店类别目前只有hroomnumber酒店总房间数量availpolicy酒店特殊信息提示activationdate暂时不用usersrating用户评分,目前没有赋值elongranking酒店在艺龙的排序，暂时不用templatetype暂时不用translations暂时不用doublepricemin暂时不用doublepricemax暂时不用currency暂时不用l

14、at酒店所在位置的纬度用于位置搜索lon酒店所在位置的经度用于位置搜索country酒店所在国家region酒店区域暂时不用，空值province酒店所在省份id表示，省份名称和geo中province关联city酒店所在城市id表示，城市名称和geo中cityid关联businesszone酒店所在商业区id表示，商业区名称和geo中commerciallocation关联district酒店所在行政区id表示，城市名称和geo中district关联propertyurl酒店在网站中的详细页urlintroeditor酒店介绍信息对酒店的详细介绍ccaccepted

15、可支持的信用卡支持的信用卡为：银联、jcb、mastercard、visadescription酒店描述对酒店的简单描述images酒店图片信息此为一节点，节点字段解释见下表airportpickupservice酒店免费接机信息此为一节点，节点字段解释见下表generalamenities酒店服务设施信息此为一节点，节点字段解释见下表roomamenities房间服务设施信息此为一节点，节点字段解释见下表recreationamenities休闲服务设施信息此为一节点，节点字段解释见下表conferenceamenities会议服务设施信息此为一节点，节点字段解释见下表diningameni

16、ties餐饮服务设施信息此为一节点，节点字段解释见下表trafficandaroundinformations周边交通信息此为一节点，节点字段解释见下表surroundingcommerces周边商务信息此为一节点，节点字段解释见下表surroundingrestaurants周边餐饮信息此为一节点，节点字段解释见下表surroundingattractions周边景致信息此为一节点，节点字段解释见下表surroundingshops周边购物信息此为一节点，节点字段解释见下表featureinfo酒店特色信息此为一节点，节点字段解释见下表roominfo酒店房型信息此为一节点，节点字段解释见下

17、表phone酒店电话(前台)fax酒店传真(前台)openingdate酒店开业日期renovationdate酒店装修日期landmarks酒店附近标志物 id表示， 标志物名称对应geo中landmarklocations列表节点包含多个子节点，节点对应字段说明为：名称描述备注imageurl图片url地址imgtype图片类型？title图片标题imgnum 节点下对应字段说明为：名称描述备注extensiondata暂时不用enddate免费接机结束日期endtime接机每天结束时间startdate免费接机开始日期starttime接机每天开始时间节点下对应字段说明为：名称描述备注e

18、xtensiondata暂时不用amenitysimplelist服务设施列表overview酒店服务设施概述节点下对应字段说明为：名称描述备注extensiondata暂时不用amenitysimplelist服务设施列表overview房间服务设施概述节点下对应字段说明为：名称描述备注extensiondata暂时不用amenitysimplelist服务设施列表overview休闲服务设施概述节点可能包含多个子节点，对应字段说明为：名称描述备注amenitylist会议室列表包含多个子节点overview酒店会议室设施概述子节点对应字段说明为：名称描述备注extensiondata暂时不

19、用amenitydetail会议室介绍amenityname会议室名称节点节点可能包含多个子节点，对应字段说明为：名称描述备注amenitylist餐厅列表包含多个子节点overview酒店餐厅设施概述子节点对应字段说明为：名称描述备注extensiondata暂时不用amenitydetail餐厅介绍amenityname餐厅名称节点对应字段说明为：名称描述备注extensiondata暂时不用overview周边交通信息概述trafficandaroundinformationlist周边交通信息列表的子节点可能包含多个节点，其对应字段说明为：名称描述备注extensiondata暂时不用

20、distances到酒店距离name周边交通名称note备注信息timetaken所用时间transportfee交通花费费用transportations乘坐的交通工具参见hotelbaseinfocodes_cn.xml信息节点包含多子节点，节点对应字段说明为：名称描述备注extensiondata暂时不用distances到酒店距离name周边商业区名称note备注信息timetaken所用时间transportfee交通花费费用transportations乘坐的交通工具参见hotelbaseinfocodes_cn.xml信息节点包含多子节点，节点对应字段说明为：名称描述备注exte

21、nsiondata暂时不用description餐厅描述distances到酒店距离name周边餐厅名称节点包含多子节点，节点对应字段说明为：名称描述备注extensiondata暂时不用distances到酒店距离name周边餐厅名称节点包含多子节点，节点对应字段说明为：名称描述备注extensiondata暂时不用description商业区描述distances到酒店距离name商业区名称节点对应字段说明为：名称描述备注hotelid酒店iddrivingguide驾车指南propertyotherhightlights酒店其他特色propertyamenitieshightlights

22、服务设施特色locationhighlights地理位置特色overview酒店特色信息概述节点包含多个子节点，节点对应字段说明为：名称描述备注roomtypeid房型idroomname房型名称roomtypenum房型数量area房间面积floor房型所在的楼层hasbroadband是否有宽带0表示无宽带，1 表示有宽带hasbroadbandfee宽带是否收费 0表示免费，1 表示收费beddescription房间描述包括大床、双床、宽带等一类描述note备注节点包含多个子节点，节点对应字段说明为：名称描述备注extensiondata暂时不用hotelid酒店idlandmarki

23、d酒店附近标志物idlandmarkname酒店附近标志物名称landmarknameen酒店附近标志物英文名称、geo_cn.xml文件说明名称描述备注idgeoid,从1开始，依次加1country国家provincename省份名称provinceid省份idcityname城市名称citycode城市idproperties该城市下的有效酒店个数 url该酒店在网站上的搜索列表urldistricts行政区节点location列表commerciallocations商业区节点location列表landmarklocations城市标志物节点location

24、列表节点对应字段说明：名称描述ididname名称、hotelbaseinfocodes_cn.xml文件说明 hotelbaseinfocodes_cn.xml包含以下字典信息： 星级代码 担保类别代码（目前api接口只支持“不担保”和“信用卡担保”两类） 订单状态代码 客人类别代码 支付方式代码（目前api接口只支持“前台自付”方式） 货币代码 确认方式代码 语言代码 性别代码 证件类型代码 订单取消原因代码 交通工具 酒店类别（目前静态文件中只有“h”类型） 房态类别代码 增值服务代码 预订规则类别代码 促销规则代码 取消规则类型代码四、代理商登录接口login 代理商登录接口主要是为获

25、取到数字凭证logintoken，logintoken是访问其他api动态接口的必需参数。 动态接口的访问地址为：正式环境:http:/114-/northboundservice/v1.1/northboundapiservice.asmx 测试环境：98/northboundservice/v1.1/northboundapiservice.asmx 此接口输入参数为：字段类型描述是否可为空备注usernamestringapi登录账号名npasswordstringapi登录密码n 输入参数后，生成的requestion.x

26、ml请求如下： 0 username /必须填写 userpassword /必须填写 此接口输出参数为：字段类型描述可为空备注loginresult logintokenstring登录凭证y输出参数生成的response.xml如下： 0 /判断请求是否成功标志 2010-10-06t10:49:21.3432823+08:00 succeed /如果不成功，错误信息将在此字段列出 e1f0b736-f798-47ce-a798-993620bac4b8 /获取的logintoken数字凭证 2010-10-06t10:54:21.3432823+08:00/数字凭证logintoken的

27、有效时间 五、api动态接口 在调用api接口中，所有发送的请求数据（request.xml）都需要包含节点，此节点作为接口的数字验证字段。所有接受的数据（response.xml）都需要包含节点，此节点作为接口返回数据的状态信息。requesthead字段说明参数类型说明备注可否为空logintoken string访问凭证登录接口除外nlanguagestring接口语言cn:中文、en:英文， 大写字母nguidstring唯一标识id在submithotelorder接口中必须填写，并且不同的订单对应的guid不能相同， 否则不能正常成单。 如果成单出现超时再次提交相同请求，则guid

28、不需要改变，否则可能会出现生成重复订单问题，nversionstring版本号可省略ytestmodeint测试开关0-正式，1-测试，默认为0, 暂时不起作用yrequesthead节点内容 e1f0b736-f798-47ce-a798-993620bac4b8 /调用login获取的访问凭证 cn /请求数据的语言，cn-中文，en-英文 /可以为空，但在提交订单接口（submithotelorder）则需要填写不同的值，以进行不同订单的区分。如果不填，则无论下几张订单，所返回的订单号只有一个，且艺龙系统中下取成功的订单页只有一个。 /可以不填 0 /可以不填 responsehead字

29、段内容为：参数类型说明描述可否为空resultcodestring结果编号0-成功,1-失败nresultmessagestring结果信息错误信息或提示信息ytimestampdatetime结果生成的时间yyyy-mm-ddthh:mm:ss例如: 2009-01-14t16:50:20nresponsehead节点内容 0 /返回结果，0-请求成功 1-请求失败 2010-10-08t10:36:36.6428603+08:00 注意：所有接口的节点字段中，即是有些参数你不需要填写（比如），但在实例化中也需要保留此字段，并把此字段进行默认赋值(string类型为空，int类型为0，日期类

30、型为“0001-01-01 00:00:00”)1. 酒店价格查询接-gethotellist输入参数（gethotel condition）节点下字段说明为（红色字体代表是个节点数组）：字段类型描述默认值可为空备注gethotelcondition checkindatedatetime入住日期0001-01-01 00:00:00n日期有效，建议入住日期和离店日期不要超过20天 checkoutdatedatetime离店日期0001-01-01 00:00:00n日期有效，返回结果中不包含离店日期的价格信息，离店日期大于入住日期cityid string城市id空n1、酒店名称可为酒店名

31、称的一部分。2、城市id,酒店名称，酒店id至少有一个不为空， 如果hotelname不为空，cityid也不能为空。3、酒店id为多个时, id之间可用英文逗号分隔hotelnamestring酒店名称空nhotelidstring酒店id 空nroomtypeidstring房型id空y通过此两个字段可查询某个酒店的详细产品信息rateplanidintrateplanid0ystarcodestring星级代码空y参见星级代码信息starcodes，多个以英文逗号分隔highestrateint产品最高价格0y1、字段为0则不限价 2、如搜200元以下，则highestrate=200，

32、lowestrate=0 3、如搜600元以上，则highestrate=10000，lowestrate=600lowestrateint产品最低价格0ypositionmodecodestring位置查询模式0y0：不按位置搜索； 1：按矩形方式； 2：按点-半径方式startlongitudedecimal起始经度0y1、此5个字段作为地图搜索使用，在positionmodecode=2或3时，使用此字段2、radius字段的单位为：米startlatitudedecimal起始纬度0yendlongitudedecimal终止经度0yendlatitudedecimal终止纬度0yra

33、diusint半径0ydistrictidstring行政区id空y如果按照这3个查询，则城市id必须输入， id的具体数值从geo_cn.xml中获取commerciallocationidstring商业区id空ylandmarklocationidstring标志物id空yopeningdatedatetime开业日期0001-01-01 00:00:00y暂不支持，默认填写0001-01-01 00:00:00decorationdatedatetime装修日期0001-01-01 00:00:00y暂不支持，默认填写0001-01-01 00:00:00roomamountint房间

34、数量0y默认为1，暂不支持orderbycodestring排序标准空yelong：默认 star：按星级 price：按价格distance：按距离ordertypecodestring排序类型空yasc :升序desc:降序pageindexint分页页数0y默认从1开始maxrowsint最大返回记录数0y0或空表示不限制如果超过elong默认的最大记录数，则以elong设置为准，默认最大为20currencycodestring空rmb ：人民币 usd ：美元 hkd ：港元 mop ：澳元（暂不支持） sgd ：新币（暂不支持），此查询条件暂时不提供输出参数字段类型描述可为空备注h

35、otelcountint酒店个数n查询结果中返回的酒店个数hotels hotels包含n个hotel数组hotelhotel数组 hotelnamestring酒店名称n hotelidstring酒店idnstarcodestring星级代码n参见静态数据文件hotelbaseinfocodes_cn.xmlhoteladdressstring酒店地址n hotelinvstatuscodestring酒店房态n0-正常 1-部分日期满房，2-全部满房 lowestpricedecimal酒店最低价n roomsrooms下包含n个room数组，参见下面介绍 hotelpromotions

36、酒店活动节点节点包含多个子节点，节点对应字段说明为： roomn roomnamestring房型名称n roomtypeidstring房型idn roominvstatuscodestring房型房态n0-正常 1-部分日期满房，2-全部满房rateplansrateplan数组节点节点包含多个子节点，节点对应字段说明为： rateplan rateplanidintrpid艺龙在房型基础上把产品进一个细分，细分后的每一产品称为rateplan，简称rp rateplancodestringrp业务编码 rateplannamestringrp名称guesttypecodestring客人

37、类型代码参见静态数据hotelbaseinfocodes_cn.xml文件ratesnrp价格数组，参见下面介绍garanteerulesy担保规则数组，参见下面介绍bookingrulessy预订规则数组，参见下面介绍addvaluesy增值服务信息数组，参见下面介绍addvaluesdescriptiony增值服务信息描述，参见下面介绍drrrulesy产品促销规则数组，参见下面介绍hotelpromotionsy酒店促销活动数组，参见下面介绍节点对应字段说明为：rates 房价数组 totalpricedecimal总价 currencycodestring货币代码 taxesamoun

38、tint税费节点， 包含类型，价格，暂不使用 rate每日价格数组节点对应字段说明为： rate每日价格数组 datedatetime对应日期n假设你查询2010-10-5到2010-10-7价格，则对应rate展示3天（5，6，7）价格数据（rate） currencycodestring货币代码 invstatuscodestring每日房态n0-正常 1、2-全部满房 retailratedecimal门市价n memberratedecimal会员价格n预订酒店价格，返回-1代表此房无价，无价和满房都不能进行预订 addbedratedecimal加床价格y返回-1代表不能加床，0-免

39、费加床，大于0表示加床的费用节点节点包含多个子节点，节点对应字段说明为：garanteerules garanteerule garanteerulestypecodeint担保规则类型 1- 信用卡-日期担保2- 信用卡-房量担保， 房量担保时也有有效日期的限制，同时可能会并存客人到店时间的判断条件，不能只简单的校验房量，需要遍历检查rulevalues中的每个节点后进行综合判断 rulevaluesdictionaryentry规则的具体数据数组, 规则有几个参数，对应几个节点值 descriptionstring该条担保规则对应的描述，如果代理不想解析规则，可以直接在预定流程中展示该描述

40、节点对应字段说明为： rulevalues key对应担保条件字段n value对应担保条件值yrulevalue项说明：项示例值说明备注startdate2010-05-04 00:00:00需要担保开始日期1-入住日期2-在店日期3-预订日期举例：datetype为1表示当前订单的入住日期落在startdate 和 enddate之间，并且入住日期符合周设置时才需要判断其它条件是否担保，否则不需要担保 enddate2010-12-31 00:00:00需要担保结束日期datetype1担保条件日期判断基准weekset1,2,3,4,5,6,7周有效天数， 一般为周一到周日都有效， 判断

41、日期符合日期段同时也要满足周设置的有效周一对应为1，周二对应为2， 依次类推gage1信用卡担保 ,该字段目前可以忽略系统默认为1 isarrivetimevouch0是否校验到店时间 0为不校验到店时间1为需要校验到店时间当isarrivetimevouch为1时，arrivestattime、arriveendtime、istomorrow才有值arrivestattime18:00到店担保的开始时间arriveendtime6:00到店担保的结束时间istomorrow1到店担保的结束时间是否为第二天 0为当天，1为次日isroomcountvouch0是否校验房量 0为不校验房量条件，

42、1为校验房量条件当garanteerulestypecode为2时有效roomcount0担保的房间数,预定几间房以上要担保vouchmoneytype2担保金额, 1为首晚房费2为全额房费ischange1是否允许变更1为允许变更2为不允许变更changerule4担保规则条数，规则1、不允许变更取消 2、允许变更/取消,需在xx日yy时之前通知3、允许变更/取消,需在最早到店时间之前几小时通知4、允许变更/取消,需在到店日期的24点之前几小时通知当存在规则2、3、4时，需要查看daynum、hournum、timenum数据以及ischange当changerule=2时，需包含字段为：daynum2011-02-28几日对应规则3描述中 “允许变更/取消,需在xx日yy时之前通知” 中的xx日，yy时timenum18：00几时当changerule=3时，需包含字段为：hournum6几小时对应规则3描述中 “ 允许变更/取消,需在最早到店时间之前几小时通知” 中的几小时当changerule=4时，需校验字段为：hournum5几