中兴彩铃系统与第3方Web Service接口规范个人彩铃部分.docx
《中兴彩铃系统与第3方Web Service接口规范个人彩铃部分.docx》由会员分享，可在线阅读，更多相关《中兴彩铃系统与第3方Web Service接口规范个人彩铃部分.docx（122页珍藏版）》请在冰豆网上搜索。
中兴彩铃系统与第3方WebService接口规范个人彩铃部分
中兴彩铃系统与第3方
WebService接口规范（个人彩铃部分）
（V1.03）
中兴通讯股份有限公司
2006年7月
修改记录
版本号
拟制人/
修改人
拟制/修改日期
更改理由
主要更改内容
（写要点即可）
V1.01
邓冰
2006.07.18
拟制接口规范
V1.01
邓冰
2006.08.17
修改接口规范
1对用户Password等字段增加加解密处理
2对RoleCode增加各项操作权限控制处理
V1.01
邓冰
2007.05.28
修改接口规范3.1.11节GenUserInfo类定义
1修改GenUserInfo类定义中的PhoneType字段定义，PhoneType字段扩展为
0GSM1CDMA2PSTN3PHS
V1.02
邓冰
2007.06.07
修改接口规范，以实现铃音信息变更同步功能
1．增加3.3.18获取铃音变更信息请求QryChangeTones
V1.02
邓冰
2007.06.12
修改接口规范，实现铃音信息全同步
1．修改3.3.18，接口由获取铃音变更信息，修改为获取全部铃音信息请求QryAllTonesInfo
V1.02
邓冰
2007.06.13
修改接口规范
1修改3.1.16/3.1.17
2修改3.1.11
3修改3.4.6.1
4修改3.1.12/3.1.13
5附录BDES加密，增加C#和VB加密
V1.02
邓冰
2007.07.03
修改接口规范
修改3.3.18节查询全部铃音操作中《中兴彩铃系统WebService接口铃音数据同步文件格式》附件
1）信息文件描述文件名为：
crbt.info.txt；
2）信息文件中的“最新一次修改时间”字段格式修改为：
yyyy.mm.dd:
hh:
mi:
ss
V1.02
邓冰
2007.07.04
修改接口规范
修改3.3.18节查询全部铃音操作中《中兴彩铃系统WebService接口铃音数据同步文件格式》附件
1）信息文件中的各字段之间以“|”分割，并且时间格式修改为“yyyy.mm.ddhh:
mi:
ss”
V1.02
邓冰
2007.07.09
修改接口规范
修改3.3.18节查询全部铃音操作中《中兴彩铃系统WebService接口铃音数据同步文件格式》附件
V1.03
邓冰
2007.07.10
修改接口规范
1增加3.3.19获取铃音试听地址接口GetToneListenAddr
2增加3.6节其它管理接口-短信通知接口SmsNotify
V1.03
邓冰
2007.07.11
修改接口规范
1修改3.6.1短信通知接口SmsNotify增加CallNumber字段
V1.03
邓冰
2007.07.13
修改接口规范
1修改GetToneListenAddr接口，ToneType=3个人铃音
V1.03
邓冰
2007.07.23
修改接口规范
1修改3.3.9UploadSysTone接口，增加CallNumber和ToneType2个字段，以支持上传个人DIY铃音
目录
1、总则1
1．1适用范围1
1．2相关术语与缩略语解释1
2、接口设计原则1
2．1接口约束1
2．2接口概述2
2．3接口协议2
3、与第3方系统个人彩铃业务接口2
3．1通用参数描述2
3．1．1通用输入参数说明2
3．1．2设备代码说明3
3．1．3访问序列号说明3
3．1．4操作者类型与代码说明3
3．1．5操作输出参数说明4
3．1．6铃音信息类说明4
3．1．7个人铃音组说明5
3．1．8个人铃音设置说明5
3．1．9用户主叫用户组说明6
3．1．10铃音基本信息说明7
3．1．11彩铃用户通用业务信息说明7
3．1．12主被叫彩铃用户信息说明8
3．1．13集团彩铃用户信息说明9
3．1．14电话号码格式说明9
3．1．15铃音类型信息10
3．1．16音乐盒/大礼包信息10
3．1．17音乐盒/大礼包组成员信息10
3．1．18铃音ID-ToneID数据定义10
3．1．19用户类型数据定义11
3．1．20用户基本信息定义11
3．2个人彩铃用户管理接口12
3．2．1方法列表12
3．2．2用户开通彩铃（Subscribe）13
3．2．3用户注销彩铃业务消息（UnSubscribe）14
3．2．4用户鉴权（UserValidate）15
3．2．5修改密码（EditPwd）16
3．2．6获取密码（GetPwd）17
3．2．7查询用户通用业务信息（QryUserServInfo）17
3．2．8查询用户主被叫彩铃业务信息（QryUserCallInfo）18
3．2．9查询用户集团彩铃业务信息（QryUserCorpInfo）19
3．2．10查询用户类型信息（QryUserTypeInfo）20
3．2．11激活去激活用户（ActDeactUser）21
3．2．12查询用户基本信息（QryUserBasInfo）22
3．2．13编辑用户基本信息（EditUserBasInfo）23
3．3系统铃音管理接口23
3．3．1方法列表23
3．3．2查询系统铃音类型（QryToneType）25
3．3．3根据铃音ID查询铃音信息（QryToneByID）25
3．3．4根据铃音名称查询铃音信息（QryToneByName）26
3．3．5根据歌手名称查询铃音信息（QryToneBySName）27
3．3．6根据铃音类型查询铃音信息（QryToneByType）28
3．3．7查询多条铃音（QryMultiTones）29
3．3．8查询铃音排行榜和推荐榜（QryToneTop）30
3．3．9上传系统铃音（UploadSysTone）31
3．3．10根据名称查询铃音盒/大礼包（QryBoxByName）33
3．3．11根据编号查询铃音盒/大礼包（QryBoxByID）33
3．3．12查询多个音乐盒/大礼包（QryMultiBoxes）34
3．3．13查询音乐盒/大礼包成员（QryBoxMem）35
3．3．14查询音乐盒/大礼包排行榜和推荐榜（QryBoxTop）36
3．3．15创建和修改音乐盒/大礼包（CreateUpBox）37
3．3．16删除音乐盒/大礼包（DelBox）38
3．3．17增加/删除音乐盒/大礼包成员（AddDelBoxMem）39
3．3．18查询所有铃音信息请求（QryAllTones）40
3．3．19获取铃音试听地址请求（GetToneListenAddr）41
3．4个用户铃音管理接口42
3．4．1方法列表42
3．4．2查询个人铃音库（QryUserTone）43
3．4．3查询个人收藏夹（QryUserFav）44
3．4．4查询个人定购的音乐盒（QryUserBox）45
3．4．5定购铃音（BuyTone）46
3．4．6赠送铃音（GiftTone）47
3．4．7删除个人铃音库铃音（DelTone）48
3．4．8查询个人铃音组（QryToneGrp）49
3．4．9查询个人铃音组中铃音（QryToneGrpMem）50
3．4．10管理个人铃音组（ManToneGrp）51
3．4．11管理个人铃音组中铃音（ManToneGrpMem）53
3．4．12查询个人铃音设置（QryToneSet）54
3．4．13设置个人铃音（SetTone）55
3．4．14删除个人铃音设置（DelToneSet）56
3．4．15修改个人铃音播放方式（UpTonePlay）57
3．5个人用户组管理接口58
3．5．1方法列表58
3．5．2查询用户主叫组（QryCallingGrp）59
3．5．3管理用户用户主叫组（ManCallingGrp）60
3．5．4查询用户主叫组成员（QryCallingGrpMem）61
3．5．5编辑用户主叫组成员（EditCallingGrpMem）62
3．6其它管理接口63
3．6．1方法列表63
3．6．2短信通知（SmsNotify）63
4、附录A：
返回结果码定义64
5、附录B：
DES加解密方法65
前言
为通过第3方的平台可以在中兴彩铃平台上完成彩铃业务的操作，本接口规范规定了第3方系统与中兴彩铃系统之间所应遵从的WebService接口规范。
本规范由中兴通讯股份有限公司提出并负责解释。
1、总则
1．1适用范围
本接口规范适用与第3方厂家依照该规范开发出和中兴彩铃系统之间的业务接口，实现第3方开发业务受理平台，进行彩铃业务的个人彩铃用户管理、集团彩铃用户管理、铃音上传等功能，以便于彩铃业务的核心处理部分和业务受理部分分离，便于业务能更快、更好适应市场变化和用户的需求。
本接口规范只涉及个人彩铃部分的接口，其它彩铃业务，如集团彩铃等部分的接口，请参考另外的相关文档。
1．2相关术语与缩略语解释
名称
定义
CRBT
彩铃系统
SOAP
简单对象访问协议
HTTP
超文本传输协议
FTP
文件传输协议
XML
扩展标记语言
WSDL
WebService描述语言
2、接口设计原则
2．1接口约束
⏹数字：
对于定长字段，右对齐、左补0；
⏹字符：
对于定长字段，左对齐、右补空格；
⏹XML文件中字符串编码为UTF-8；
⏹FTP传输ASCII文件时，字符串编码为GB-2312；
⏹文件头中“总记录数”不含文件头记录；
⏹声明可以为空的记录字段不可填空；
2．2接口概述
第3方系统调用中兴彩铃系统提供的彩铃业务受理WebService接口，为彩铃用户（个人、集团等）提供彩铃业务功能，如彩铃开户/销户、铃音定购、个人设置等功能。
通过WebService技术，为第3方提供一套完整的彩铃业务接口，帮助第3方开发出彩铃受理平台。
中兴彩铃系统和第3方系统之间的接口逻辑示意图如下：
2．3接口协议
SOAP/HTTP
3、与第3方系统个人彩铃业务接口
3．1通用参数描述
3．1．1通用输入参数说明
通用输入参数类，包括安全验证参数（DID，SEQ，DIDPWD）、操作者类型与代码以及接口版本信息。
类名
成员名
可空否
类型
说明
InaccessInfo
DID
否
String（7）
安全验证参数，详见3.1.2设备代码说明
SEQ
否
String（32）
安全验证参数，详见3.1.3访问序列号说明
DIDPWD
否
String（32）
安全验证参数，“序列号+密码原文”MD5后结果。
role
否
String（3）
操作者类型
roleCode
否
String（1-20）
操作者代码
version
是
String（1-10）
接口版本号，如V1.00
3．1．2设备代码说明
设备代码（DID）包括两类：
1）第3方设备代码
第3方设备代码：
设备代码由第3方的设备类型以及四位序列号组成，共7位。
例如WWW类第3方设备，为0010000，0010001……。
表一、第3方设备类型编号表
编号
设备类型
说明
001
WWW
包括用户网站，管理员网站等
002
WAP
003
IVR
暂不设置独立IVR
004
SMS
2）彩铃后台设备代码
彩铃后台设备代码：
唯一标识一个彩铃后台，由标识“10”和彩铃平台所在省省代码以及2位序列号组成，共7位。
如多个彩铃后台的编码为1028000、1028001、1028002……。
3．1．3访问序列号说明
序列号分成三部分，第一部分长为7位，表示第3方设备代码（参见3.1.2第3方设备代码说明），第二部分长为14位，表示命令产生的日期和时间（系统中的任何命令的保存时间都不应该超过一年），格式为十进制的yyyymmddhhmmss，比如2004年11月20日20时32分25秒产生的命令，其第二部分为十进制20041120203225；第三部分长为8位，由0开始，循环进位，直到进位满了之后再清零，重新开始计数。
序列号用来唯一标示一个消息。
3．1．4操作者类型与代码说明
编号
操作者类型role
操作者代码roleCode
说明
000
彩铃平台后台
彩铃平台后台编号
彩铃平后台发起
001
终端用户
彩铃用户号码
用户网站Portal发起
002
CP
CP登录帐号
CP管理网站Portal发起
003
Administrator
系统管理员登录帐号
系统管理网站Portal发起
004
集团管理员
集团管理员登录帐号
集团管理网站Portal发起
005
客服管理员
客服人员登录帐号
系统管理网站Portal发起
注：
每一个RoleCode彩铃系统都将分配一定的操作权限，每种业务操作都对应了一定的权限，只有分配了相应权限的RoleCode，在调用某个操作接口时，彩铃平台才会接收其请求，进行相应的业务处理，否则彩铃系统将返回请求方下面的错误信息。
312004
用户帐号无对应操作权限
3．1．5操作输出参数说明
类名
成员名
是否可以为空
类型
说明
Response
returnCode
否
String（6）
返回结果码
description
是
String（0~50）
返回结果描述
3．1．6铃音信息类说明
类名
成员名
可空否
类型
说明
ToneInfo
ToneID
否
String（20）
铃音编码
ToneName
是
String（1-20）
铃音名称
ToneNameLetter
是
String
（1）
铃音名称首字母
SingerName
是
String（1-20）
歌手名称
SingerNameLetter
是
String
（1）
歌手名称首字母
CpID
是
String（1-20）
铃音相关CP/SP编码
Price
是
String（1-20）
铃音价格，单位为分
UpdateTime
是
String（1-20）
铃音更新时间
UseTimes
是
String（1-20）
铃音购买总次数
ToneValidDay
是
String（1-20）
铃音有效截止日期，格式为YYYYMMDD
Info
是
String（1-20）
铃音描述信息
TonePreListenAddress
是
String（1-20）
针对WEB文件服务器的网站铃音试听URL地址，用于播放试听铃音内容
Status
是
String（1-20）
铃音状态（默认为1）：
1：
正常可用2：
隐藏
ToneType
是
String
（1）
铃声类型：
1系统音
3个人上传或自录音
8集团音
Offset
是
String（1-20）
偏移量（该铃音在铃音组中的位置）
Para1
是
String（1-20）
备用扩充字段1
Para2
是
String（1-20）
备用扩充字段2
ToneIndex
是
Integer
铃声索引，新增时不用填，彩铃系统自动生成
ToneClassID
是
Integer
铃声所属的铃音分类的编号。
ToneLong
是
Integer
铃音的时长
GiftTimes
是
String（1-20）
铃音赠送总次数
ToneSize
是
String（1-20）
铃音的大小
3．1．7个人铃音组说明
类名
成员名
可空否
类型
说明
UserToneGrp
UserToneGrpID
否
String（20）
铃音组编码
ToneGrpName
是
String（40）
铃音组名称
3．1．8个人铃音设置说明
类名
成员名
可空否
类型
说明
UserToneSettingInfo
SettingID
是
String（10）
铃音设置id号
SettingObjType
否
String
（1）
设置对象类型：
1无指定主叫/主叫组铃音
2指定主叫铃音
3指定主叫组铃音
Calling
是
String（1-20）
·SettingObjType=1，该字段为空，无意义
·SettingObjType=2，该字段为主叫号码，移动号码为MSISDN格式，固定号码区号+本地固定号码，号码格式的定义参见3.1.13节说明
·SettingObjType=3，该字段为主叫号码组的编号
timeType
否
String
（1）
0-默认；
1-周时间段
2-月时间段
3-日时间段
4-带起始日期的时间段
5-年时间段
StartTime
否
String（1-20）
铃音播放起始时间段，格式：
·timetype为0：
0
·timetype为1：
NHHMiSS，N表示星期几，N=1表示星期1，N=7表示星期日，以此类推，HHMiSS表示时分秒
·timetype为2：
MMHHMiSS，MM表示月份，MM=01表示1月份，MM=12表示12月份，以此类推，HHMiSS表示时分秒
·timetype为3：
HHMiSS，时分秒
·timetype为4：
YYYYMMDDHHMiSS，YYYYMMDD表示起始日期，HHMiSS表示时分秒
·timetype为5：
MMDDHHMiSS，MMDD表示每年起始月、日，HHMiSS表示时分秒
EndTime
否
String（1~20）
铃音播放结束时间段，格式：
·timetype为0：
0
·timetype为1：
NHHMiSS，N表示星期几，N=1表示星期1，N=7表示星期日，以此类推，HHMiSS表示时分秒
·timetype为2：
DDHHMiSS，MM表示月份，MM=01表示1号，MM=31表示31号，以此类推，HHMiSS表示时分秒
·timetype为3：
HHMiSS，时分秒
·timetype为4：
YYYYMMDDHHMiSS，YYYYMMDD表示结束日期，HHMiSS表示时分秒
·timetype为5：
MMDDHHMiSS，MMDD表示每年结束月、日，HHMiSS表示时分秒
ToneType
否
String
（1）
铃音类型
0-铃音
1-铃音组
2-铃音盒
ToneID
否
String（20）
ToneType=0，铃音编码
ToneType=1，铃音组编码
timedescrip
是
String（1-40）
时间段描述
3．1．9用户主叫用户组说明
类名
成员名
可空否
类型
说明
UserCallingGrp
CallingGrpID
否
String（20）
用户组编码
CallingName
是
String（40）
用户组名称
3．1．10铃音基本信息说明
类名
成员名
可空否
类型
说明
ToneBasicInfo
ToneID
否
String（20）
铃音编码
ToneName
否
String（20）
铃音名称
3．1．11彩铃用户通用业务信息说明
类名
成员名
可空否
类型
说明
GenUserInfo
Callnumber
否
String（20）
彩铃用户号码
Passwd
否
String（8）
彩铃用户密码，DES进行加密，加密方式参见附录B
LockID
否
String（3）
用户状态
0激活
3强制去激活
CreateDate
否
String（19）
开户日期，格式为YYYY.MM.DD
IsPre
否
String
（1）
是否为预付费用户：
0：
否
1：
是
默认值为0
PhoneType
否
String
（1）
用户号码类型
0GSM
1CDMA
2PSTN
3PHS
IfRingCopy
否
String
铃音是否允许复制
0允许
1不允许
SubService
否
String（20）
开通的子业务，每位表示1种子业务，0表示未开通，1表示开通，从低位开始（低位到高位的顺序为从左到右）进行排列：
第1位表示被叫彩铃
第2位表示主叫彩铃
第3位表示集团彩铃
第4位表示彩铃Plus
其它位待定
如：
00000000000000000101，表示用户开通了集团彩铃业务和被叫彩铃业务
3．1．12主被叫彩铃用户信息说明
类名
成员名
可空否
类型
说明
CallUserInfo
Callnumber
否
String（20）
彩铃用户号码
ServType
否
String
（1）
业务类型
1被叫彩铃业务
2主叫彩铃业务
LockID
否
String（3）
用户状态
0激活
1去激活
IsPre
否
String
（1）
是否为预付费用户：
0：
否
1：
是
默认值为0
UserType
否
String（3）
主/被叫彩铃用户类型
CreateDate
否
String（19）
首次开户日期，格式为YYYY.MM.DD
UseDate
否
String（19）
最近一次开户日期，格式为YYYY.MM.DD
EndGiftDate
否
String（19）
赠送业务到期日期，格式为YYYY.MM.DD
AllowCloseDate
否
String（19）
允许销户的日期，格式为YYYY.MM.DD
OpenMode
否
String
（2）
开户方式
1Web
2IVR
3SP
4BOSS
5WAP
6人工台
7SMS
8IVR（196）
9按键复制
11管理员
12热线复制
OpenSource
是
String（20）
开户来源
SerAreaNo
是
String（4）
用户所属业务区
RingPlayMode
是
String
（1）
铃音播放方式
1固定
2随机
3日随机
RingGrpPlayMode
是
String
（1）
铃音组播放方式
1固定
2随机
GroupFlag
是
String
（1）
集团标识
0否
1是
3．1．13集团彩铃用户信息说明
类名
成员名
升级会员 