禹星科技短信平台接口定义规范20.docx

1、禹星科技短信平台接口定义规范20禹星科技短信平台接口定义规范文件编号：YXKJ-D003版本号：V 2.0 武汉禹星科技有限公司2012年8月8日目 录1 概述 41.1协议说明 41.2适用范围 41.3参考资料 41.4术语 42 CP与SP的通信 52.1 通用HTTP方式 52.1.1 从CP到SP的命令 52.2 通用Webservice方式 62.2.1 从CP到SP的命令 63 消息定义 63.1基于通用HTTP的消息定义 63.1.1 submit 73.1.2 balance 93.2基于通用Webservice的消息定义 103.2.1 submit 113.2.2 bal

2、ance 134 接口常见问题 155 修订历史 16附录1 17前 言 本规范为武汉禹星科技有限公司企业规范，现阶段版本是2.0版。本规范描述了武汉禹星科技短信业务中消息的类型和定义。根据业务的发展，规范中的指令操作和参数将会做进一步的调整和增加。本规范解释权属于武汉禹星科技有限公司。本规范起草单位：武汉禹星科技有限公司开发部。本规范主要起草人：袁建斌。1 概述1.1协议说明本协议是CP和SP之间的接口协议。1.2适用范围本协议适用于各CP厂商。1.3参考资料1.4术语本协议用到以下术语：CP内容提供商SP服务提供商(本文SP均指禹星科技)MO由手机用户提交的短消息MT由手机用户接收的短消息

3、SMGShort Message Gateway，短消息网关SMSCShort Message Service Center ，短消息中心2 CP与SP的通信CP和SP支持两种类型的通信承载方式：通用HTTP承载方式和通用WebService承载方式。 2.1 通用HTTP方式CP和SP之间采用通用HTTP方式通信时，CP为HTTP的客户端，SP为服务器端。HTTP的特点决定客户端和服务器端的每一次通信都必须一次完成连接、发送请求、接收应答、关闭连接等过程(HTTP承载方式不再需要专门的连接命令)。如果HTTP服务器接收到的HTTP请求内容的格式不完整或不正确， HTTP服务器应该返回错误码。

4、HTTP承载方式支持的HTTP协议为1.0版。HTTP承载方式使用如下命令：2.1.1 从CP到SP的命令消 息描 述submitCP用该消息向SP请求发送短消息balanceCP用该消息向SP请求查询余额2.2 通用Webservice方式CP和SP之间采用通用Webservice方式通信时，CP为Webservice的客户端，SP为Webservice服务器端。如果Webservice服务器接收到的Webservice请求内容的格式不完整或不正确， Webservice服务器应该返回错误码。Webservice承载方式使用如下命令：2.2.1 从CP到SP的命令消 息描 述submitCP

5、用该消息向SP请求发送短消息balanceCP用该消息向SP请求查询余额3 消息定义3.1基于通用HTTP的消息定义HTTP客户端采用POST或GET方法向服务器端发送请求，服务器端返回应答。HTTP请求和响应的格式如下：3.1.1 submitsubmit请求：请求地址：:8966/submit参数名称数据类型含 义是否必填备 注cpCodeStringCP用户名是cpPasswordStringCP密码是MD5加密后的32位字符串，请向SP客服索取。也可通过客户平台修改密码，修改后请向SP客服索取新的32位字符串userNumberString一个或多个接收该短消息的手机号是单次提交最多允

6、许1000个，号码之间用英文逗号分隔msgContentString短消息的内容是短信长度与cpcode所用通道有关，详询SP客服srcXIDString扩展号否SP分配，默认为空reserve1String保留，扩展用否reserve2String保留，扩展用否charsetString编码字符集否缺省值为GBK，目前支持GBK、utf-8、gb2312submit应答应答的文件格式是XML，编码是utf-8。参数名称数据类型含 义是否必填备 注resultString应答结果是0：接收成功其它：错误码*spmidStringSP内部信息标识是当result不为0时，该值为-1descrip

7、tionString应答描述否当result为0时，该值为空；当result不为0时，该值不为空reserve1String保留，扩展用否reserve2String保留，扩展用否示例：0 1974663.1.2 balancebalance请求：请求地址：:8966/balance参数名称数据类型含义是否必填备 注cpCodeStringCP用户名是cpPasswordStringCP密码是MD5加密后的32位字符串，请向客服索取。可通过客户平台修改密码，修改后请向客服索取新的32位字符串charsetString编码字符集否缺省值为GBK,目前支持GBK、utf-8、gb2312balan

8、ce应答应答的文件格式是XML，编码是utf-8。参数名称数据类型含 义是否必填备 注resultString应答结果是0：接收成功其它：错误码*balanceString余额否当result为0时，该信息为账户余额；当result不为0时，该信息为空descriptionString应答描述否reserve1String保留，扩展用否reserve2String保留，扩展用否示例：010023您的余额是100233.2基于通用Webservice的消息定义Webservice客户端向服务器端发送请求，服务器端返回应答。Webservice请求和响应的格式如下：3.2.1 submitsubm

9、it请求：请求地址：:8966/services/WS2Handler?wsdl方法名称：submit 参数名称数据类型含 义是否必填备 注cpCodeStringCP用户名是cpPasswordStringCP密码是MD5加密后的32位字符串，请向SP客服索取。可通过客户平台修改密码，修改后请向SP客服索取新的32位字符串userNumberString一个或多个接收该短消息的手机号是单次提交最多允许1000个，号码之间用英文逗号分隔msgContentString短消息的内容是短信长度与cpcode所用通道有关，详询SP客服srcXidString扩展号否SP分配，默认为空reserve1

10、String保留，扩展用否reserve2String保留，扩展用否submit应答应答的文件格式是XML，编码是utf-8。参数名称数据类型含 义是否必填备 注resultString应答结果是0：接收成功其它：错误码*spmidStringSP内部信息标识是当result不为0时，该值为-1descriptionString应答描述否当result为0时，该值为空；当result不为0时，该值不为空reserve1String保留，扩展用否reserve2String保留，扩展用否示例：0 1974663.2.2 balancebalance请求：请求地址：:8966/services/W

11、S2Handler?wsdl方法名称：balance 参数名称数据类型含义是否必填备 注cpCodeStringCP用户名是cpPasswordStringCP密码是MD5加密后的32位字符串，请向客服索取。可通过客户平台修改密码，修改后请向客服索取新的32位字符串balance应答应答的文件格式是XML，编码是utf-8。参数名称数据类型含 义是否必填备 注resultString应答结果是0：接收成功其它：错误码*balanceString余额否当result为0时，该信息为账户余额；当result不为0时，该信息为空descriptionString应答描述否reserve1String

12、保留，扩展用否reserve2String保留，扩展用否示例：010023您的余额是100234 接口常见问题5 修订历史版本号时间修订人主要内容或重大修改V1.02012.02袁建斌V1.12012.04袁建斌增加了余额查询接口v2.02012.08袁建斌1、修改了接口地址2、修改了参数名称3、增加了扩展参数4、增加了账户密码安全控制5、增加了使用示例6、优化了底层通迅速度注：对该文件内容增加、删除或修改均需填写此历史，详细记载变更信息，以保证其可追溯性。附录1错误码描 述0无错误，提交成功1用户名、密码、手机号、短信内容其中一项为空2用户名或者密码错误3账户余额不足4手机号码格式错误5短信内容字数超过限制6提交内容包含非法字符7手机号码个数超过限制8网络故障导致信息提交失败9不支持的字符集-1提交失败