禹星科技短信平台接口定义规范20.docx
《禹星科技短信平台接口定义规范20.docx》由会员分享，可在线阅读，更多相关《禹星科技短信平台接口定义规范20.docx（14页珍藏版）》请在冰豆网上搜索。
禹星科技短信平台接口定义规范20
禹星科技短信平台接口定义规范
文件编号：
YXKJ-D003
版本号：
V2.0
武汉禹星科技有限公司
2012年8月8日
目录
1概述4
1.1协议说明4
1.2适用范围4
1.3参考资料4
1.4术语4
2CP与SP的通信5
2.1通用HTTP方式5
2.1.1从CP到SP的命令5
2.2通用Webservice方式6
2.2.1从CP到SP的命令6
3消息定义6
3.1基于通用HTTP的消息定义6
3.1.1submit7
3.1.2balance9
3.2基于通用Webservice的消息定义10
3.2.1submit11
3.2.2balance13
4接口常见问题15
5修订历史16
附录117
前言
本规范为武汉禹星科技有限公司企业规范，现阶段版本是2.0版。
本规范描述了武汉禹星科技短信业务中消息的类型和定义。
根据业务的发展，规范中的指令操作和参数将会做进一步的调整和增加。
本规范解释权属于武汉禹星科技有限公司。
本规范起草单位：
武汉禹星科技有限公司开发部。
本规范主要起草人：
袁建斌。
1概述
1.1协议说明
本协议是CP和SP之间的接口协议。
1.2适用范围
本协议适用于各CP厂商。
1.3参考资料
1.4术语
本协议用到以下术语：
CP
内容提供商
SP
服务提供商（本文SP均指禹星科技）
MO
由手机用户提交的短消息
MT
由手机用户接收的短消息
SMG
ShortMessageGateway，短消息网关
SMSC
ShortMessageServiceCenter，短消息中心
2CP与SP的通信
CP和SP支持两种类型的通信承载方式：
通用HTTP承载方式和通用WebService承载方式。
2.1通用HTTP方式
CP和SP之间采用通用HTTP方式通信时，CP为HTTP的客户端，SP为服务器端。
HTTP的特点决定客户端和服务器端的每一次通信都必须一次完成连接、发送请求、接收应答、关闭连接等过程（HTTP承载方式不再需要专门的连接命令）。
如果HTTP服务器接收到的HTTP请求内容的格式不完整或不正确，HTTP服务器应该返回错误码。
HTTP承载方式支持的HTTP协议为1.0版。
HTTP承载方式使用如下命令：
2.1.1从CP到SP的命令
消息
描述
submit
CP用该消息向SP请求发送短消息
balance
CP用该消息向SP请求查询余额
2.2通用Webservice方式
CP和SP之间采用通用Webservice方式通信时，CP为Webservice的客户端，SP为Webservice服务器端。
如果Webservice服务器接收到的Webservice请求内容的格式不完整或不正确，Webservice服务器应该返回错误码。
Webservice承载方式使用如下命令：
2.2.1从CP到SP的命令
消息
描述
submit
CP用该消息向SP请求发送短消息
balance
CP用该消息向SP请求查询余额
3消息定义
3.1基于通用HTTP的消息定义
HTTP客户端采用POST或GET方法向服务器端发送请求，服务器端返回应答。
HTTP请求和响应的格式如下：
3.1.1submit
submit请求：
请求地址：
:
8966/submit
参数名称
数据类型
含义
是否必填
备注
cpCode
String
CP用户名
是
cpPassword
String
CP密码
是
MD5加密后的32位字符串，请向SP客服索取。
也可通过客户平台修改密码，修改后请向SP客服索取新的32位字符串
userNumber
String
一个或多个接收该短消息的手机号
是
单次提交最多允许1000个，号码之间用英文逗号分隔
msgContent
String
短消息的内容
是
短信长度与cpcode所用通道有关，详询SP客服
srcXID
String
扩展号
否
SP分配，默认为空
reserve1
String
保留，扩展用
否
reserve2
String
保留，扩展用
否
charset
String
编码字符集
否
缺省值为GBK，目前支持GBK、utf-8、gb2312
submit应答
应答的文件格式是XML，编码是utf-8。
参数名称
数据类型
含义
是否必填
备注
result
String
应答结果
是
0：
接收成功
其它：
错误码*
spmid
String
SP内部信息标识
是
当result不为0时，该值为-1
description
String
应答描述
否
当result为0时，该值为空；当result不为0时，该值不为空
reserve1
String
保留，扩展用
否
reserve2
String
保留，扩展用
否
示例：
xmlversion="1.0"encoding="UTF-8"?
>
0
197466
3.1.2balance
balance请求：
请求地址：
:
8966/balance
参数名称
数据类型
含义
是否必填
备注
cpCode
String
CP用户名
是
cpPassword
String
CP密码
是
MD5加密后的32位字符串，请向客服索取。
可通过客户平台修改密码，修改后请向客服索取新的32位字符串
charset
String
编码字符集
否
缺省值为GBK,目前支持GBK、utf-8、gb2312
balance应答
应答的文件格式是XML，编码是utf-8。
参数名称
数据类型
含义
是否必填
备注
result
String
应答结果
是
0：
接收成功
其它：
错误码*
balance
String
余额
否
当result为0时，该信息为账户余额；当result不为0时，该信息为空
description
String
应答描述
否
reserve1
String
保留，扩展用
否
reserve2
String
保留，扩展用
否
示例：
xmlversion="1.0"encoding="UTF-8"?
>
0
10023
您的余额是10023
3.2基于通用Webservice的消息定义
Webservice客户端向服务器端发送请求，服务器端返回应答。
Webservice请求和响应的格式如下：
3.2.1submit
submit请求：
请求地址：
:
8966/services/WS2Handler?
wsdl
方法名称：
submit
partname="cpCode"type="xsd:
String"/>
partname="cpPassword"type="xsd:
String"/>
partname="userNumber"type="xsd:
String"/>
partname="msgContent"type="xsd:
String"/>
partname="srcXid"type="xsd:
String"/>
partname="reserve1"type="xsd:
String"/>
partname="reserve2"type="xsd:
String"/>
参数名称
数据类型
含义
是否必填
备注
cpCode
String
CP用户名
是
cpPassword
String
CP密码
是
MD5加密后的32位字符串，请向SP客服索取。
可通过客户平台修改密码，修改后请向SP客服索取新的32位字符串
userNumber
String
一个或多个接收该短消息的手机号
是
单次提交最多允许1000个，号码之间用英文逗号分隔
msgContent
String
短消息的内容
是
短信长度与cpcode所用通道有关，详询SP客服
srcXid
String
扩展号
否
SP分配，默认为空
reserve1
String
保留，扩展用
否
reserve2
String
保留，扩展用
否
submit应答
应答的文件格式是XML，编码是utf-8。
参数名称
数据类型
含义
是否必填
备注
result
String
应答结果
是
0：
接收成功
其它：
错误码*
spmid
String
SP内部信息标识
是
当result不为0时，该值为-1
description
String
应答描述
否
当result为0时，该值为空；当result不为0时，该值不为空
reserve1
String
保留，扩展用
否
reserve2
String
保留，扩展用
否
示例：
xmlversion="1.0"encoding="UTF-8"?
>
0
197466
3.2.2balance
balance请求：
请求地址：
:
8966/services/WS2Handler?
wsdl
方法名称：
balance
partname="cpCode"type="xsd:
String"/>
partname="cpPassword"type="xsd:
String"/>
参数名称
数据类型
含义
是否必填
备注
cpCode
String
CP用户名
是
cpPassword
String
CP密码
是
MD5加密后的32位字符串，请向客服索取。
可通过客户平台修改密码，修改后请向客服索取新的32位字符串
balance应答
应答的文件格式是XML，编码是utf-8。
参数名称
数据类型
含义
是否必填
备注
result
String
应答结果
是
0：
接收成功
其它：
错误码*
balance
String
余额
否
当result为0时，该信息为账户余额；当result不为0时，该信息为空
description
String
应答描述
否
reserve1
String
保留，扩展用
否
reserve2
String
保留，扩展用
否
示例：
xmlversion="1.0"encoding="UTF-8"?
>
0
10023
您的余额是10023
4接口常见问题
5修订历史
版本号
时间
修订人
主要内容或重大修改
V1.0
2012.02
袁建斌
V1.1
2012.04
袁建斌
增加了余额查询接口
v2.0
2012.08
袁建斌
1、修改了接口地址
2、修改了参数名称
3、增加了扩展参数
4、增加了账户密码安全控制
5、增加了使用示例
6、优化了底层通迅速度
注：
对该文件内容增加、删除或修改均需填写此历史，详细记载变更信息，以保证其可追溯性。
附录1
错误码
描述
0
无错误，提交成功
1
用户名、密码、手机号、短信内容其中一项为空
2
用户名或者密码错误
3
账户余额不足
4
手机号码格式错误
5
短信内容字数超过限制
6
提交内容包含非法字符
7
手机号码个数超过限制
8
网络故障导致信息提交失败
9
不支持的字符集
-1
提交失败
升级会员 