中兴彩铃系统与第3方Web Service接口规范个人彩铃部分文档格式.docx

中兴彩铃系统与第3方Web Service接口规范个人彩铃部分文档格式.docx

《中兴彩铃系统与第3方Web Service接口规范个人彩铃部分文档格式.docx》由会员分享，可在线阅读，更多相关《中兴彩铃系统与第3方Web Service接口规范个人彩铃部分文档格式.docx（122页珍藏版）》请在冰豆网上搜索。

2007.07.04

1）信息文件中的各字段之间以“|”分割，并且时间格式修改为“yyyy.mm.ddhh:

ss”

2007.07.09

V1.03

2007.07.10

1增加3.3.19获取铃音试听地址接口GetToneListenAddr

2增加3.6节其它管理接口-短信通知接口SmsNotify

2007.07.11

1修改3.6.1短信通知接口SmsNotify增加CallNumber字段

2007.07.13

1修改GetToneListenAddr接口，ToneType=3个人铃音

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

安全验证参数，“序列号+密码原文”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

彩铃平台后台

彩铃平台后台编号

彩铃平后台发起

终端用户

彩铃用户号码

用户网站Portal发起

CP

CP登录帐号

CP管理网站Portal发起

Administrator

系统管理员登录帐号

系统管理网站Portal发起

集团管理员

集团管理员登录帐号

集团管理网站Portal发起

005

客服管理员

客服人员登录帐号

注：

每一个RoleCode彩铃系统都将分配一定的操作权限，每种业务操作都对应了一定的权限，只有分配了相应权限的RoleCode，在调用某个操作接口时，彩铃平台才会接收其请求，进行相应的业务处理，否则彩铃系统将返回请求方下面的错误信息。

312004

用户帐号无对应操作权限

3．1．5操作输出参数说明

是否可以为空

Response

returnCode

String（6）

返回结果码

description

String（0~50）

返回结果描述

3．1．6铃音信息类说明

ToneInfo

ToneID

String（20）

铃音编码

ToneName

铃音名称

ToneNameLetter

String

（1）

铃音名称首字母

SingerName

歌手名称

SingerNameLetter

歌手名称首字母

CpID

铃音相关CP/SP编码

Price

铃音价格，单位为分

UpdateTime

铃音更新时间

UseTimes

铃音购买总次数

ToneValidDay

铃音有效截止日期，格式为YYYYMMDD

Info

铃音描述信息

TonePreListenAddress

针对WEB文件服务器的网站铃音试听URL地址，用于播放试听铃音内容

Status

铃音状态（默认为1）：

1：

正常可用2：

隐藏

ToneType

铃声类型：

1系统音

3个人上传或自录音

8集团音

Offset

偏移量（该铃音在铃音组中的位置）

Para1

备用扩充字段1

Para2

备用扩充字段2

ToneIndex

Integer

铃声索引，新增时不用填，彩铃系统自动生成

ToneClassID

铃声所属的铃音分类的编号。

ToneLong

铃音的时长

GiftTimes

铃音赠送总次数

ToneSize

铃音的大小

3．1．7个人铃音组说明

UserToneGrp

UserToneGrpID

铃音组编码

ToneGrpName

String（40）

铃音组名称

3．1．8个人铃音设置说明

UserToneSettingInfo

SettingID

String（10）

铃音设置id号

SettingObjType

设置对象类型：

1无指定主叫/主叫组铃音

2指定主叫铃音

3指定主叫组铃音

Calling

·

SettingObjType=1，该字段为空，无意义

SettingObjType=2，该字段为主叫号码，移动号码为MSISDN格式，固定号码区号+本地固定号码，号码格式的定义参见3.1.13节说明

SettingObjType=3，该字段为主叫号码组的编号

timeType

0-默认；

1-周时间段

2-月时间段

3-日时间段

4-带起始日期的时间段

5-年时间段

StartTime

铃音播放起始时间段，格式：

timetype为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）

铃音播放结束时间段，格式：

DDHHMiSS，MM表示月份，MM=01表示1号，MM=31表示31号，以此类推，HHMiSS表示时分秒

YYYYMMDDHHMiSS，YYYYMMDD表示结束日期，HHMiSS表示时分秒

MMDDHHMiSS，MMDD表示每年结束月、日，HHMiSS表示时分秒

铃音类型

0-铃音

1-铃音组

2-铃音盒

ToneType=0，铃音编码

ToneType=1，铃音组编码

timedescrip

String（1-40）

时间段描述

3．1．9用户主叫用户组说明

UserCallingGrp

CallingGrpID

用户组编码

CallingName

用户组名称

3．1．10铃音基本信息说明

ToneBasicInfo

3．1．11彩铃用户通用业务信息说明

GenUserInfo

Callnumber

Passwd

String（8）

彩铃用户密码，DES进行加密，加密方式参见附录B

LockID

用户状态

0激活

3强制去激活

CreateDate

String（19）

开户日期，格式为YYYY.MM.DD

IsPre

是否为预付费用户：

0：

是

默认值为0

PhoneType

用户号码类型

0GSM

1CDMA

2PSTN

3PHS

IfRingCopy

String

铃音是否允许复制

0允许

1不允许

SubService

开通的子业务，每位表示1种子业务，0表示未开通，1表示开通，从低位开始（低位到高位的顺序为从左到右）进行排列：

第1位表示被叫彩铃

第2位表示主叫彩铃

第3位表示集团彩铃

第4位表示彩铃Plus

其它位待定

如：

00000000000000000101，表示用户开通了集团彩铃业务和被叫彩铃业务

3．1．12主被叫彩铃用户信息说明

CallUserInfo

ServType

业务类型

1被叫彩铃业务

2主叫彩铃业务

1去激活

UserType

主/被叫彩铃用户类型

首次开户日期，格式为YYYY.MM.DD

UseDate

最近一次开户日期，格式为YYYY.MM.DD

EndGiftDate

赠送业务到期日期，格式为YYYY.MM.DD

AllowCloseDate

允许销户的日期，格式为YYYY.MM.DD

OpenMode

String

（2）

开户方式

1Web

2IVR

3SP

4BOSS

5WAP

6人工台

7SMS

8IVR（196）

9按键复制

11管理员

12热线复制

OpenSource

开户来源

SerAreaNo

String（4）

用户所属业务区

RingPlayMode

铃音播放方式

1固定

2随机

3日随机

RingGrpPlayMode

铃音组播放方式

1固定

2随机

GroupFlag

集团标识

0否

1是

3．1．13集团彩铃用户信息说明