院线通客户端接口协议分析要点.docx
《院线通客户端接口协议分析要点.docx》由会员分享，可在线阅读，更多相关《院线通客户端接口协议分析要点.docx（89页珍藏版）》请在冰豆网上搜索。
院线通客户端接口协议分析要点
密级：
机密—JM
文档编号：
ENG01_01
院线通与客户端接口
协议分析
洪正
广东凯通软件开发有限公司
广东凯通软件开发有限公司对本文件资料享受著作权及其它专属权利，未经书面许可，不得将该等文件资料（其全部或任何部分）披露予任何第三方，或进行修改后使用。
更改记录
日期
版本号
修订说明
修订人
审核人
批准人
2012-11-15
V1.0
院线通-客户端接口协议
洪正
模版使用须知
在撰写文档时，应先仔细阅读模版说明，并遵循以下要求。
1.除示例和有特殊说明处外，本模版的黑色字体部分必须保留。
对不适用或需略过的章节，应保留标题，在内容处写“不适用”或“略”。
只有特殊情况才能略过，并需说明原因。
除附录外，应严格遵循模版框架，不应添加大纲章节；不应更改章节标题（除绿色部分外）。
2.作者可以在大纲下自行扩展层次。
3.作者可在附录里添加章节。
4.不能采用模棱两可的陈述。
对不能确定的技术问题，应明确列出，并详细说明原因。
5.本模版的蓝色部分是文档写作要求和指引，正式文档中必须删除。
6.本模版的绿色部分，需要根据实际情况修改。
7.写作完毕后，必须更新目录。
8.对于文档的修改，应改一处，就及时填写更改记录。
9.碰到模版不能解决的问题，请与模版作者联系。
摘要
本文的内容摘要。
更改记录2
摘要4
目录5
1.缩略语10
2.范围和限制11
2.1.分析范围11
2.2.适用限制11
3.院线通与客户端接口协议概述12
3.1.相关网络结构12
3.2.协议栈12
3.3.协议介绍13
3.4.协议识别13
3.5.业务描述13
4.信令业务流程15
5.消息分析16
5.1.编码方式16
5.2.消息结构16
5.3.消息分类和列表17
5.4.主要消息及其关键字段18
5.4.1.院线通一期接口18
5.4.1.1.影院影厅信息查询querycinema18
5.4.1.2.当日影片信息查询querycinemamovies19
5.4.1.3.片场次查询querymovietime20
5.4.1.4.余票信息查询（仅星海音乐厅）getticketnum21
5.4.1.5.自动选座autoselectseat21
5.4.1.6.订单座位释放unlockseat22
5.4.1.7.订单交易确认fixorder22
5.4.1.8.订单查询qryorder23
5.4.1.9.生成订单generateorder25
5.4.1.10.更新订单updateorder26
5.4.2.院线通二期接口27
5.4.2.1.影院查询qrycinema27
5.4.2.2.影院影片查询qryfilm28
5.4.2.3.热门影片查询qryhotfilm29
5.4.2.4.根据影片名查询排期qryshowbyfilmname30
5.4.2.5.根据影片名查询影院qrycinemabyfilmname31
5.4.2.6.根据影片甄选城市qrycitybyfilmname31
5.4.2.7.排期查询qyrshow32
5.4.2.8.排期查询qryshowbyid32
5.4.2.9.影厅座位图查询qryhallseat33
5.4.2.10.排期座位图查询qryshowseat34
5.4.2.11.滚动广告查询qryad35
5.4.2.12.开通城市查询qrycity35
5.4.2.13.手机号码查询qryhone36
5.4.2.14.手机归属地查询qryphplace36
5.4.2.15.订单查询qryorder37
5.4.2.16.手工选坐selectseat38
5.4.2.17.自动选坐autoselectseat40
5.4.2.18.客户端首界面基础信息查询qrybasedata41
5.4.2.19.当日播放所有影片查询qryonedayfilm42
5.4.2.20.订单重锁座位lockseat43
5.4.2.21.非常规系统错误提示接口qrysysteminfo44
5.4.2.22.根据cityid获取下属区县qrycountys44
5.4.2.23.订单查询qryorderinfo45
5.4.2.24.判断是否新用户ifNewCustomer45
5.4.2.25.用户注册userReg46
5.4.2.26.获取验证码getVerifycode46
5.4.2.27.用户登录userLogin47
5.4.2.28.用户密码重置resetPassword47
5.4.2.29.用户观看片花信息上报filmClip48
5.4.2.30.抢票活动排期信息qryShowPolicy49
5.4.2.31.新片上映订阅/退订subscribeFilm49
5.4.2.32.新片上映订阅.退订查询qrySubscribeFilm50
5.4.2.33.影币转送presentFilmCoin50
5.4.2.34.邀请好友sendFriendReq51
5.4.2.35.处理好友请求dealFriendReq51
5.4.2.36.查询好友列表qryFriend52
5.4.3.支付接口53
5.4.3.1.加密接口EncryptSign53
5.4.3.2.新加密接口WapEncryptSign53
5.4.3.3.Wap网银支付Http跳转serverUrl54
5.4.3.4.Web网银支付Http跳转WebEncryptSignServlet54
5.4.3.5.查询支付方式列表cpayandcheckinQuery55
5.4.3.6.查询支付结果cpayandcheckinQuery55
5.4.3.7.支付扣费请求clientpayservlet56
5.4.3.8.支付扣费请求cpayOrderServlet57
5.4.3.9.自助终端代金卷验证接口validateAccount57
5.4.3.10.优惠劵验证接口validateCoupon58
5.4.3.11.支付申请短信验证码请求cpayOrderServlet59
5.4.3.12.账户查询请求cpayOrderServlet59
5.4.3.13.查询支付方式qryPayType60
5.4.4.院线通二维码接口61
5.4.4.1.自助终端验票接口validEVoucher61
5.4.4.2.出票上报通知接口notifyPrintStatus62
5.4.5.优惠劵接口62
5.4.5.1.优惠劵派发voucherDisptch62
5.4.5.2.个人账号优惠劵查询queryPersonInfo63
5.4.5.3.优惠劵查询接口queryVoucher63
5.4.5.4.影币查询接口queryFilmCoin64
5.4.6.演出类接口65
5.4.6.1.场馆查询qryVenue65
5.4.6.2.热门演出节目查询qryHotevent65
5.4.6.3.根据主id查询热门演出节目qryHoteventById66
5.4.6.4.根据热门演出查询排期qryShowByHotevent67
5.4.6.5.根据场馆编号查询排期qryShowByVenueId67
5.4.6.6.根据排期编号查询排期qryShowByShowId68
5.4.6.7.自动选座antoSelectSeat68
5.4.6.8.订单释放unlockActSeat69
6.XDR设计71
6.1.TDR设计71
6.1.1.通用部分71
6.1.2.专用部分71
6.2.CDR设计71
6.2.1.通用部分71
6.2.2.专用部分72
6.3.MDR设计74
6.3.1.通用部分74
6.3.2.专用部分74
7.合成准则75
7.1.院线通客户端与院线通接入平台接口协议内部合成75
7.2.协议和其它协议的关联75
8.参考资料76
8.1.内部资料76
8.2.外部资料76
9.附录77
9.1.重要字段枚举类型77
9.1.1.系统状态码定义77
9.1.2.IMSI定义77
9.1.3.支付模块接口返回状态码定义78
10.定时器79
1.缩略语
无
2.范围和限制
无
2.1.分析范围
无
2.2.适用限制
无
3.院线通与客户端接口协议概述
院线通平台与客户端之间的接口采用Http协议进行通信。
用户通过手机院线通客户端与接入平台进行消息交互，用户登陆到院线通客户端后，可以对各影院进行相应的影院业务操作，如查询影院信息，查询对应影院日期的排期（具体日期的具体时段放什么影片），获取影厅座位信息并选取座位等，并且可以通过支付平台进行影票订购的支付。
3.1.相关网络结构
院线通平台内部由两个平台组成，分别为接入平台和订购平台。
用户通过院线通客户端首先连接到接入平台，接入平台将消息传递到订购平台后，具体与院线通的其他业务系统进行交互。
具体网络图如下：
本文档只对院线通接入平台与院线通客户端之间的接口协议进行分析，其他接口协议不做详细描述。
3.2.协议栈
院线通接入平台与院线通客户端之间的接口协议采用http协议，接口协议栈和http协议的协议栈结构一致。
3.3.协议介绍
本协议接口是用于院线通接入平台与院线通客户端之间的接口协议。
其主要作用是用于用户的日常影院订票业务，包括影院查询，影片排期查询，影厅座位查询和订座，支付等。
负责客户端与院线通之间的通信。
3.4.协议识别
在院线通接入平台与客户端之间的接口为Http协议，在接入平台与客户端的通信端口为7001或者7101两个端口，在抓包程序中可以根据这个数据特点获取此接口数据，但是此两个端口通信的数据并不全部是客户端与接入平台的数据，还有部分其他类型的数据，所以在采集程序中需要对接收到的数据做二次挑选，在请求消息中由于接入平台和客户端数据HTTP请求行中有mobileyxt字符，可将不含有此字符的消息丢弃，而在响应消息中存在其他数据中的content-Type字段值为text/html或者text/xml，所以目前可以将响应消息中的为这两种类型的消息丢弃。
消息特点还待进一步的验证，寻找更好的其他方法。
在承载层之上的具体业务层，则需要分析其具体的消息格式和消息内容，以确定消息类型。
消息格式必须满足http协议规则，并且具体消息格式满足接口规范，消息结构请具体看消息分析章节。
3.5.业务描述
院线通客户端与接入平台之间的业务都是与影院相关的业务，这里的影院可以是电影，也可以是其他演出场馆相关的业务。
其具体的操作有如下几种：
1、查询影院信息，包括影院编号、影院所在地址、名称、授权日期等
2、查询具体影院具体日期的排期，包括影院什么时间几号影厅放什么影片，票价和是否可预订等信息
3、选取座位，包括查看影厅的所有座位信息和状态，当有座位时可以锁定用户的座位等
4、确认订单，取消订单，更新订单等于订单相关的其他操作
5、支付，用户在确定自己的订单后，需要进行支付操作，用户通过客户端选择不同的支付方式，进行支付扣费请求，当然也包括对账户的查询等操作，接入平台收到支付相关的消息后，将进一步的将请求发送到支付平台进行具体的处理。
其接入平台与支付平台之间的接口不在本文的分析范围内，具体参考商户与支付平台之间的接口协议。
整个用户订购影票的简易流程如下图所示：
4.信令业务流程
本文分析业务接口为院线通客户端与院线通接入平台之间的接口，其基本的信令流程如下图所示：
用户所有的操作，如影院查询，影厅查询，排期查询，选座，生成订单，支付等操作，其信令流程都为院线通客户端向院线通接入平台发起请求，然后由院线通接入平台将消息发送到具体的平台处理，当处理完成后，将其响应返回给院线通客户端。
其业务关联部分也只需要将这一对请求与相应进行相应的组合。
5.消息分析
5.1.编码方式
http协议为文本协议，其消息格式符合http协议规范，具体的消息举例如下，虽然消息类型一致，但其消息中的有效信息的位置却是不一样的，在程序处理时需要区别对待。
1、消息的有效位置处于http请求行中，且其消息字段用&符号进行分割，此种消息主要解析消息请求行
GET/mobileyxt/jsoniface/qryonedayfilm.htm?
imsi=web001&showdate=2012-11-05HTTP/1.1
User-Agent:
JakartaCommons-HttpClient/3.0
Host:
:
7101
2、消息的有效位置处于http消息中的内容部分，消息字段用&号分割
POST/mobileyxt/jsoniface/cpayOrderServletHTTP/1.1
Content-Length:
155
Content-Type:
application/x-www-form-urlencoded
Host:
183.63.133.183:
7001
Connection:
Keep-Alive
User-Agent:
HttpRequestUtils
Account=18922287261&busitype=film&method=queryAccount&imsi=460000520738550&teml=%5BMotorola%5D%5BXT615%5D%5BANDROID%5D%5B4.0.1.0%5D%5Bnull%5D&AccountType=7
消息解析位置判断方法：
根据消息中的Content-Length的值来判断，若Content-Length值不为0，则内容在消息内容部分，当不存在Content-Length时，消息有效内容在消息请求行中，需要在大量消息中验证
5.2.消息结构
院线通客户端与院线通接入平台消息采用http协议，其消息结构符合http协议标准。
5.3.消息分类和列表
主要接口及消息类型如下表格
接口名
消息类型
影院查询
qrycinema
影院影片查询
qryfilm
根据影片名查询排期
qryshowbyfilmname
根据影片名查询影院
qrycinemabyfilmname
根据影片甄选城市
qrycitybyfilmname
根据影院和影片查询排期
qryshow
根据影院和影片查询排期
qryshowbyid
影厅座位图查询
qryhallseat
排期座位图查询
qryshowseat
滚动广告查询
qryad
开通城市查询
qrycity
手机号码查询
qryphone
手机归属地查询
qryphplace
订单查询
qryorder
手工选坐
selectseat
自动选坐
autoselectseat
客户端首界面基础信息查询
qrybasedata
当日播放所有影片查询
qryonedayfilm
订单重锁座位
lockseat
非常规系统错误提示
qrysysteminfo
根据cityid获取下属区县
qrycountys
订单查询
qryorderinfo
用户注册
userReg
获取验证码
getVerifycode
用户登录
userLogin
用户密码重置
resetPassword
用户观看片花信息上报
filmClip
抢票活动排期信息
qryShowPolicy
新片上映订阅/退订
subscribeFilm
新片上映订阅/退订查询
qrySubscribeFilm
硬币转送
presentFilmCoin
邀请好友
sendFriendReq
处理好友请求
dealFriendReq
查询好友列表
qryFriend
加密接口
EncryptSign
新加密接口
WapEncryptSign
Wap网银支付Http跳转
serverUrl
Web网银支付Http跳转
WebEncryptSignServlet
查询支付方式列表
cpayandcheckinQuery
查询支付结果
cpayandcheckinQuery
支付扣费请求（WAP客户端）
clientpayservlet
支付扣费请求
cpayOrderServlet
自助终端代金卷验证接口
validateAccount
优惠劵验证接口
validateCoupon
账户查询请求
cpayOrderServlet
查询支付方式
qryPayType
自助终端验票接口
validEVoucher
出票上报通知接口
notifyPrintStatus
优惠劵派发
voucherDisptch
个人账号优惠劵查询
queryPersonInfo
优惠劵查询接口
queryVoucher
影币查询接口
queryFilmCoin
判断是否新用户
ifNewCustomer
场馆查询
qryVenue
热门演出节目查询
qryHotevent
根据主ID查询热门演出节目
qryHoteventById
根据热门演出查询排期
qryShowByHotevent
根据场馆编号查询排期
qryShowByVenueId
根据排期编号查询排期
qryShowByShowId
自动选座
autoSelectSeat
订单释放
unlockActSeat
5.4.主要消息及其关键字段
5.4.1.院线通一期接口
5.4.1.1.影院影厅信息查询querycinema
消息含义：
获取所有影院信息
请求参数说明：
参数
类型
值条件
含义
无
响应参数说明：
参数
类型
值条件
含义
id
string
必须
影院编号8位
spCode
string
必须
SP代码
name
string
必须
影院名称
linkId
string
必须
影院连接编码
local
string
影院所在地区
hallCount
Number
影厅数量
address
string
影院地址
contact
string
联系方式
5.4.1.2.当日影片信息查询querycinemamovies
消息含义：
查询某影院指定一天的电影介绍信息
请求参数说明：
参数
类型
值条件
含义
cinemaId
string
必须
影院编号8位
cinemaLinkID
string
必须
影院连接编码
showDate
string
必须
场次日期
spCode
string
必须
SP代码
响应参数说明：
参数
类型
值条件
含义
id
string
必须
影院编码
name
string
必须
影院名称
title
string
必须
影院别名
language
string
必须
影片语言
duration
Number
必须
影片总时长
actor
string
主演
director
string
导演
desc
string
描述
startdate
string
播放开始日期
enddate
string
播放结束日期
5.4.1.3.片场次查询querymovietime
消息含义：
获取某影院某电影的排期
请求参数说明：
参数
类型
值条件
含义
showdate
string
必须
星海为截止日期，其余为查询日期
cinemaId
string
必须
影院编号
cinemaLinkId
string
必须
影院连接编码
spCode
string
必须
SP代码
movieid
string
必须
影片id
响应参数说明：
参数
类型
值条件
含义
cinemaId
string
必须
影院编号8位
seqno
string
必须
场次编号
showseqno
string
必须
场次内部编号，用于锁位，确定订单等参数
date
string
必须
场次日期
time
string
必须
场次时间
hall
string
必须
影厅名称
hallId
string
必须
2位
price
string
必须
电影票价
ticketnum
int
必须
余票数量
totlenum
int
必须
总票数
filmname
string
影片ID
otherstring
string
其他信息
5.4.1.4.余票信息查询（仅星海音乐厅）getticketnum
消息含义：
取回当前演出所有余票情况
请求参数说明：
参数
类型
值条件
含义
showid
string
必须
演出id,返回可销售的所有分区的余票情况
响应参数说明：
参数
类型
值条件
含义
ticketType
Varchar（50）
必须
票等级
ticketTypeID
int
必须
票等级ID
section
Varch（20）
必须
分区名称
sectionid
int
必须
分区ID
ticketnum
int
必须
余票数
price
int
必须
票价
5.4.1.5.自动选座autoselectseat
消息含义：
向SP以订单形式提交自动选座请求
请求参数说明：
参数
类型
值条件
含义
spCode
string
必须
SP代码
cinemaId
string
影院编号，星海可选，其余必填
flowId
string
流水号，满天星必填
ticketprice
number
票价
p
升级会员 