客运联网售票系统软件接口规范.docx

《客运联网售票系统软件接口规范.docx》由会员分享，可在线阅读，更多相关《客运联网售票系统软件接口规范.docx（25页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、客运联网售票系统软件接口规范（V5.0）目 录1前言51.1概述51.2定义51.3参考资料52约定63接口规范73.1接口总览73.2票务中心提供的接口83.2.1班次更新83.2.2锁定座票93.2.3取消锁票93.2.4售票明细93.2.5售票重打印103.2.6废票103.2.7退票103.2.8取退票费率103.2.9检票113.2.10对帐明细113.2.11代理认证113.2.12取票号113.2.13班次基本信息查询113.2.14取得班次票价123.2.15取得中心站点信息123.2.16确认接口123.2.17取客运站站点编码133.3客运站提供的接口133.3.1取票价1

2、33.3.2售票更新133.3.3锁定座票（新增）133.3.4取消锁票（新增）133.3.5废票更新143.3.6重打印更新143.3.7退票更新143.3.8班次信息表143.3.9站点信息表153.3.10检票信息表153.3.11售票明细表（财务对帐用）153.3.12售票查询153.3.13班次信息表更新153.3.14站点编码表更新163.3.15检票信息表更新163.3.16售票明细表更新164其它补充说明的规范164.1关于电子票164.2接口的更新规则174.3异站售票提示和日志175本地操作关键流程与程序设计参考规范185.1售本站票185.2售异站票195.3退票205.

3、4废票206附录216.1客运站编码216.2班车说明226.3退票费计算226.4V5.0不再使用的的接口列表226.4.1锁定座票226.4.2取消锁票226.4.3取得班次票价236.4.4取票价（存储过程）236.5新流程主要特性及设计原理图示231 前言1.1 概述珠海市客运联网售票系统是在珠海市交委的组织下建立的全市客运站联网售票系统。该系统利用先进的计算机技术，将全市16个客运站的售票系统整合为一个整体，实现客运站互相售票的目标。为了最大限度的保持各客运站的独立性和特性，减少重复投资，联网售票系统采用交易中间件技术来实现客运站之间的相互售票交易功能。本系统提供统一的软件接口，嵌入

4、客运站现有的售票系统中，实现现有客运站售票系统与联网售票系统的无缝连接。客运站售票系统经过少量的改动后，利用软件接口，即可实现联网售票。各客运站可以保持现有界面风格不变、操作习惯不变。本文档响应新的联网售票系统客户端接口产品，在珠海客运-联网售票系统-软件接口规范（V4.9X）的基础上，阐述新的联网售票系统的软件接口规范（V5.0），其中重点更改了售票业务、退票业务、废票业务、重打票等的业务流程。各方开发单位有义务严格按照本规范的要求，参考软件接口开发手册，将软件接口嵌入相关计算机系统的软件模块中。1.2 定义DLL（Dynamic Linkable Library）：动态链接库，是一种磁盘文

5、件（通常带有DLL扩展名），它由全局数据、服务函数和资源组成，在运行时被系统加载到进程的虚拟空间中，成为调用进程的一部分。存储过程（Stored Procedure）：是由SQL Server引擎执行的预编译SQL语句，用来封装针对数据库服务器的一整套操作或查询。1.3 参考资料珠海市客运联网售票系统总体设计方案珠海市客运联网售票系统软件功能需求说明书珠海市客运联网售票系统概要设计说明书广东省汽车客运站收费规则实施细则关于2004年我省公路客运春运票价的批复珠海客运-联网售票系统-软件接口规范（4.9X）2 约定l 软件接口的安装不同编码的客运站需要不同的安装盘。如对于二汽和东圃客运站需要提供

6、不同的安装盘。l 软件接口提供本规范要求的软件接口，分别由珠海交通信息化建设投资营运有限公司和客运站提供。珠海交通信息化建设投资营运有限公司负责制定接口规范，编写使用手册，指导应用方开发应用。l 软件接口应用本规范要求的软件接口，分别由珠海交通信息化建设投资营运有限公司和珠海市各客运站使用。双方按照规范要求，负责将软件接口嵌入相关计算机系统的软件模块中，实现联网售票目标。l 接口形式本软件接口以三种形式提供。 动态链接库（DLL） 存储过程 表l 操作系统Windows98/2000系列操作系统。l 数据库Microsoft SQLServer2000数据库。l 开发工具本软件接口支持的开发工

7、具有Delphi，PowerBuilder，VisualBasic，VisualC+，Visual FoxPro。l 软件平台本软件接口使用了BEA公司的交易中间件Tuxedo。因此，所有使用本软件接口的计算机系统必须安装Tuxedo客户端软件。该软件由交通信息化投资建设营运有限公司负责安装。l 用途本软件接口只能用于珠海市客运联网售票系统，未经许可，不能用于其它用途。l 流程规范本规范提供的流程规范只是指导客运站如何嵌入软件接口，并非一个统一的业务处理流程标准。l 本文档行文约定红色（粗体）新增接口或特殊说明；正文黑色粗体为各接口的增补说明、建议或注意事项。3 接口规范3.1 接口总览注：粗

8、红体为新增或变更接口；灰色表格部分为客运站提供部分。序号类别名称描述接口形式备注1调度接口SchemeRefresh班次更新DLL投资公司提供2售票接口TicketLock2锁定座票（新）DLL投资公司提供3SchBaseInfo班次基本信息查询DLL投资公司提供4PriceInfo2票价信息（新）DLL投资公司提供5LockCancel2取消锁票（新）DLL投资公司提供6TicketUpdate售票更新DLL投资公司提供7TicketRePrint售票重打印DLL投资公司提供8TicketBlankout废票DLL投资公司提供9TicketOff退票DLL投资公司提供10GetOffFare

9、获取退票费率DLL投资公司提供11CheckUser代理认证DLL投资公司提供12GetTicketNo取票号DLL投资公司提供13SchBaseInfo取得班次基本信息DLL投资公司提供14ConfirmAct确认接口DLL投资公司提供15GetStCode取得中心站点编码DLL投资公司提供16检票接口TicketExam检票DLL投资公司提供17对帐明细SellCollate对帐明细DLL投资公司提供18票价接口ProGetPrice2取票价（新）存储过程客运站提供*19售票接口ProTicketUpdate售票更新存储过程客运站提供*20ProTicketLock锁定座票（新）存储过程客

10、运站提供*21ProTicketUnlock取消锁票（新）存储过程客运站提供*22ProTicketBlankout废票接口存储过程客运站提供*23ProReprint重打印接口存储过程客运站提供*24ProTicketOff退票接口存储过程客运站提供*25读取数据接口tc_scheme班次信息表客运站提供*26tc_stationcode站点编码表客运站提供*27tc_ticketExam检票信息表客运站提供*28tc_ticketsell售票明细表客运站提供*29查询接口ProQuerySell售票明细查询存储过程客运站提供*30班次信息更新ProWrtScheme班次信息更新存储过程客运

11、站提供*客运站提供的接口必须提供相关的用户和口令，并有相应的权限。提示：此接口现阶段的版本为5.0，在原接口4.XX版本上升级而来，为便于用户对比使用，现将与上版本不一致的地方用粗黑体标示加以区别，没有标示粗黑体的则没有变化。3.2 票务中心提供的接口3.2.1 班次更新名称：班次更新功能：将客运站班次增加、停止的信息上传给票务中心。说明：每天凌晨，调用此接口，将本客运站生成的班次信息上传到票务中心；另外，在调度软件中嵌入该接口，在班次发生变化时，调用此接口，将班次变化信息上传给票务中心。一次可传多条记录。该接口在批量上传的时候，可以同时将班次的票价信息上传到中心，票价包括全票价、半票价、学生

12、票价。所传票价仅作参考用，不作为当时交易依据。在正常的调度期间，当票价发生变化时，不需要调用该接口。使用建议：1） 客运站调度软件中，在即时调度中使用该接口，实现小批量次更新；避免在产生总调度计划（全日）时使用。总调度计划（全日）由中心工作人员在凌晨集中提取。2） 客运站即时调度中，班次上传时尽量使用组装成数据集批量上传，不宜分拆成一条条的数据上传，导致频繁的调用班次上传接口。3.2.2 锁定座票名称：锁定座票功能：根据用户输入参数，锁定票务中心数据库的相应票源，并返回锁结果。说明：只在售异地票时使用，售本地票无须再调用任何锁票接口。选定购票数量（座位）后，都应调用该函数，锁定相应票源。如果锁

13、票不成功，则判断返回值，如果属于网络故障或者代理服务器故障，售票软件应接收到错误信息，终止此次交易过程；由于售本地票不调任何锁票接口，不受此限制。 3.2.3 取消锁票名称：取消锁票功能：取消前面的所有锁票操作，或指定座位解锁。缺省值0为取消所有锁票。说明：在售票流程中，调用该接口取消前面的所有锁票请求。只有售票员放弃卖票或者取消当前所选的所有票时，才调用此接口；解锁单个座位，指定输入参数为相应座位。这里原有函数保值不变，增加一个函数LockCancel2，此函数在原来的函数的基础上增加一个输入参数szDepot，用于指示要执行解锁的票在哪个客运站场。3.2.4 售票明细名称：售票明细功能：更

14、新票务中心数据库、异地客运站数据库的售票信息，产生车票防伪码。说明：不论是售本地票还是异地票，都需要调用本接口。售本站票时，先调用本站售票更新接口，如果更新成功，则调用本接口，否则不调用本接口；售异站票时，只需调用本接口即可，用户可以在调用本接口成功后在本站数据库记录售异站票的信息。一次最多允许同时更新60张票，但只能操作同一个客运站的票。退订票、退调票时可以不锁定座位。改乘时，反映当时的售票信息，同正常售票一样。代理点调用时，必须售票更新成功时才能输出防伪码。3.2.5 售票重打印名称：售票重打印功能：更新票务中心数据库，生成防伪码。说明：出现打印错误但尚未退出本次的售票功能时，可以重新打印

15、车票，否则只能通过废票功能来实现。一次可以最多重打1张，但只能操作同一个客运站的票。3.2.6 废票名称：废票功能：将已售出的票作废。说明：对售票更新成功的车票，如果打印出现错误，或者未打印，或者因为特殊原因要将该票废除，此时调用此接口完成废票业务。各客运站（代理点）只能废除本地售出的车票，不能废除别的客运站（代理点）售出的车票，这一功能限制由废票接口内部实现。另外废票时有半小时的时间限制，这一功能限制由废票接口内部实现。只能废自己售出的票。一次最多能废60张票，但只能操作同一个客运站的票。3.2.7 退票名称：退票功能：将已售出的票退掉。说明：退票可在发车站和异地实现，在发车站退票，由各客运

16、站根据自己的业务规则退票；在代售点退票，按照交通部规定全市统一规则退票。退票成功后调用本接口，将退票信息上传至票务中心。在网络故障时，不能异地退票，只能在发车站退票。最多一次可退60张票，但只能操作同一个客运站的票。同时只能退同一个票源站的票。3.2.8 取退票费率名称：取退票费率功能：取票务中心全市统一的退票费率。说明：该接口只是在非发车站退票时调用，即代理点退票按照全市统一的退票费率收取退票手续费。系统自动根据售票时间计算费率，并返还给代理点。在网络故障时，不能异地退票，只能在发车站退票。3.2.9 检票名称：检票功能：将相应票号的已售出车票标志为已检票。说明：在当天的空闲时间，调用此接口

17、，将当天检票信息或打单信息上传到票务中心，可以选择和班次更新时一起上传。一次将整车的信息上传。一次最多500条。3.2.10 对帐明细名称：对帐明细功能：将一定时间段的售票数据，包括退、废、重打印。说明：票务中心和各客运站进行对帐的时候，如果双方的帐目不相同，各客运站需要将指定售票日期范围之内的售、退、废、重打印票的所有数据上传到票务中心，由票务中心找出差异。每次调用最多允许同时上发500条记录。3.2.11 代理认证名称：代理认证功能：检查该用户是否合法使用。说明：只有代理点售票需要调用该接口，接口返回是否合法，。当新密码和旧密码不同时认为修改密码。新密码和旧密码均不允许为空。3.2.12

18、取票号名称：取票号。功能：返回当前的票号串。说明：代理在调用售票更新之前，调用该接口。成功之后才能执行售票更新和打印。每次最多返回30张票号，每10位一个票号，中间没有任何的间隔符号。3.2.13 班次基本信息查询名称：班次基本信息查询功能：根据用户输入参数，查询票务中心数据库，返回符合查询条件的班次信息。本站信息不返回。说明：买票之前必须先进行班次查询，代理点的班次查询和客运站的班次查询不同在于代理的查询只返回中心数据的班次信息，不包含票价等即时信息。3.2.14 取得班次票价名称：取得班次票价功能：根据用户输入参数，返回相应客运站班次的票价信息。说明：除客运站之外，其它客户端在售票时，必须

19、先调用班次查询接口，然后制定班次。输入的参数均是执行SchBaseInfo接口返回的参数。3.2.15 取得中心站点信息名称：取得中心站点信息功能：根据用户输入站点编码缩写或者站点名称名字，返回中心站点信息。说明：输入的参数可以是汉字或者是站点编码的缩写，中心流程自动判断，返回所有符合条件的站点编码，包括中心代码、名称、缩写，如输入“东莞”，中心返回所有站点名称包含东莞的站点信息，如果输入“DG”或者“dg”，中心返回所有站点缩写包含“DG”的站点信息。3.2.16 确认接口名称：确认接口功能：客户端调用售票、重打印、废票、退票等接口操作，如果取得返回值或者在成功完成其它后续操作之后，最少保证

20、成功写入本地数据库，调用该接口进行确认。说明：中心更新根据参数更新相应的记录，如果需要确认的记录超过一定的时间阀值，中心监控软件报警，进入人工处理流程。客户端可以不理会本接口的返回值。当调用中心售、退、废等接口返回非“0”值时，调用该接口，通知中心，接收的是非“0”值。调用中心售、退、废等接口返回 “0”值时，继续往下处理，如果更新本地数据库失败，不调用确认接口。如果成功调用确认接口。确认接口返回值只是提供给调用者写入日志的依据，不用做其它处理。3.2.17 取客运站站点编码名称：取客运站站点编码功能：从客运站提供的表tc_stationcode读取信息，写入到票务中心数据库。说明：如果对本站

21、的站点编码进行了修改，由客运站更新到本表。该表由客运站自动写入，同时可以由票务中心通过存储过程写入到该表。每次调用最多允许同时上发500条记录。3.3 客运站提供的接口3.3.1 取票价名称：取票价功能：获取指定时间、班次（线路）、到站的座位票价、以及座位图等信息。说明：由客运站提供该接口，由投资公司负责调用。3.3.2 售票更新名称：售票更新功能：更新客运站售票记录，写入流水帐。说明：由客运站提供该接口，由投资公司负责调用。如果是多条售票记录，一次更新一条记录，在存储过程里面不要有任何提交和回滚的语句。3.3.3 锁定座票（新增）名称：锁定座票。功能：提供对异站过来的锁票请求进行可售检查，锁

22、定座位的功能，通过参数返回成功锁定的座位串。说明：由客运站提供该接口，由投资公司负责调用。对来自异站的锁票请求，根据班车座位当时的实际准售情况作出正确的回应。对于不指定座位的锁票要求，站方提供锁定满足数量要求的座位，并将锁定的座位信息返回；对于指定座位的锁票请求，如果不能满足，站方提供锁定满足数量要求的其他座位，并将锁定的座位信息返回，中心服务负责将座位号返回给调用终端。对于指定座位的锁票，只提供调用一次锁票锁一个座位的功能，其中参数c_seat只能接收一个长度为3位的座位号。3.3.4 取消锁票（新增）名称：取消锁票。功能：提供对异站过来的解锁请求进行座位解锁。说明：此处的解锁是解锁前面过程

23、ProTicketLock锁定的座位，对终端、座位锁票记录不存在的锁票记录进行解锁，返回0，即函数执行成功。3.3.5 废票更新名称：废票更新功能：更新客运站售票记录，写入废票。说明：由客运站提供该接口，由投资公司负责调用。如果是多条废票记录，一次更新一条记录，在存储过程里面不要有任何提交和回滚的语句。3.3.6 重打印更新名称：重打印更新功能：更新客运站售票记录，写入流水帐。说明：由客运站提供该接口，由投资公司负责调用。如果是多条重打印记录，一次更新一条记录，在存储过程里面不要有任何提交和回滚的语句。3.3.7 退票更新名称：退票更新功能：更新客运站售票记录，写入退票记录。说明：由客运站提供

24、该接口，由投资公司负责调用。如果是多条退票票记录，一次更新一条记录，在存储过程里面不要有任何提交和回滚的语句。3.3.8 班次信息表说明：分配给中心代理的用户必须有在任意时候对表tc_scheme有select、delete、truncate的权限。每天晚上生成班次计划之后全部更新到此表，保证和本站班次信息一致。本表只是批量上传的班次表。少量更新的班次信息仍由客运站客户程序调用班次更新接口。班次信息最迟应该在凌晨1点之前生成。该表由客运站自动写入，同时可以由票务中心通过存储过程写入到该表。3.3.9 站点信息表说明：分配给中心代理的用户必须有在任意时候对表tc_ stationcode有sel

25、ect、delete、truncate的权限。如果对本站的站点编码进行了修改，由客运站更新到本表。该表由客运站自动写入，同时可以由票务中心通过存储过程写入到该表。3.3.10 检票信息表说明：分配给中心代理的用户必须有在任意时候对表tc_ ticketExam有select、delete、truncate的权限。客运站不需要自动写入该表，由票务中心需要时通过调用存储过程写入到该表。3.3.11 售票明细表（财务对帐用）说明：分配给中心代理的用户必须有在任意时候对表tc_ ticketsell有select、delete、truncate和创建索引的权限。包括本站售票、售异站票的信息和被异站售出

26、的票。客运站不需要自动写入该表，由票务中心需要时通过调用存储过程写入到该表。3.3.12 售票查询名称：售票明细信息查询功能：指定票号查询本地数据库相关的售票信息。说明：由客运站提供该接口，由投资公司负责调用。指定用户必须有执行ProQuerySell的权限。3.3.13 班次信息表更新名称：班次信息表更新功能：指定日期（可以限定班次），将相关的班次信息写入到表tc_scheme中。说明：由客运站提供该接口，由投资公司负责调用。指定用户必须有执行ProWrtScheme的权限。建议客运站批量上传也调用该接口。3.3.14 站点编码表更新名称：站点编码表更新功能：全部或指定站点编码，将相关的站点

27、信息写入到表tc_stationcode中。说明：由客运站提供该接口，由投资公司负责调用。指定用户必须有执行ProWrtStCode的权限。建议客运站批量生成时也调用该接口。3.3.15 检票信息表更新名称：检票信息表更新功能：指定日期（可以限定班次），将相关的检票信息写入到表tc_ticketExam中。说明：由客运站提供该接口，由投资公司负责调用。指定用户必须有执行ProWrtTicketExam的权限。建议客运站批量生成时也调用该接口。3.3.16 售票明细表更新名称：售票明细表更新功能：指定日期（可以限定班次），将相关的售票明细信息写入到表tc_ticketsell中。说明：由客运站提

28、供该接口，由投资公司负责调用。指定用户必须有执行ProWrtTicketsell的权限。建议客运站批量生成时也调用该接口。4 其它补充说明的规范4.1 关于电子票电子票是指网上等手段售出的，乘客没有拿到实际的票据，只有票号等信息的票证。乘客在网上完成售票之后，系统提供给乘客一个电子票号（即打印在票面上的条形码），乘客乘车前凭票号和身份证号取得乘车票据。电话号码同时可以作为验证的另一个依据，并可以及时和乘客保持沟通。基于以上功能，客运站需要提供凭票号、身份证或电话号码提取售票记录，并打印该售票记录的功能。另外建议提供相关的监控功能，如发车前一定时间内提示服务员主动联系乘客。即售出的电子票，必须由

29、出票站（包括客运站或其它可以配送打印的代理）在打印完成之后、退票之前、废票之前或者改乘之前必须调用该接口进行确认。具体参见本文档的3.2.4。网上只提供查询和售票功能，不提供此外的其它功能。网上售票时，localdepot为1000。4.2 接口的更新规则接口新版本更换时，凡是涉及到异站售票需要调用的接口必须同时更新为新版本。4.3 异站售票提示和日志各客运站售异站票时，必须按照本文档返回值的不同意思，提示错误信息，便于售票员分清出错源头和票务中心解决错误。如售票明细接口中返回8，就应该提示类似“发车站更新不成功”的信息。各客运站包括票务中心对异站售票，特别是异站售票出现异常时必须有完整的日志

30、记录。5 本地操作关键流程与程序设计参考规范5.1 售本站票5.2 售异站票5.3 退票5.4 废票6 附录6.1 客运站编码编码名称0010珠海市客运联网售票票务管理中心0011珠海市长途汽车运输公司省汽车客运站 0012珠海市第二公共汽车公司珠海汽车客运站 0013珠海新天威交通发展有限公司天河客运站 0014珠海市道路运输站场建设管理中心芳村汽车客运站 0015珠海市长途汽车运输公司越秀南客运站 0016珠海罗冲围客运站有限公司 0017珠海市道路运输站场建设管理中心窖口汽车站0018珠海广园汽车客运有限公司 0019珠海市道路运输站场建设管理中心海珠汽车客运站 0020珠海市锦汉天河大

31、厦汽车客运有限公司 0021佛山市汽车运输集团有限公司广佛客运分公司 0022珠海市第二公共汽车公司东圃汽车客运站 0023珠海市道路运输站场建设管理中心夏茅汽车站 0024珠海市道路运输站场建设管理中心永泰汽车站 0025珠海市道路运输站场建设管理中心黄埔汽车客运站0026珠海白云机场股份有限公司旅客分公司 注意与补充：1、目前0027编码可能预留为新东圃编码，具体待相关工作落实后通知。2、网上售票编码为1000；3、96900服务中心编码为9600；4、代理售票点编码一般首两位数字为“10”，例如中国旅行社编码为1006；其中集团代理点，例如中国旅行社（1006），一般下设多个出票点，每个

32、出票点在中心标识为不同终端，但是对外统一标明出票代理为1006；5、客运站自设的代理点或分支客运站，一般首两位代码取客运站编码的后两位，例如：1201花都客运站；1202增城客运站；1203番禺客运站；1204从化客运站。6.2 班车说明该附录参照广东省物价局、广东省交通厅的关于2004年我省公路客运春运票价的批复文：营运方式：直达、普通车型：大型、中型、小型种类：座席、卧铺档次：高级、中级、普通6.3 退票费计算该规则参见广东省汽车客运站收费规则实施细则。以下是以每票的票额计算的，多票的退票费为计算结果的总和。当次班次开车前时间2小时前办理退票，计算方法为“退票费率票面金额”，结果如果不足0

33、.5元，按0.5元计算。当次班次开车前时间2小时以内办理退票，计算方法为“退票费率票面金额”，结果如果不足1元，按1元计算。6.4 V5.0不再使用的的接口列表注:考虑向下兼容仍保留。6.4.1 锁定座票名称：锁定座票功能：根据用户输入参数，锁定票务中心数据库的相应票源，并返回锁结果。说明：不论是售本站票，还是售异站票，每次选定购票数量（座位）后，都应调用该函数，锁定相应票源。如果锁票不成功，则判断返回值，如果属于网络故障或者代理服务器故障，则转向本站售票模式，采用本站售票软件锁定票源。6.4.2 取消锁票名称：取消锁票功能：取消前面的所有锁票操作，或指定座位解锁。缺省值0为取消所有锁票。说明

34、：在售票流程中，调用该接口取消前面的所有锁票请求。只有售票员放弃卖票或者取消当前所选的所有票时，才调用此接口；解锁单个座位，指定输入参数为相应座位。6.4.3 取得班次票价名称：取得班次票价功能：根据用户输入参数，返回相应客运站班次的票价信息。说明：除客运站之外，其它客户端在售票时，必须先调用班次查询接口，然后制定班次。输入的参数均是执行SchBaseInfo接口返回的参数。6.4.4 取票价（存储过程）名称：取票价功能：获取指定时间、班次（线路）、到站的座位票价。说明：由客运站提供该接口，由投资公司负责调用。6.5 新流程主要特性及设计原理图示1、 锁票与解锁2、本地票售票更新（包括本地退、废、重打印）