联网售票接口标准_V1.docx

XXXXXXXXXXXXXXXXXXXXXXXXX联网售票接口开发指引Webservicexxxxxxxxxxxxxx公司2011年10月目录1概述52编写目的53范围54目标对象55术语和缩略语55.1术语55.1.1发班模式55.1.2发班类型65.1.3班次种类65.1.4客运类别65.1.5班线种类65.1.6车辆等级65.1.7车辆类型65.1.8车辆座型65.1.9幂等性65.1.10幂等操作66接口描述77WebService接口约定77.1实现机制87.1.1XML结构描述87.2接口报文头约定97.3接口调用约定98接口布署说明109联网售票标准流程119.1流程图119.2流程说明129.3常见代售票流程异常处理139.3.1锁位异常139.3.2售票提交异常139.3.3退票异常139.3.4车票重打异常1310接口详细说明1410.1接口说明1410.2接口列表1410.3接口定义1510.3.1客运站信息1510.3.2站点查询1610.3.3班次查询1710.3.4实时班次查询2010.3.5获取订单号2310.3.6锁定座位2310.3.7取消锁位2610.3.8售票提交2710.3.9售票确认3110.3.10取退票费率3210.3.11退票3310.3.12废票3410.3.13退票反馈3610.3.14车票重打3710.3.15订票提交4010.3.16退订票4210.3.17售订票4310.3.18售订票确认4610.3.19交易对账4710.3.20交易查询4810.3.21交易明细4910.3.22交易汇总5010.3.23代售明细5110.3.24代售汇总5310.3.25退订票反馈5410.3.26班次座位信息5510.3.27业务冲正5610.3.28售票机构信息5710.3.29车票打印5710.3.30未打印车票查询6010.3.31车票打印反馈6210.3.32订单状态查询6411错误号约定6511.1中心数据库错误号6511.2车站数据库错误号6511.3通讯服务错误号6511.4系统错误号6512修订记录6612.12011-08-16 LWL6612.22011-08-29 LWL6612.32011-08-30 LWL6612.42011-08-31 LWL6612.52011-09-03 LWL6612.62011-09-23 LWL6612.72011-11-01 LWL6612.82011-12-01 LWL6612.92011-12-17 LWL6612.102011-12-20 LWL6612.112012-01-09LWL6612.122012-01-15 LWL6612.1320120224 LWL6612.142012-03-06 LWL66概述为了进一步开展某某市客运站联网售票、网上售票、手机售票等多途径便捷的购票业务，首先必须实现中心与客运站的双向通讯，即需要中心向客运站及各类接入客户端提供接口以处理联网售票相关操作请求，客运站也要向中心提供接口，处理中心转发到客运站的各种业务请求。为此，本文制定中心所提供的联网售票相关的一系列接口以及接口的技术要求、接口方式、数据格式、传送方式、数据质量等内容。编写目的本文旨在使联网售票的各种接入客户端的架构师、需求分析师、系统设计师、项目经理、开发人员等相关人员了解接口的技术要求、接口方式、数据格式、传送方式、数据质量等。指导他们在联网售票通讯环境的设计和开发工作。范围本文档某某市联网售票系统接口的技术要求、接口方式、数据格式、传送方式、数据质量等内容。目标对象联网售票客户端架构师、需求分析师、系统设计师、项目经理、开发人员。注：联网售票客户端包括：客运站售票系统客户端、网上订/购票系统客户端、代理售票点客户端、手机购票终端等接入终端。术语和缩略语术语发班模式发班类型是指具体的班次是否有确定的发班时间点。如果有确定的时间点则为定时班、否则为：非定时班。可选值（定时班,非定时班）。发班类型指客运班次的类型，分为：正班、加班、顶班。班次种类分为：始发班、配载班。客运类别直达、普通。班线种类一类班线、二类班线、三类班线、四类班线。车辆等级指车辆的装备等级，分为：高三级、高二级、高一级、中级、普通级车辆类型指客运车辆的类型，分为：特大型客车、大型客车、中型客车、小型客车车辆座型分为：座位、卧铺。幂等性即某函数一次调用和多次调用产生的返回结果相同。f(f(x) = f(x)幂等操作重复调用多次产生的业务结果与调用一次产生的业务结果相同。实现方式：通过业务操作本身实现幂等性，接收到业务请求时，首先在业务记录表中检索，如果已有处理过的记录(注意判断是否相同用户发起)，则直接返回上一次处理结果或不进行任何操作;如果没有记录，则进行业务处理，然后记录处理结果，记录后再将结果返回。幂等业务流程接口描述接口由中心以WebService方式提供；售票提供接口是指票源站向中心提供的接口，以数据库存储过程方式提供，中心将此接口提供给售票方进行售票操作。WebService接口约定WebService接口通过以Xml文档方式回复请求结果。采用SoapHeader进行身份验证，验证节点为AuthorizationSoapHeader，验证项为UserName和Password。用户名为车站编码，密码则是由中心分配的登陆密码。如果接口返回数据项为“无”，也会返回XML结果，只是不包含数据，但包含成功或错误信息。WSDL描述见附件：wsdl.txt。实现机制图2 接口使用模式图3接口运行机制对于数据请求，由站务管理系统根据本规范的要求向数据中心信息系统提交申请关键字，数据中心信息系统根据请求的内容返回相应的业务基础数据。对于数据上报，由站务管理系统根据本规范的要求向数据中心信息系统提交有关数据，数据中心信息系统根据实际业务的要求返回相应的结果。XML结构描述说明：1、 返回结果XML格式文件，编码方式为utf-8。具体格式图示为：接口报文头约定注：报文头节点名均用小写。序号节点名节点说明类型长度描述1title标题String255报文标题2description说明String255附加说明3srcserver发送站编码String20本站编码4tagserver接收站编码String20票源站或中心编码5service服务名称String255请求服务名称6transid事务IDString36事务Guid，发送方生成，不能重复。接口调用约定1、 接口报文总长度不能超过3M，调用时请注意，如果有必要，请分为多次上报。2、 接口调用时请先检查“请求结果”项中的errcode和errmsg。如果errcode不为0则表示调用错误，在errmsg中有相应的错误原因描述。请调用者对错误作适当的处理。具体错误号请参数附录。接口布署说明所有对客运站系统或其他接入系统所发布的WebService接口均布署在相应的前置机上，接口使用者只与前置机通讯，直接调用相应前置机上的WebService服务。同时，客运站提供的接口布署在车站的站务服务上，中心通过与前置机通讯来调用客运站提供的接口。如下图所示：联网售票标准流程流程图流程说明代售票时，售票方只要与数据中心服务通讯即可。售票程序根据需要向数据中心服务发送请求报文，并接收返回结果。1、 班次查询：传入发车站、目的地、日期、时间段参数查询符合条件的班次信息。此操作只在数据中心处理。2、 班次实时信息查询：在步骤1返回的班次信息中选择需要购票的班次，把班次日期和班次号发往票源站查询班次的实时座位和票价。也可略过此环节直接申请锁定座位。3、 锁位：确定有余票以及票价后，输入需要购买的票型和数量，锁定座位。（注：锁票后可设置携带儿童等操作）。4、 售票提交：锁定座位并收款后，向票源站发送售票站、售票员工号、售票员姓名、交易号等参数，将锁定的车票售出。5、 售票结果确认：成功售出座位后，向中心发送该交易完成的确认信息。常见代售票流程异常处理锁位异常锁定座位时如果出现错误，调用者可不作特殊处理。发车方请定时检测锁位情况，如果锁定座位后超过约定的时间(不同的业务约定不同的保留时间)，则释放座位。售票提交异常售票提交时如果出现异常，可在间隔10秒钟左右尝试3次重复提交，如果仍然失败，则记录出错的时间及详细提示备查。退票异常退异站票时如果出现异常，可先按约定的手续费计算规则，把余款退还给乘客。间隔一段时间后再尝试退票，如果仍不成功，则记录车票信息交数据中心处理。车票重打异常如果重打印车票时出现异常，则可能原车票已不可用，可再次尝试，如果仍不成功，则进行退票处理，如果退票仍不成功，则先把票款退还给乘客，同时记录车票信息交中心处理，重新售票。接口规范接口说明接口由数据中心信息系统提以WebService方式供，用来实现站与站之间联网售票。接口列表序号接口名称接口功能提供者幂等备注中心车站1站点查询2班次查询3实时班次查询4获取订单号5锁定座位6取消锁位7售票提交8售票确认9取退票费率10退票11退票反馈12车票重打13订票提交14退订票15售订票16售订票确认17交易查询18交易明细19交易汇总20代售明细21代售汇总22退订票反馈接口定义基础数据接口客运站信息l 接口说明接口名称：TKStationInfo接口功能：从中心查询参与联网售票的客运站信息。接口声明：public string TKStationInfo (string City);l 访问规则由数据中心系统供，供售票机构调用。l 请求参数序号参数名参数说明类型长度可空描述1City所在城市String20Y如果为空则返回所有客运站信息l 返回数据序号字段名数据项名称类型长度可空描述1STCode站场代码String202STName站场简称String503STFullName站场名称String504STSale可售票String11可售，0不可售5STBook可订票String11可订，0不可订6STType站场类别String20配客点、客运站7STLevel站场级别String208STPreSale预售天数Int9STProvince辖区省String2010STCity辖区市String2011STDistrict辖区县String20STTel咨询电话String20STAddr车站地址String25512STNotes备注String255站点查询l 接口说明接口名称：TKNodeQuery接口功能：从中心查询站点信息，站点编码是全省统一站点编码，售票时使用该编码进行查询或交易，此编码集相对改动较少，各票源站和售票站可定时从中心获取(如每周获取一次)，然后对本地站点编码进行匹配处理。接口声明：public string TKNodeQuery (string OwnerStation, string DstNode);l 访问规则由数据中心系统供，供客运站售异站票时调用。l 请求参数序号参数名参数说明类型长度可空描述1OwnerStation客运站编码String20Y2DstNode站点String50Y拼音简码或中文，如果不指定则返回所有站点信息l 返回数据序号字段名数据项名称类型长度可空描述1NDStation客运站编码String20N2NDCode站点编码String20N唯一3NDShortcut助记码String104NDName站点名称String50N5NDEName英文名称Date50Y6NDProvince省String20N中文7NDCity市String20N中文8NDDistrict区String20中文9NDOpTime更新时间DateTime10NDNotes备注String255Y售票机构信息l 接口说明接口名称：TKOrgInfo接口功能：由中心接口系统提供，客运站同步售票机构信息时调用。接口声明：public string TKOrgInfo (string TypeCode);l 访问规则由数据中心系统供，供客运站售异站票时调用。l 请求参数序号参数名参数说明类型长度可空描述1TypeCode机构类型String20N0所有，1车站，2其他售票机构l 返回数据序号字段名字段名称类型长度可空描述1OrgCode机构编码String202OrgName机构名称String503OrgFullName机构全称String1004OrgShortName机构简称String205OrgType机构类型String206OrgNotes备注String255售票交易接口中心班次查询l 接口说明接口名称：TKSchQueryCenter接口声明：public string TKSchQueryCenter (string StartStation,string OpStation,string OpAddress,string SchDate,string DstNode, string SeatType,string SchTime,string OperMode,string SchCode,int BllType,int PageSize,int PageIndex);接口功能：根据目的地和日期等信息查询符合查询条件的班次信息。l 访问规则由数据中心系统供，供客运站售异站票时调用。向中心查询班次列表，座位和票价并不实时。默认只能查询距当前时刻4小时之后的班次，调用前请先判断日期和时间。l 请求参数序号参数名参数说明类型长度可空描述1StartStation发车站String20Y发车站编码/起点市/起点站。如果为空则按发车时间排序返回前100条班次信息。2OpStation请求站编码String20N3OpAddress操作地址String20Y操作地址SchDate班次日期StringNyyyy-MM-dd4DstNode终到站String50N站点编码或中文5SeatType座位类型String10Y座/卧6SchTime发班时间String5YHH:mm,显示当天指定时间之后的班次。7OperMode运营方式String20Y直达/普通8SchCode班次号String10Y为空返回所有匹配记录，指定班次号则返回相应班次号的班次信息。9BllType业务类型IntN7网上售票，8自助售票，9手机售票，10订票，11车站互售10PageSize每页行数String10Y整型串11PageIndex页号String10Y整型串l 返回数据序号字段名数据项名称类型长度可空描述1SchLocalCode班次号String202SchDate班次日期Date3SchLineName线路名称String504SchStationCode始发站编码String205SchStationName始发站名称String506SchCompCode经营单位代码String207SchCompName经营单位名称String508SchBusBrand车牌号码String209SchBusBrandColor车牌颜色String2010SchTime发班时间Time511SchWaitingRoom候车厅String5012SchCheckGate检票口String5013SchBerth停车位String5014SchType班次种类String20始发/配载15SchMode发班模式String20普通/滚动16SchDstProvince终到省String5017SchDstCity终到地String5018SchDstNode终到站String20终点站编码19SchDstNodeName终到站名称String50终点站名称20SchOperType运营方式String20直达或普通21SchInterval发班间隔String522SchNodeNameList途经站点String100023SchDist里程Float24SchSeatCount座位数Int25SchPrice全票价float26SchDiscPrice半票价float27SchStdPrice学生票价float28SchFuel燃油附加费float29SchBusType车辆类型String2030SchBusLevel车辆等级String2031SchTicketCount剩余车票Int32SchChild免票儿童位Int33SchStat班次状态String201:售票，2：检票，3：已发班； 4：停班34SchNodeCode到站编码String20站点编码，锁票时调用(传入有可能是中文)35SchNodeName到站名称String5036SchPrintSeat是否打印座位Int0不打印，1打印37Notes备注String255实时班次查询l 接口说明接口名称：TKSchQueryStation接口声明：public string TKSchQueryStation(string StartStation,string OpStation,string OpAddress,string SchDate,string DstNode, string SeatType,string SchTime,string OperMode,string SchCode,int BllType,int PageSize,int PageIndex);接口功能：根据目的地和日期等信息到客运站服务器查询符合查询条件的班次实时信息。l 访问规则此接口直接转发到客运站服务器进行查询，返回结果是目标站班次的实时信息，一般用于并发量不大的业务，比如客运站之间代售。只能查询距当前时刻4小时之后的班次，调用前请先判断日期和时间。l 请求参数序号参数名参数说明类型长度可空描述1StartStation发车站String20Y发车站编码/起点市/起点站。如果为空则按发车时间排序返回前100条班次信息。2OpStation请求站编码String20N3OpAddress操作地址String20Y操作地址SchDate班次日期StringNyyyy-MM-dd4DstNode终到站String50N站点编码或中文5SeatType座位类型String10Y座/卧6SchTime发班时间String5YHH:mm,显示当天指定时间之后的班次。7OperMode运营方式String20Y直达/普通8SchCode班次号String10Y为空返回所有匹配记录，指定班次号则返回相应班次号的班次信息。9BllType业务类型IntN7网上售票，8自助售票，9手机售票，10订票，11车站互售10PageSize每页行数String10Y整型串11PageIndex页号String10Y整型串l 返回数据序号字段名数据项名称类型长度可空描述1SchLocalCode班次号String202SchDate班次日期Date3SchStationName始发站名称String504SchCompCode经营单位代码String205SchCompName经营单位名称String506SchBusBrand车牌号码String207SchBusBrandColor车牌颜色String208SchTime发班时间Time59SchWaitingRoom候车厅String5010SchCheckGate检票口String5011SchBerth停车位String5012SchType班次种类String20始发/配载13SchMode发班模式String20普通/滚动14SchDstProvince终到省String5015SchDstCity终到地String5016SchDstNode终到站String20终点站编码17SchDstNodeName终到站名称String50终点站名称18SchOperType运营方式String20直达或普通19SchInterval发班间隔String520SchNodeNameList途经站点String100021SchDist里程Float22SchSeatCount座位数Int23SchPrice全票价float24SchDiscPrice半票价float25SchStdPrice学生票价float26SchFuel燃油附加费float27SchBusType车辆类型String2028SchBusLevel车辆等级String2029SchTicketCount剩余车票Int30SchChild免票儿童位Int31SchStat班次状态String201:售票，2：检票，3：已发班； 4：停班32SchNodeCode到站编码String20站点编码，锁票时调用(传入有可能是中文)33SchNodeName到站名称String5034SchPrintSeat是否打印座位Int0不打印，1打印35Notes备注String255获取订单号l 接口说明接口名称：TKGetOrderNo接口功能：用于从服务器获取订单号(锁票时必须传入订单号)。接口声明：public string TKGetOrderNo();l 访问规则由数据中心系统供，供客运站售异站票时调用。生成的订单号将用于对帐和业务跟踪以及系统调试。l 请求参数无l 附加数据无l 返回数据序号字段名数据项名称类型长度可空描述1OrderNo订单号String20N锁定座位l 接口说明接口名称：TKLock接口功能：用于售票前锁定指定的座位，避免在付费等其他操作时被其他乘客抢购。如果规定的时间内未完成交易，则锁定的座位可能会被客运站自动取消（具体时间范围与客运站商定）。接口声明：public string TKLock(string OpStation,string OpAddress,string StartStation,string SchDate,string SchCode,string OperCode,string OperName,string CustTel,string CustName,string CustCerType,string CustCerNo,string DstNode,int TicketCount,string SeatList,string TicketType,string Child,string OrderNo,int BllType,string TransID);l 访问规则由数据中心系统供，供客运站售异站票时调用。l 请求参数序号参数名参数说明类型长度可空描述1StartStation发车站String20N发车站编码2OpStation请求站编码String20N3OpAddress操作地址String20Y操作地址4SchDate班次日期String10Nyyyy-MM-dd5SchCode班次号String20N6OperCode操作员工号String20N7OperName操作员姓名String20N8CustTel用户手机号String20Y网上购票或手机购票用9CustName用户名String20Y网上购票或手机购票用10CustCerType证件类别String20Y网上购票或手机购票用:身份证/军官证等11CustCerNo证件号码String20Y网上购票或手机购票用12DstNode到达站String50N13TicketCount票数Int2N14SeatList座位列表 String120Y每个座位用3位数字表示(暂不支持指定座位)15TicketType票型IntN1全，2半，3学16Child免票儿童数IntN默认为017OrderNo订单号String20N18BllType业务类型IntN7网上售票，8自助售票，9手机售票，10订票，11车站互售,12代售点19TransID事务IDGuid36N新GUID，客户端生成l 附加数据无l 返回数据数据类型：多记录。序号字段名数据项名称类型长度可空描述1SchDate班次日期Dateyyyy-MM-dd2SchCode班次号String203SchTime班次时间String5Hh:mm,锁票后校验用，防止车站修改班次时间的班次未及时同步到中心。4DstName目的地名String505Seat座位号Int36TicketType票型Int1仅供参考，应记录传入票型。7Price票价float98Fuel燃油附加费float9Child免票儿童Int10OperCode操作员工号String2011OperName操作员姓名String2012OpTime操作时 间Datetimeyyyy-MM-dd hh:mm:ss13OrderNo订单号string2014TransID事务IDString20锁票时的事务ID15TicketCount剩余座位Int锁位后剩余座位16SchStat班次状态String201:售票，2：检票，3：已发班； 4：停班17Notes说明String255Yl 附加信息无论锁票成功或失败，在Response节点附加班次状态和锁位后剩余票数。如: 0 125 锁定座位(V2)l 接口说明接口名称：TKLock_2接口功能：增加客户ID参数，其余项和TKLock相同。接口声明：public string TKLock_2(string OpStation,string OpAddress,string StartStation,string SchDate,string SchCode,string OperCode,string OperName,string CustID,string CustTel,string CustName,string CustCerType,string CustCerNo,string DstNode,int TicketCount,string SeatList,string TicketType,string Child,string OrderNo,int BllType,string TransID);l 访问规则由数据中心系统供，供客运站售异站票时调用。l 请求参数序号参数名参数说明类型长度可空描述1StartStation发车站String20N发车站编码2OpStation请求站编码String20N3OpAddress操作地址String20Y操作地址4SchDate班次日期String10Nyyyy-MM-dd5SchCode班次号String20N6OperCode操作员工号String20N7OperName操作员姓名String20N8CustID客户IDString36Y客户GUID，用于注册用户购票以及注册用户为其他联系人购票。9CustTel用户手机号String20Y网上购票或手机购票用10CustName用户名String20Y网上购票或手机购票用11CustCerType证件类别String20Y网上购票或手机购票用:身份证/军官证等12CustCerNo证件号码String20Y网上购票或手机购票用13DstNode到达站String50N14TicketCount票数Int2N15SeatList座位列表 String120Y每个座位用3位数字表示(暂不支持指定座位)16TicketType票型IntN1全，2半，3学17Child免票儿童数IntN默认为018OrderNo订单号String20N19BllType业务类型IntN7网上售票，8自助售票，9手机售票，10订票，11车站互售,12代售点20TransID事务IDGuid36N新GUID，客户端生成l 附加数据无l 返回数据 (同TKLock)取消锁位l 接口说明接口名称：TKUnLock接口功能：释放已锁定的座位。(注：如果乘客放弃购票，则要主动释放已锁定的座位，避免长时间占用客运资源)接口声明：public string TKUnLock (string StartStation,string OpStation,string OpAddress,string OperCode,string OperName,string TransID);l 访问规则由数据中心系统供，供客运站售异站票时调用。l 请求参数序号参数名参数说明类型长度可空描述1StartStation发车站String20发车站编码2OpStation请求站编码String20OpAddress操作地址String20Y操作地址3OperCode操作员工号String204OperName操作员姓名String205TransID事务IDGuid36锁位事务IDl 返回数据序号字段名字段名称类型长度可空描述1errcode错误号Int0正确，3001-4000错误2errmsg错误信息String255l 附加信息无论解锁成功或失败，在Response节点附加班次状态和解锁后剩余票数。如: 0 125 售票提交l 接口说明接口名称：TKCommit接口功能：确认售出已锁定的座位,并获得车票信息。接口声明：public string TKCommit (string StartStation,string OpStation,string OpAddress,string OperCode,string OperName,string TransID,string PayType,string PaySn,string BillCodeList,string BillNoList,string BarcodeList,string InsBillList,string TransTime,string Notes);l 访问规则由数据中心系统供，供客运站售异站票时调用。如果售出后需要异地打印车票，并且车票条码是印刷模式，售订票时则要传入条码等信息。l 请求参数序号参数名参数说明类型长度可空描述1StartStation发车站String20发车站编码2OpStation请求站编码String203OpAddress操作地址String20Y操作地址4OperCode操作员工号String205OperName操作员姓名String206TransID事务IDString36锁票事务ID，同报文头事务ID7PayType支付类型StringY现金/信用卡/网银8PaySn支付单号StringY支付方生成，对帐用。9BillCodeList发票代码String255N“，”分隔，每张车票对应一个号码10BillNoList发票号码String255N“，”分隔