JTT 1443.2-2022 水路客运电子船票系统技术规范 第2部分：服务接口

目　　次前言Ⅱ…………………………………………………………………………………………………………引言Ⅲ…………………………………………………………………………………………………………1　范围1………………………………………………………………………………………………………2　规范性引用文件1…………………………………………………………………………………………3　术语和定义、缩略语1………………………………………………………………………………………4　通用要求1…………………………………………………………………………………………………5　报文结构3…………………………………………………………………………………………………6　系统接口3…………………………………………………………………………………………………附录A(规范性)　接口内容5………………………………………………………………………………ⅠJT/T1433.2—2022前　　言本文件按照GB/T1.1—2020《标准化工作导则　第1部分:标准化文件的结构和起草规则》的规定起草。本文件是JT/T1433《水路客运电子船票系统技术规范》的第2部分。JT/T1433已经发布了以下部分:———第1部分:电子船票;———第2部分:服务接口。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由交通运输信息通信及导航标准化技术委员会提出并归口。本文件起草单位:中国交通通信信息中心、中交信有限责任公司、大连市水路运输协会、大连港客运总公司、交通运输部烟台打捞局、海南港航控股有限公司、重庆航运交易所邮轮旅游服务公司。本文件主要起草人:张鹏、邓英、姜锋俊、鲍雨新、张明伟、朱火孟、陈本锡、解超、于渤、张勇、郑力、张亮、蔡迎、耿奕伟、陈献国。ⅡJT/T1433.2—2022引　　言JT/T1433《水路客运电子船票系统技术规范》用于指导水路客运电子船票系统建设,为实现跨区域联网售票和跨交通运输方式的联程运输奠定基础。JT/T1433旨在规范水路客运电子船票的信息、凭证以及电子船票系统的服务接口,由两个部分构成。———第1部分:电子船票。目的在于统一电子船票的信息内容及样式,方便进行信息交换和互联互通。———第2部分:服务接口。目的在于统一水路客运电子船票系统的服务接口,便于快速进行系统对接,提高效率和节约成本。ⅢJT/T1433.2—2022水路客运电子船票系统技术规范第2部分:服务接口1　范围本文件规定了水路客运电子船票系统服务接口的通用要求、报文结构和接口内容。本文件适用于水路客运电子船票系统服务接口的设计、开发和使用。2　规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中,注日期的引用文件,仅该日期对应的版本适用于本文件;不注日期的引用文件,其最新版本(包括所有的修改单)适用于本文件。JT/T697.8　交通信息基础数据元　第8部分:水路运输信息基础数据元JT/T979.1　道路客运联网售票系统　第1部分:服务接口规范JT/T1433.1—2022　水路客运电子船票系统技术规范第1部分:电子船票RFC2616　超文本传输协议HTTP/1.1(HypertextTransferProtocol-HTTP/1.1)3　术语和定义、缩略语3.1　术语和定义JT/T697.8、JT/T979.1、JT/T1433.1及RFC2616中界定的术语和定义适用于本文件。3.2　缩略语下列缩略语适用于本文件。HTTP:超文本传输协议(HypertextTransferProtocol)JSON:Java脚本语言对象符号(JavaScriptObjectNotation)REST:表征状态转移(RepresentationalStateTransfer)SOA:面向服务架构(ServiceOrientedArchitecture)URI:通用资源标识符(UniformResourceIdentifier)4　通用要求4.1　水路客运电子船票系统应基于HTTP协议进行通信。4.2　水路客运电子船票系统接口请求和返回数据应进行签名,校验数据的完整性。签名数据保存在HTTP消息头中,业务数据保存在HTTP消息体中,使用JSON协议解析。4.3　接口请求响应通用状态码应符合表1的规定。接口请求响应业务状态码应符合表2的规定。1JT/T1433.2—2022表1　接口请求响应通用状态码通用状态码说　　明200服务调用成功400请求格式错误401未授权访问402不可识别403服务器拒绝访问404指定的资源未找到408请求超时500服务器内部错误504响应超时表2　接口请求响应业务状态码业务状态码说　　明10000成功10001请求格式错误10101航线信息授权异常10201船舶信息授权异常10301航班信息授权异常10401获取订单船票数量上限授权异常10501获取电子船票基础信息失败10601获取电子客票信息失败10701获取退票手续费失败10702该窗口不可退票10703退票操作失败10801获取预存款信息失败10901押金查询失败11001获取交易记录失败11002未获取到交易记录11201获取车辆类型信息失败11301获取车辆长度信息失败11401货物类型查询失败11501获取电子车票可选舱位信息失败11601获取电子车票票价信息失败11701获取退票原因失败11801锁定舱位订单提交失败2JT/T1433.2—2022表2　接口请求响应业务状态码(续)业务状态码说　　明11901订单售票失败11902订单不存在11903锁票失败11904订单状态不正确12401订单支付失败12501解锁失败　　注:响应业务状态码可能会随业务发展进行扩展。5　报文结构5.1　报头HTTP消息报头包括普通报头、请求报头、响应报头和实体报头。HTTP消息报头应符合表3的规定。表3　报　　头协议字段字　段　值说　　明　Accept　application/json　接收或返回的json类型数据　Content-type　application/json　Content为json类型数据5.2　请求正文请求正文支持JSON格式,每个请求正文由公共请求信息和接口请求信息组成。JSON格式请求正文具体形式应符合如下规定:{pubrequest:{},body:{}}5.3　响应正文响应正文支持JSON格式,每个响应正文由公共返回信息和接口返回信息组成。JSON格式响应正文具体形式应符合如下规定:{pubresponse:{},body:{}}6　系统接口水路客运电子船票系统应至少提供表4所列的服务接口,接口内容应符合附录A的规定。3JT/T1433.2—2022表4　服务接口序号接口名称中文名称英文名称接口说明1　查询航线信息　bsRoute　查询从某始发港出发的所有航线信息2　查询航班信息　plPlan　查询某指定航线的航班信息3　查询客票余票信息　ticketsInfo　查询当前航班余票的汇总信息,以及票价详情4　查询退票手续费　refundTicketsInfo　查询指定电子船票的退票手续费5　查询车型等级　bsCarType　查询当前航班的可用车型等级6　查询货物类型　bsGoodsType　查询当前航班允许车载货物的类型7　查询车辆可选舱位　bsAllowedBerth　查询当前航班车辆的可选舱位信息8　查询车票价格信息　bsPriceInfo　查询指定车型、车长、货物类型的电子车票票价9　查询订单信息　orderDetailInfo　查询指定订单号下的电子船票订单详情10　查询改签状态　changeDetailInfo　根据电子船票号查询是否可改签,以及可改签的航班等信息11　锁票　lockTicket　根据提供的信息锁定舱位并生成订单12　解锁　unlockTicket　将已锁舱位进行解锁操作13　出票　saleTicket　将某一订单内的所有电子船票做出票处理14　退票　refundTicket　根据电子船票号对指定电子船票进行退票操作15　销票　voidTicket　根据电子船票号将指定电子船票做销票处理16　改签　changeTicket　根据电子船票号将指定电子船票进行改签17　检票　checkTicket　根据电子船票号对指定电子船票进行检票4JT/T1433.2—2022附　录　A(规范性)接口内容A.1　接口公共信息A.1.1　公共信息内容应提供表4所规定接口的请求和返回的公共信息内容。A.1.2　公共请求信息公共请求信息定义应符合表A.1的规定。表A.1　公共请求信息定义数据项名称数据项描述数据项格式约　　束　授权码　调用方被授权后获得唯一授权码　10位字符串类型M　版本　指明接口版本号　V+1位整数+1位小数M　发送时间　发送时间　YYYYMMDDhhmmssM　　注:M表示必填,O表示可选。下同。A.1.3　公共返回信息公共返回信息定义应符合表A.2的规定。表A.2　公共返回信息定义数据项名称数据项描述数据项格式约　　束　版本　指明接口版本号　V+1位整数+1位小数M　返回时间　返回时间　YYYYMMDDhhmmssM　返回状态码　本接口的返回状态　按照表2要求M　返回状态说明　返回状态的详细说明　字符串类型MA.2　查询航线信息A.2.1　请求内容请求内容应符合表A.3的规定。表A.3　查询航线信息请求内容数据项名称数据项描述数据项格式约　　束　公共请求信息　包含公共请求内容　按照表A.1要求M　始发港代码　始发港口的代码　按照JT/T1433.1—2022　表A.1中编号A16要求　M5JT/T1433.2—2022A.2.2　返回内容返回内容应符合表A.4的规定。表A.4　查询航线信息返回内容数据项名称数据项描述数据项格式约束　公共返回信息　包含公共返回内容　按照表A.2要求M　航线信息集合　包含所有航线的信息　按照表A.5要求M航线信息内容应符合表A.5的规定。表A.5　航线信息内容数据项名称数据项描述数据项格式约束　航线代码　航线的代码　按照JT/T1433.1—2022表A.1中编号A14要求　M　航线名称　航线的名称,如大连-烟台　按照JT/T1433.1—2022表A.1中编号A15要求　M　始发港名称　始发港口的名称,如大连湾新港　按照JT/T1433.1—2022表A.1中编号A17要求　M　终到港名称　终到港口的名称,如蓬莱新港　按照JT/T1433.1—2022表A.1中编号A19要求　MA.3　查询航班信息A.3.1　请求内容请求内容应符合表A.6的规定。表A.6　查询航班信息请求内容数据项名称数据项描述数据项格式约束　公共请求信息　包含公共请求内容　按照表A.1要求　M　航线代码　航线的代码　按照JT/T1433.1—2022表A.1中编号A14要求　M　承运船号　本航班承运船的编号　按照JT/T1433.1—2022表A.1中编号A21要求　M　始发港代码　始发港口的代码　按照JT/T1433.1—2022表A.1中编号A16要求　M　乘船日期　航班开航的日期　按照JT/T1433.1—2022表A.1中编号A28要求　M6JT/T1433.2—2022A.3.2　返回内容返回内容应符合表A.7的规定。表A.7　查询航班信息返回内容数据项名称数据项描述数据项格式约束　公共返回信息　包含公共返回内容　按照表A.2要求M　航班信息集合　包含所有的航班信息　按照表A.8要求M航班信息内容应符合表A.8的规定。表A.8　航班信息内容数据项名称数据项描述数据项格式约束　航班代码　本次承运任务所属的班次代码　按照JT/T1433.1—2022表A.1中编号A20要求　M　承运船号　本航班承运船的编号　按照JT/T1433.1—2022表A.1中编号A21要求　M　船舶名称　本航班承运船的名称　按照JT/T1433.1—2022表A.1中编号A22要求　M　乘船日期　航班开航的日期　按照JT/T1433.1—2022