atitit.恒朋无纸化彩票系统数据接入通信协议

深圳市恒朋科技开发有限公司

Shenzhen Helper Science & Technology Co., Ltd.

恒朋无纸化彩票系统数据接入通信协议

文档版本历史

内容目录

恒朋无纸化彩票系统数据接入通信协议............................................1

文档版本历史..................................................................2

内容目录......................................................................3

1.文档定义....................................................................4

1.1名词表和缩略语..........................................................4

1.2文档约定................................................................4

2.概述........................................................................5

2.1角色定义................................................................5

2.2交易交互过程............................................................5

3. 交易消息定义...............................................................6

3.1 http参数...............................................................6

3.2消息包..................................................................6

3.3消息头..................................................................8

3.4消息体.................................................................11

3.4.1奖期通知...........................................................11

3.4.2奖期查询...........................................................12

3.4.3投注...............................................................14

3.4.4投注结果通知.......................................................17

3.4.5票查询.............................................................19

3.4.6返奖查询...........................................................21

3.4.7销量查询...........................................................22

4总述........................................................................24

附录A 玩法参数说明...........................................................25

附录B 响应状态码说明.........................................................26

附录C 投注号码格式说明.......................................................28

附录D 玩法奖等参数说明.......................................................32

1.文档定义

第三方投注代理商如果要实现接入恒朋无纸化彩票系统，需要参考两份文档，一份是《恒朋无纸化彩票系统数据接入技术方案》，以及当前的这份《恒朋无纸化彩票系统数据接入通信协议》。《恒朋无纸化彩票系统数据接入技术方案》说明了第三方投注代理商与恒朋无纸化彩票系统的连接与通信的技术方案，《恒朋无纸化彩票系统数据接入通信协议》说明了通信的数据结构。这两份文档的所有权归属于深圳市恒朋科技开发有限公司。

1.1名词表和缩略语

MD5

HTTP

XML

SCHEMA

1.2文档约定

● 文档备注部分会使用10号字体，并且会注明：注。

● 文档当前版本相对与上一个版本的变化会使用蓝色字体显示。

2.概述

恒朋无纸化彩票系统可以接入多个第三方投注代理商，为接入的第三方投注代理商提供数据落地服务，同时也为第三方投注代理商实现了彩票的无纸化销售方式。

注：更多信息可以参考《恒朋无纸化彩票系统数据接入技术方案》

2.1角色定义

● 投注代理商：也可以叫做第三方投注代理商，它提供用户界面，接收用户投注请求，管理用户的投注资金，返奖。

● 恒朋无纸化彩票系统：接收投注代理商的投注数据，完成开兑奖，为投注代理商提供数据落地的服务。

2.2交易交互过程

在第三方投注代理商与恒朋无纸化彩票系统之间的交互过程中，有由第三方投注代理商主动发起请求，也有恒朋无纸化彩票系统主动发起请求。当任一方主动发起请求的时候，发起请求的一方为请求方，接收请求的一方为响应方。下图说明了第三方投注代理商与恒朋无纸化彩票系统之间的交互过程：

当前恒朋无纸化彩票系统默认支持的数据传输协议为HTTP，所以每一个交互都是一个请求/响应的模式。消息发送方发出请求之后，需要等待响应，并且处理响应信息。

3. 交易消息定义

3.1 http参数

交易交互是以http协议作为数据传输协议，这里定义发起交易请求的一端为客户端，客户端需要以http post的方式提交交易请求，在交易请求中需要定义一下两个参数：

参数名

参数说明

交易类型, 参考‘ 消息头’ 部分关于交易类型的定义，比如103

交易消息包

这里假设有一个奖期查询的交易请求，那么http消息体的内容如下：

transType=102&transMessage=<?xml version="1.0" encoding="GBK"?><message version="1.0" id="3899122007051000000231"><header> <messengerID>389912</messengerID><timestamp>20070510092433</timestamp><transactionType>101</transactionType> <digest>8123f913e123e123990028d9c72e013c</digest></header> <body> <issueQuery><issue gameName="ssc" number="2007051001"/></issueQuery> </body></message>

注：实际http传输中，可能对内容进行编码。

3.2消息包

每一个请求/响应的消息包都是一个xml的字符串，包含消息头和消息体，对于不同类型的请求/响应（比如投注和奖期查询），消息头的格式是相同的，而消息体会携带具体的特定类型的请求/响应信息。

请参照下面的消息包格式定义

[消息包示例1—奖期通知请求]

<?xml version="1.0" encoding="GBK"?>

<?xml version="1.0" encoding="GBK"?>

[消息头] <timestamp>20070510092435</timestamp>

<digest>8123f913e123e123990028d9c72e0dfgds</digest>

</header>

<body>

[消息体] <response code="0000" message="成功,系统处理正常"/>

</body>

</message>

[消息包示例2—奖期通知响应]

整个消息包是一个xml字串，首先声明xml的版本和编码，这里定义encoding为GBK。在消息包元素message中声明了version和id两个属性，其中：

version 表示该消息包使用的数据通信协议的版本，当前为1.0

id 表示这个交易消息包的编号，这个编号必须保证在恒朋无纸化彩票系统唯一。对于同一个交易，请求/响应的消息id应该是相同的。编号的生成规则为（agentID+8位时间戳(YYYYMMDD)+8位递增流水号），其中：

agentID是恒朋无纸化彩票系统为第三方投注代理商分配的唯一编号。

递增流水号从1开始到99999999,每次递增1, 到达99999999之后重新从1开始，由投注代理商自己管理，不足8位的左边补0。

比如某个编号为389912的代理在2007年5月10日发起了一个奖期查询的请求，那么请求的消息包的id为3899122007051000000231，其中递增流水号为231。

关于消息头和消息体的描述，请参照后续章节。

注: 在这份文档的示例部分，我们总假定投注代理商的编号为389912

3.3消息头

消息头对于所有的交易请求以及对每个交易请求的请求/响应都具有同样的数据结构，其中所包含的信息描述了消息包的发送方，消息发送的时间，交易请求的类型以及对消息包的部分信息的摘要。

注：在后面对交易请求消息体的描述中不再重复说明消息头的结构。

</header>

header元素定义了消息头的数据结构，其中：

名称

数据类型

必需

长度

描述

[消息头]

交易类型。每个交易包括请求和响应，当前支持以下交易类型：

● 时间戳：即消息头中timestamp元素的值。

● 投注代理商密码：恒朋无纸化彩票系统会为每个投注代理商分配一个访问密码，这个密码不会在消息中直接传输。无论是投注代理商向恒朋无纸化彩票系统发送消息还是恒朋无纸化彩票系统向某个代理发送消息，都会使用投注代理商的密码来执行摘要。

● 消息体：消息包中body元素部分。

假设一个请求消息如下：

<?xml version="1.0" encoding="GBK"?>

</header>

<body>

</issueQuery>

</body>

</message>

那么，被摘要的字串应该是（假设投注代理商的密码为111111）：

389912200705101234567820070510102433111111<body> <issueQuery><issue gameName="ssc" number="2007050102"/></body>

注：被摘要的body元素部分应该保留消息字串中的所有格式信息，比如空格。

同时，该奖期查询请求的响应消息应该为：

<?xml version="1.0" encoding="GBK"?>

</header>

<body>

<issue gameName="ssc" number="2007051002"

status="5" bonusCode="1,2,3,4,5"/>

</reponse>

</body>

</message>

[示例请求]

[示例响应]

关于奖期查询交易的说明请参考后续章节。

3.4消息体

在投注代理商和恒朋无纸化彩票系统之间有多个不同的业务交互，每个交互需要发送具体的业务请求，恒朋无纸化彩票系统根据或者投注代理商根据不同的业务请求来执行相应的业务处理。每一个业务处理都是一个请求/响应的过程，即每个业务请求都会有一个相应的业务响应。

3.4.1奖期通知

当恒朋无纸化彩票系统的奖期状态转换的时候，比如开启一个新奖期，截止一个奖期等，恒朋无纸化彩票系统会向相应的投注代理商系统发送奖期通知，通知投注代理商关于奖期状态的变化。同时投注代理商也可以不依赖于恒朋无纸化彩票系统的奖期通知机制，可以通过奖期查询的服务来获得奖期的状态转换。当然投注代理商也可以完全不依赖于恒朋无纸化彩票系统的奖期管理，而由自己来管理奖期。

1）恒朋无纸化彩票系统向投注代理商发出奖期通知的请求消息，消息体格式如下：

<body>

<issue gameName="ssc" number="2007051023"

status="1" />

<issue gameName="ssc" number="2007051024"

status="1" />

</issueNotify>

</body>

在消息体元素body中定义了issueNotify子元素来声明奖期通知，其中：

* issueNotify元素：容器元素，定义了奖期通知数据结构。

issue元素：奖期元素，描述了奖期信息。

名称

数据类型

必需

长度

描述

gameName

string

玩法的编号，具体的玩法编号定义可以参照附录B。

[请求消息体]

长度

描述

code

string

响应方处理请求的响应状态码，具体定义可以参照附录B。

message

注：响应消息都包含response子元素，这个元素在所有交易响应信息中结构是一样的，所以后面将不再对这个元素做重复说明。

[响应消息体]

其中，issueQuery元素定义了奖期查询请求数据结构，issue子元素描述了要查询的奖期。如果不指定issue元素的number属性，那么默认返回玩法当前奖期的信息,并且响应信息中会携带当前奖期编号，更多关于issue元素描述可以参照随后奖期查询响应部分中关于issue的描述。

2) 恒朋无纸化彩票系统向投注代理商返回响应信息，消息体格式如下：

<body>

<issue gameName="ssc"

number="2007051002"

startTime="20070328080000"

stopTime="20070328180000"

status="5"

bonusCode="1,2,3,4,5"/>

</response>

</body>

在响应消息中，issue元素描述了详细的奖期信息。

* issue元素

名称

数据类型

必需

长度

描述

gameName

string

玩法的编号，具体的玩法编号定义可以参照附录B。

number

string

奖期开启时间，格式与消息头中的timestamp子元素一样，为yyyyMMddHHmmss，示例： 20070510080000表示2007年5月10日上午8：00

奖期截止时间，格式同startTime

玩法的状态，可选值可以参照'奖期通知'部分对于'event'子元素的code 属性的描述。

奖期的开奖号码。

[响应消息体]

恒朋无纸化彩票系统状态

暂停奖期

完成期结

issue, startTime, stopTime, status

完成兑奖

issue, startTime, stopTime, bonusNumber, status

<body>

[异常响应消息体]

<body>

<userProfile cardType="1" mail="wangye@sun.com"

cardNumber="430525800815722"

mobile="13612736754"

realName="王绎之" bonusPhone=" (0755)65079323" />

</ticket>

<ticket id="3899122007051000000267"

playType="301" money="6.00" amount="1">

<userProfile cardType="3" mail="ramon@phoenix.com"

cardNumber="G03355390"

bonusPhone=" (023)76526753"

mobile="13098191231" realName="李侠"/>

</ticket>

</lotteryRequest>

</body>

彩票投注的基本单位是票，它对应了投注请求消息体中的一个ticket元素，每一票只能包含同样投注方式的投注号码，并且对投注号码的数量有限制，具体定义可以参照下表中playType属性的定义。

在投注的请求消息体中，lotteryRequest是一个容器元素，它可以有多个ticket子元素，这表示恒朋无纸化彩票系统可以处理投注代理商的批量投注请求,当前协议版本定义一个投注请求最多可以携带500票。

下面说明了消息体的数据结构：

[请求消息体]

ticket元素:投注的票

名称

数据类型

必需

长度

描述

string

票号，生成规则可以参照消息包的id 定义规则。

playType

integer

投注方式，当前支持以下投注方式定义：

方式编号

5组投注号码

103

cardType

方式编号

军官证

护照

长度

</body>

1）恒朋无纸化彩票系统向投注代理商发起投注结果通知交易请求，消息体格式如下

[响应消息体]

<ticket id="3899122007051000000231"

</ticketNotify>

</body>

其中，响应消息中的ticketNotify定义了投注结果通知消息体结构，ticket子元素和相应的投注交易请求中的ticket元素是对应的，即投注交易请求中每个ticket的投注处理结果都会在相应的投注结果通知中返回，其中：

ticket: 投注基本单位

名称

数据类型

必需

长度

描述

dealTime

string

恒朋无纸化彩票系统处理投注代理投注请求的时间，格式为yyyyMMddHHmmss 。

status

string

恒朋无纸化彩票系统处理某一票投注的状态，状态码可以参照附录B

message

string

如果恒朋无纸化彩票系统处理票投注失败，可以说明失败原因。

2）投注代理商返回相应信息到恒朋无纸化彩票系统，消息体格式如下：

<body>

</body>

[请求消息体]

[响应消息体]

</ticketQuery>

2）恒朋无纸化彩票系统处理了投注代理商的票查询请求，返回响应信息。消息体格式如

[请求消息体]

[响应消息体]

<body>

<ticket id="3899122007051000000231"

dealTime="20070510165423" money="8.00"

playType="301" amount="2"

status="0000" message=" "/>

<userProfile cardType="1" mail="wang@sun.com"

cardNumber="430525800815722" mobile="13612736754"

realName="王绎之" bonusPhone="(0755)65079323"/>

</ticket>

<ticket id="3899122007051000000232"

dealTime="20070510165423" money="6.00"

playType="301" amount="1"

status="0000" message=""/>

<userProfile cardType="3"

mail="ramon@phoenix.com"

cardNumber="G03355390"

bonusPhone="(023)76526753"

mobile="13098191231" realName="李侠"/>

</ticket>

</ticketQueryResult>

</response>

</body>

ticketQueryResult元素定义了票查询结果的数据结构，其中的ticket子元素与投注请求中的票数据结构是相似的，这里不重复列出它们，请参照‘投注’部分。

3.4.6返奖查询

投注代理商向恒朋无纸化彩票系统发起返奖的请求，恒朋无纸化彩票系统处理请求，然后返回返奖数据到投注代理商。

1）投注代理商向恒朋无纸化彩票系统发起返奖请求，消息体格式如下：

[请求消息体]

<body>

</bonusQuery>

</body>

bonusQuery元素定义了返奖请求的数据结构，issue元素描述了要查询的奖期的信息，关于issue的描述可以参照”奖期查询”部分。

2）恒朋无纸化彩票系统接收到投注代理商的请求，处理请求之后，返回返奖数据。消息体格式如下：

[响应消息体]

<body>

<bonusQueryResult bonusNumber="1,2,3,4,5"

totalItems="3" totalMoney="1100.00">

<bonusItem playType="301" money="0.00" isBombBonus="true"

bonusLevel="1" ticketID="3899122007051045451212"/>

<bonusItem playType="301" money="1000.00" isBombBonus="false"

bonusLevel="2" ticketID="3899122007051045451212"/>

<bonusItem playType="301" money="100.00" isBombBonus=" false "

bonusLevel="3" ticketID="3899122007051098127477"/>

</bonusQueryResult>

</response>

</body>

在响应信息的消息体中，bonusQueryResult定义了返回信息的数据结构，其中：

bonusQueryResult元素

名称

数据类型

必需

长度

描述

bonusNumber

string

开奖号码。

totalItems

integer

中奖记录总数。

totalMoney

double

中奖金额总数。

* issue :描述了奖期信息，可以参照‘奖期查询’中关于issue的定义。

* bonusItem元素: 返奖明细

名称

数据类型

必需

长度

描述

playType

isBombBonus

money

bonusLevel

ticketID

string

3.4.7销量查询

[请求消息体]

[响应消息体]

</balanceQueryResult>

balanceQueryResult元素定义了销量查询结果的数据结构，其中：

名称

数据类型

必需

长度

描述

salesMoney

double

该奖期的销售金额。只有奖期截止之后才能查询到销售金额。

bonusMoney

double

该奖期的返奖金额。只有返奖之后才能查询到返奖金额。返奖之前查到的返奖金额为-1

* issue :描述了奖期信息，可以参照‘奖期查询’中关于issue的定义。

如果恒朋无纸化彩票系统处理销量查询请求出现异常，那么返回信息的消息体格式如下：

<body>

</body>

其中response的code属性定义了响应状态码，可以参照附录B。

[响应消息体]

4总述

在这份通信协议中，主要描述了投注代理商与恒朋无纸化彩票系统之间的通信数据结构，概述部分简要的介绍了投注代理商与恒朋无纸化彩票系统之间的交互过程，如果要了解更多，可以参考《恒朋无纸化彩票系统数据接入技术方案》。

附录A 玩法参数说明

玩法名称

区域

全国

20选5

重庆

205

附录B 响应状态码说明

0000

0010

消息格式错误。

0011

不支持的协议版本，比如设定了message的version属性为0.1。

0012

messageID格式错误。

0014

timestamp时间戳格式错误。

0015

消息摘要不匹配。

0016

不支持该交易类型。

0017

MessageId重复。

0098

单个请求超出最大并发数。

1011

1012

1013

奖期未完成期结。

2001

用户手机号码错误。

2012

2013

2014

2015

禁止组选投注。

2045

2046

2047

重复发送的投注票（该投注票已经发送到恒朋无纸化彩票系统了）。

不存在该票号。

投注失败。

投注中。

3001

3002

3003

9999

投注方式

时时彩

号码之间用逗号分隔，示例：1,2,3,4,5

说明

{5个号码}

前2个号码用下划线”_”表示，号码之间用逗号分隔

前3个号码用下划线”_”表示，号码之间用逗号分隔

{5个号码}

复选投注只有五星、三星和二星复选

格式

五星复选

号码之间用逗号分隔。

三星和值

{5个号码}

投注方式

格式同直选投注。

单式投注

投注方式

说明

奖等定义

二等奖

选中6个红色球号码

Ｎ

二等奖

选中3个基本号

posted @ 2015-08-11 00:00 attilaxAti 阅读(455) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

attilaxAti

atitit.恒朋无纸化彩票系统数据接入通信协议

公告