携程网站联盟api平台.doc

携程网站联盟API平台2.0集成开发指南文件状态： 草稿 正在修改 正式发布文档编号：P-11096.2-09-02项 目 名：网站联盟II期-API2.0平台作 者：刘磊文 件 名：携程旅行网网站联盟API2.0集成开发指南.doc保密等级：审 核 人：批 准 人：最后更新时间：2012-7-11版权申明：本文件属于机密文件，所有权属于携程计算机技术（上海）有限公司。任何接触此件的人必须遵守以下规定：1 本文件及包含的内容均属于携程计算机技术（上海）有限公司资产。2 未经携程计算机技术（上海）有限公司的书面同意，任何人不得对本文件的全部和/或部分内容进行任何形式的复制或传播扩散。版本历史版本/状态作者审核人发布日期备注V0.1刘磊2012-5-4V0.2刘磊2012-5-7增加国际机票相关内容V0.3陈浩刘磊2012-5-81修改酒店搜索，可订检查，订单详情等契约及说明2更新错误代码V1.0盛凯刘磊2012-5-101增加度假API说明2请求列表中删除订单提交APIV1.1刘磊2012-5-111增加支付说明2增加静态文件下载地址V1.2刘磊2012-6-41修改酒店静态信息接口说明，修正请求样例中的错误V1.3徐驰唐春龙刘磊刘磊2012-6-111增加团购API相关说明2增加酒店API相关时间格式说明3增加酒店API价格计划促销活动说明V1.4王涛刘磊刘磊2012-7-111增加国内机票API说明2修正团购API请求类型说明V1.4刘磊2012-8-301OTA_HotelSearch和OTA_HotelRatePlan增加7天及香格里拉等酒店查询参数说明V1.5徐驰唐春龙2012-9-26整理最新的说明文档目录1. 引言81.1. 目的81.2. 读者对象81.3. 文档内部约定81.3.1. 文档字体约定81.4. 术语与缩写82. 方案概述92.1. 业务说明92.2. 业务流程112.3. API2.0平台介绍163. 数据格式203.1. 请求地址203.2. 请求类型203.3. 测试及正式访问243.3.1. 测试环境访问243.3.2. 生产环境访问243.4. 请求频次243.5. 签名原始串243.6. 签名算法253.6.1. MD5签名原理253.7. 接口介绍263.7.1. 用户 User263.7.1.1. 用户生成 OTA_UserUniqueID263.7.2. 酒店Hotel283.7.2.1. 静态文件下载283.7.2.2. 联通测试 OTA_Ping293.7.2.3. 酒店查询 OTA_HotelSearch313.7.2.4. 酒店静态信息查询 OTA_HotelDescriptiveInfo383.7.2.5. 价格计划查询 OTA_HotelRatePlan533.7.2.6. 价格缓存变化查询 OTA_HotelCacheChange653.7.2.7. 可订检查OTA_HotelAvail693.7.2.8. 订单生成 OTA_HotelRes813.7.2.9. 订单取消 OTA_Cancel983.7.2.10. 订单变化查询 OTA_HotelResNotif1023.7.2.11. 订单详情查询 OTA_Read1073.7.2.12. 酒店列表查询 D_HotelSearch1183.7.2.13. 酒店详情 D_HotelDetail1373.7.2.14. 酒店订单列表查询 D_HotelOrderList1663.7.2.15. 酒店订单详情查询 D_HotelOrderDetail1733.7.2.16. 酒店评价查询 D_HotelCommentList1793.7.3. 国内机票Flight1823.7.3.1. 静态文件下载1823.7.3.2. 国内机票查询 OTA_FlightSearch1833.7.3.3. 国内机票生成订单 OTA_FltSaveOrder1913.7.3.4. 国内机票取消订单 OTA_FltCancelOrder2013.7.3.5. 国内机票订单列表OTA_FltOrderList2033.7.3.6. 国内机票订单详情 OTA_FltViewOrder2083.7.3.7. 国内机票订单变更 OTA_GetStatusChangedOrders2183.7.4. 国际机票Flight2213.7.4.1. 静态文件下载2213.7.4.2. 国际机票查询 OTA_IntlFlightSearch2213.7.4.3. 机型信息查询OTA_FltGetCraftInfos2383.7.4.4. 城市查询 OTA_FltGetCityInfos2413.7.4.5. 机场查询 OTA_FltGetAirportInfos2443.7.4.6. 航空公司信息 OTA_FltGetAirlineInfos2463.7.5. 度假Vacations2503.7.5.1. 度假地址选择器 OTA_VacationAddressSelector2503.7.5.2. 度假城市列表（热门城市） OTA_VacationCity2523.7.5.3. 度假证件类型 OTA_VacationCredentialType2553.7.5.4. 度假配送方式 OTA_VacationDeliverType2573.7.5.5. 度假酒店 OTA_VacationHotels2613.7.5.6. 度假订单金额计算 OTA_VacationOrderAmount2693.7.5.7. 度假临时订单生成 OTA_VacationOrderCreate2713.7.5.8. 度假订单列表 OTA_VacationOrderList2993.7.5.9. 度假订单明细 OTA_VacationOrderInfo3043.7.5.10. 度假产品单选项 OTA_VacationOrderItem3183.7.5.11. 产品查询列表 OTA_VacationPackageList3473.7.5.12. 产品明细 OTA_VacationPackageInfo3553.7.5.13. 度假暂存订单详情 OTA_VacationTmpOrderInfo3673.7.5.14. 度假系统机票 OTA_VacationSysFlight3803.7.5.15. 度假可选项列表 OTA_VacationOrderOption3873.7.6. 支付3983.7.6.1. 在线支付3983.7.6.2. 支付流水查询 GetPaymentInfo4003.7.7. 团购4033.7.7.1. 团购产品列表查询GroupProductList4033.7.7.2. 团购产品详细查看 GroupProductInfo4073.7.7.3. 团购订单列表查询GroupOrderList4143.7.7.4. 团购订单生成 GroupCreateOrder4173.7.7.5. 团购券查询 GroupQueryTickets4203.7.7.6. 团购订单通知 GroupOrderChange4233.7.7.7. 团购产品通知 GroupProductChange4263.7.7.8. 团购券通知 GroupTicketChange4283.7.7.9. 团购券取消 GroupCancelTickets4314. 附录4334.1. FAQ4334.1.1. 问：我运行程序后怎么一直报错误代码：签名错误？4334.1.2. 问：我怎么得到联盟身份（Alliance）和站点密钥（Secretkey）？4344.1.3. 问：如果我只想使用酒店查询功能，然后跳转到CTRIP.com完成预订怎么办？4344.1.4. 问：<Error Type="12" ShortText="System error" Code="448">System error:no cache</Error>在什么情况下出现的？4344.1.5. 问：我想通过API2.0的OTA_HotelSearch接口查找某个城市的所有酒店，好像查不到请求如下<ns:HotelRef HotelCityCode="1" HotelName=""/>。4344.1.6. 问：酒店价格计划接口OTA_HotelRatePlan可以一次查询多家酒店的价格吗？4344.1.7. 问：“Server returned HTTP response code: 413”是什么问题？4354.1.8. 问：我怎么知道我可以对接口的最大访问频次是多少？4354.1.9. 问：AreaID和BrandCode对应的数据在哪里能找到。4354.1.10. 问：OTA_HotelRatePlan返回的结果里RatePlanCode="559401" RatePlanCategory="16"描述的是什么意思。4354.1.11. 问：我之前用的是酒店API1.0查询酒店信息的，请问现在提供的API2.0查询接口在使用方式上与API1.0有区别吗？4364.1.12. 问：为什么我调用酒店API2.0的可订性检查接口会抛下面的错。4364.1.13. 问：酒店API2.0新预订接口下单时，担保信息必须要填写吗？4364.1.14. 问：酒店API2.0新预订接口对于信用担保时录入的信用卡资料需要经过加密再传入吗？4364.1.15. 问：酒店API2.0搜索接口节点<VendorMessage InfoType="23">infotype数字对应的类型有哪些。4374.1.16. 问：酒店API2.0的搜索接口提供最低价格的显示吗？4374.1.17. 问：酒店API2.0的搜索接口提供国外酒店的搜索吗？4374.1.18. 问：酒店API2.0价格计划接口返回的内容中<CancelPenalty Start="2012-05-04 10:55:01" End="2012-05-08 17:00:00">描述的是什么信息。4384.1.19. 问：酒店API2.0调用中报错4384.1.20. 问：价格计划接口返回多个日期段的价格我该怎么取值。4384.1.21. 问：我用标准SOAP请求名为*.asmx的服务接口为什么连不上。4384.1.22. 问：酒店API2.0新预订接口的联系方式Contact Type有哪几种？4384.2. 错误代码4391.1.1. 目的本文描述了网站联盟API平台对联盟伙伴提供的接口化预订解决方案，帮助联盟伙伴轻松实现酒店、机票、度假等在线旅游业务查询、预订、API功能。文档分别从交互模式、签名、接口、注意事项等方面详细介绍了API平台的工作方式和开发过程，可以帮助开发人员快速入门并掌握开发技能，同时也可以作为日后接口参数及参数类型的速查手册。1.2. 读者对象本文档的预期读者为业务需求人员、开发经理、项目经理、架构设计师、开发人员、测试人员、设计评审人员、用户文档编写者。1.3. 文档内部约定1.3.1. 文档字体约定 着重说明字体：对于本文中重要，易混淆，易疏忽的关键内容进行标记时使用的字体 补充说明字体：为便于读者理解，文本在某些描述之后会使用现有系统的实际情况举例，这是一种对于前文进行补充说明时使用的字体 待定信息字体：对于本文在编写时未确定，需与相关干系人进一步明确信息时使用的字体1.4. 术语与缩写术语/缩写解释APIApplication Programming Interface应用程序接口本文中指携程旅行网提供给联盟伙伴的业务数据接口WebserviceUrl指API2.0平台提供的业务Webservice的请求地址SOAPWebservice请求时使用的网络协议，API2.0平台中提供的所有API必须基于SOAP协议请求SecretKey密钥指联盟伙伴通过携程客户经理完成API平台权限开通后获得的针对每个SID的唯一身份认证标识。可通过登录联盟平台()后通过站点列表中的站点详情页查看。请妥善保存此密钥并不得泄露给第三方Xmlns所有API2.0平台提供的API的命名空间为信用卡加密在酒店部分API中，对于涉及到信用卡部分的数据需要进行加密。加密算法为DES对称加密。加密密钥为SecretKey的最后8位。时间格式时间字符串格式应当采用”ISO 8601” 标准<ns:ResGuest ArrivalTime="13:00:00.000+08:00"><ns:LateArrivalTime>2012-06-15T15:00:00.000+08:00</ns:LateArrivalTime><ns:TimeSpan Start="2012-06-15T13:00:00.000+08:00" End="2012-06-16T11:00:00.000+08:00"/>2. 方案概述2.1. 业务说明API平台提供联盟伙伴自行通过携程旅行网提供的在线旅游业务API实现业务相关流程，避免了只能导流量而不能自主定义预订流程的问题2.2. 业务流程2.3. API2.0平台介绍Ø 提供方式：WebServiceØ 协议：SOAPØ 请求报文：1) 请求报文分为两个部分：Header 和 RequestBody2) Header节点说明术语/缩写解释AllianceID联盟ID指联盟伙伴通过网站联盟平台()自行注册或通过携程客户经理注册后得到的唯一联盟标识类型为Int32SID站点ID指联盟伙伴通过网站联盟平台()开通联盟并登录后自行添加或通过携程客户经理注册后得到的联盟下站点的唯一标识类型为Int32。一个联盟可拥有多个站点RequestType请求类型请求类型必须同请求的WebserviceUrl中的请求页面名称一致（不区分大小写）。若WebserviceUrl和RequestType不一致则会返回错误信息TimeStamp时间戳本文中指以1970-1-1 00:00:00.000为基准，至当前时间为止的总秒数每次请求的时间戳必须在到达API后30秒内Signature签名以原始签名串按照顺序进行字符串拼接后MD5加密所得的字符串。MD5相关请见MD5签名章节3) RequestBody节点说明RequestBody节点为具体业务请求XML，根据请求的业务不同而变化。具体可参见每个API的请求XML。l 酒店API部分请求说明例1：酒店联通测试请求XML如下：<?xml version="1.0"?><Request><Header AllianceID="1" SID="50" TimeStamp="1335341667" RequestType="OTA_HotelSearch" Signature="XXXXXXXXXXXXXXXXXXXXXXX" /><HotelRequest><RequestBody xmlns:ns="http:/www.opentravel.org/OTA/2003/05" xmlns:xsi="http:/www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http:/www.w3.org/2001/XMLSchema"><ns:OTA_ReadRQ Version="1.0"><ns:UniqueID Type="28" ID="1"/><ns:UniqueID Type="503" ID="50"/><ns:UniqueID Type="1" ID="159c906a-aa28-4f54-b609-59d2c105fde2"/><ns:UniqueID Type="501" ID="100063481"/></ns:OTA_ReadRQ></RequestBody></HotelRequest></Request>例2：酒店订单取消请求XML如下：<?xml version="1.0"?><Request><Header AllianceID="1" SID="50" TimeStamp="1335341667" RequestType="OTA_Cancel" Signature="XXXXXXXXXXXXXXXXXXXX" /><HotelRequest><RequestBody xmlns:ns="http:/www.opentravel.org/OTA/2003/05" xmlns:xsi="http:/www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http:/www.w3.org/2001/XMLSchema"> <ns:OTA_CancelRQ TimeStamp="2012-04-20T00:00:00.000+08:00" Version="1.0"><ns:UniqueID ID="100060688" Type="501"/><ns:UniqueID ID="1" Type="28" /><ns:UniqueID ID="159c906a-aa28-4f54-b609-59d2c105fde2" Type="1"/><ns:Reasons><ns:Reason Type="506"/></ns:Reasons></ns:OTA_CancelRQ></RequestBody></HotelRequest></Request>总结：通过以上示例可发现，对于所有的酒店请求，黑色部分每次请求均一致，蓝色部分为每个业务API的具体业务请求体，随着请求的API类型不同而变化。红色部分为每次请求的头节点，根据具体请求时间和请求类型而变化l 度假及其他API请求说明：例1：度假查询参数API请求XML如下：<?xml version="1.0"?><Request><Header AllianceID="1" SID="50" TimeStamp="1335341667" RequestType="OTA_VacationAddressSelector" Signature="XXXXXXXXXXXXXXXXXXXXXXXX" /><VacationAddressSelectorRequest><SearchValue>上海</SearchValue></VacationAddressSelectorRequest></Request>例2：度假查询参数API请求XML如下：<?xml version="1.0"?><Request><Header AllianceID="1" SID="50" TimeStamp="1335341667" RequestType="OTA_VacationCity" Signature="XXXXXXXXXXXXXXXXXXXXXXXX" /><VacationCityRequest><CityName></CityName></VacationCityRequest></Request>总结：通过以上示例可发现，对于所有的度假请求，黑色部分每次请求均一致，蓝色部分为每个业务API的具体业务请求体，随着请求的API类型不同而变化。红色部分为每次请求的头节点，根据具体请求时间和请求类型而变化Ø 响应报文n 请求报文分为两个部分：Header 和 ResponseBodyn Header节点说明术语/缩写解释ReferenceID唯一追踪编号对于每次请求均会返回此属性若在使用过程中发生问题可凭此联系携程技术人员寻求解决方案ResultCode请求结果标志Success成功Fail失败Unknown未知问题Forbidden禁止访问Error错误ResultNo错误编号开发人员可通过该编号在错误代码列表中查询具体错误信息或寻求携程技术人员支持ResultMsg错误信息Timestamp响应时间戳n ResponseBody节点说明ResponseBody节点为具体业务响应XML，根据请求的业务不同而变化。具体可参见每个API的响应XML3. 数据格式3.1. 请求地址每个不同的API均提供不同的基于SOAP协议的请求地址。每次请求均需使用如下格式生成完整请求地址：http:/API_Url/Business Type/RequestType.asmx其中参数分别代表如下内容：API_Url：所需请求的API访问地址，携程旅行网提供了测试环境供测试使用，在测试通过后请联系客户经理开通生产环境访问权限Business Type：业务类型(Hotel,Flight,Vacations,Trains,Tuan,User)RequestType：请求类型3.2. 请求类型不同业务的请求类型列表如下：Ø 用户编号术语/缩写解释4801OTA_UserUniqueID用户生成Ø 酒店编号术语/缩写解释1101OTA_Ping联通测试1102OTA_HotelSearch酒店查询1103OTA_HotelDescriptiveInfo酒店静态信息查询1104OTA_HotelRatePlan价格计划查询1105OTA_HotelCacheChange价格缓存变化查询1106OTA_HotelAvail可订检查1107OTA_HotelRes订单生成1108OTA_Cancel订单取消1109OTA_HotelResNotif订单变化查询1110OTA_Read订单详情查询1111D_HotelSearch通过查询服务器直接查询酒店列表1112D_HotelDetail通过查询服务器直接查询酒店详情1113D_HotelOrderList通过查询服务器直接查询酒店订单列表1114D_HotelOrderDetail通过查询服务器直接查询酒店订单详情1115D_HotelCommentList通过查询服务器直接查询酒店评论信息Ø 国内机票编号术语/缩写解释1201OTA_FlightSearch国内航班查询1202OTA_GetFlightGifts国内航班礼盒1203OTA_FltSaveOrder国内机票订单保存1204OTA_FltCancelOrder国内机票订单取消1205OTA_FltViewOrder国内机票订单查询1206OTA_GetStatusChangedOrders国内机票订单变更查询1207OTA_FltOrderList国内机票订单列表Ø 国际机票编号术语/缩写解释1311OTA_IntlFlightSearch国际机票查询1301OTA_FltGetCraftInfos机型基础信息查询1302OTA_FltGetCityInfos城市基础信息查询1303OTA_FltGetAirportInfos机场基础信息查询1304OTA_FltGetAirlineInfos航线基础信息查询Ø 旅游度假编号术语/缩写解释1401OTA_VacationAddressSelector地址选择器1402OTA_VacationCity出发城市列表1403OTA_VacationCredentialType证件类型1404OTA_VacationDeliverType配送方式1405OTA_VacationHotels度假酒店列表1406OTA_VacationOrderItem度假产品单选项1407OTA_VacationOrderOption度假产品可选项1408OTA_VacationOrderAmount度假订单金额计算1409OTA_VacationOrderCreate订单生成1410OTA_VacationOrderSubmit订单提交（支付完成后提交）1411OTA_VacationOrderList订单列表查询1412OTA_VacationOrderInfo订单详情查询1413OTA_VacationPackageList度假产品列表查询1414OTA_VacationPackageInfo度假产品详情1415OTA_VacationTmpOrderInfo暂存订单详情1416OTA_VacationSysFlight度假系统机票查询 Ø 团购编号术语/缩写解释1501GroupProductList团购产品列表1502GroupProductInfo团购产品详情1503GroupCreateOrder团购创建订单1504Group_SubmitOrder团购提交订单1504GroupQueryTickets团购券列表1505GroupCancelTickets团购取消券1506GroupOrderList团购订单列表1507GroupProductChange团购产品变更通知1508GroupOrderChange团购订单变更通知1509GroupTicketChange团购券变更通知Ø 支付编号术语/缩写解释1601GetPaymentDetail支付查询1602PaymentEntry在线支付 3.3. 测试及正式访问3.3.1. 测试环境访问携程提供API2.0平台测试环境。测试环境API_Url为：http:/OpenAPIT 暂未开通请在阅读完本手册后，联系客户经理开通测试环境访问权限及访问密钥。请务必于测试环境中确认调用程序没有缺陷。3.3.2. 生产环境访问请联系客户经理开通访问权限，并获取生产环境访问密钥。生产环境API_Url为：http:/OpenAPI3.4. 请求频次API平台根据不同联盟设置了每个API每分钟可访问次数限制。若超过访问次数限制则将返回RateLimit，并将锁定5分钟。若您的业务确实需要扩充访问次数，请联系携程网站联盟销客户经理为您配置。 3.5. 签名原始串无论是用get、post还是xml，签名原始串组串方式都一致，除Signature字段外，待签名参数按照一定规则拼接而成，参数名、空值不传递，不参与签名。签名时字段名和字段值都采用原始值，不进行URL Encode。 MD5 是一种摘要生成算法，通过在签名原始串后加上联盟通信密钥的内容，进行MD5运算，形成的摘要字符串即为签名结果。为了方便比较，签名结果统一转换为大写字符。3.6. 签名算法目前为MD5签名MD5签名计算公式：Signature=Md5(TimeStamp+AllianceID+MD5(密钥).ToUpper()+SID+RequestType).ToUpper()如签名原始参数串是：AllianceID =1& SID =50& TimeStamp =1234567890&RequestType=OTA_Ping站点密钥是：abcdefg123456MD5后站点密钥是：5393E07F94A25AAA373DBD3FA257BD3A签名的结果为：Signature= Md5(TimeStamp+AllianceID+MD5(密钥).ToUpper()+SID+RequestType).ToUpper()=MD5(123456789015393E07F94A25AAA373DBD3FA257BD3A50OTA_Ping)= EF5FBA4AAB36FD044F8A13BA0D63DD133.6.1. MD5签名原理联盟站点基于SOAP协议发送API请求到API2.0平台，出于安全考虑，简述如下：联盟站点请求API时对请求参数附加上联盟密钥一起进行MD5签名，联盟密钥由API平台和联盟各执一份，并且API平台保证联盟密钥与其它联盟不相同，所以其他联盟无法伪造MD5签名，当API请求到达API平台后，API平台使用联盟密钥按相同算法生成MD5签名，然后验证联盟发送过来的MD5签名是否与API平台生成的一致，从而可以保证请求不可篡改及伪造。3.7. 接口介绍3.7.1. 用户 User3.7.1.1. 用户生成 OTA_UserUniqueID1) 服务地址：http:/API_Url/Business Type/ OTA_UserUniqueID.asmx2) 方法名：Request3) 方法参数：requestXML string4) 功能： a) 根据联盟站点、本地用户名生成并关联唯一携程用户，并返回唯一关联标识UserUniqueID。b) SID+本地用户名：携程用户=1：1c) 在调用需要使用到用户名的API时，请先调用用户API生成携程帐户并获取到UserUniqueID。在所有需要使用用户名的API中，只需要传递UserUniqueID即可。5) 请求示例：以下是 SOAP 1.1 请求和响应示例。所显示的占位符需替换为实际值。POST /Hotel/OTA_UserUniqueID.asmx HTTP/1.1Content-Type: text/xml; charset=utf-8Content-Length: lengthSOAPAction: "<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:xsi="http:/www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http:/www.w3.org/2001/XMLSchema" xmlns:soap="http:/schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <Request xmlns=" <requestXML>string</requestXML> </Request> </soap:Body></soap:Envelope>6) 响应示例：HTTP/1.1 200 OKContent-Type: text/xml; charset=utf-8Content-Length: length<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:xsi="http:/www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http:/www.w3.org/2001/XMLSchema" xmlns:soap="http:/schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <RequestResponse xmlns=" <RequestResult>string</RequestResult> </RequestResponse> </soap:Body></soap:Envelope>7) 请求requestXML<?xml version="1.0" encoding="utf-8"?><Request><Header AllianceID="1" SID="50" TimeStamp="1335341667" RequestType="OTA_UserUniqueID" Signature="XXXXXXXXXXXXXXXXXXXXXXX" /><UserRequest><AllianceID>1</AllianceID><SID>50</SID><UidKey>admin</UidKey></UserRequest></Request>UserRequest字段类型描述默认值可为空备注AllianceIDint联盟IDNSIDint站点IDNUidKeystring本地用户名N调用方本地用户名相同值会返回相同用户标识8) 响应Re