亿美短信平台SDK420WebService版用户手册.docx
《亿美短信平台SDK420WebService版用户手册.docx》由会员分享，可在线阅读，更多相关《亿美短信平台SDK420WebService版用户手册.docx（20页珍藏版）》请在冰豆网上搜索。
亿美短信平台SDK420WebService版用户手册
案卷号
日期
亿美软通短信平台SDK4.2.0（WebService版）
用户手册
作者：
北京亿美软件科技有限公司
完成日期：
2010-08-16
签收人：
签收日期：
修改情况记录：
版本号
修改批准人
修改人
安装日期
签收人
北京亿美软通科技有限公司
地址：
北京市朝阳区光华路4号东方梅地亚中心C座20层（）
网址：
手机快捷网址：
电话：
010-传真：
010-
售前咨询：
400-810-7255售后服务：
400-779-7255
手机中文实名：
亿美软通亿美移动商务
目录
用户手册1
1亿美软通WebService接口开发说明3
1.1简介3
1.2背景3
1.3定义3
1.4开发流程4
2数据结构5
2.1上行数据结构5
2.2状态报告数据结构5
3功能介绍及使用5
3.1注册序列号5
3.2注册企业信息6
3.3注销序列号7
3.4查询单价8
3.5序列号充值8
3.6发送短信8
3.7接收短信9
3.8修改密码10
3.9查询余额11
3.10状态报告………………………………………………………………………………………..12
1亿美软通WebService接口开发说明
1.1简介
亿美短信SDK：
是针对独立软件开发商（ISV）和系统集成商（SI）的软件开发
及技术产品服务的需求，提供的短信通讯开发组件（SDK，SoftwareDevelopmentKit）
1.2背景
系统名称：
亿美SDK移动商务开发组件
项目开发者：
北京亿美软通科技有限公司
1.3定义
MTMessageTerminal——下行短信，即向手机终端发送短信
MOMessageOriginal——上行短信，即手机用户向特服号码发送短信
企业特服号码由亿美为SDK用户分配的属于该用户专用的特服号码。
每个软件序列号对应一个企业特服号码。
扩展号码基于企业特服号码，企业自行扩展维护的子号码（最大15位），类似电话分机号码。
软件序列号由亿美分配给SDK用户，用来身份验证、计费的标识信息
EUCPEmayUnifiedCommunicationPlatform——亿美统一通讯平台
EUCP实现了统一的接入，提供统一的服务
多运营商（中国移动、中国联通、中国网通、中国电信）的统一接入及服务提供，只需通过一个SDK接入EUCP即可统一的与上述运营商的手机用户进行短信通讯
余额与SDK帐户即软件序列号对应的帐户余额，只有拥有足够的余额才能进行成功的短信收发操作
KEY值默认情况下，注册序列号后，序列号会与电脑的硬件信息绑定，这样一个序列号只
能在一台定机器上使用。
如果设置Key值，注册序列号后，序列号不会与电脑的硬件信息绑定
，这样，一个序列号就可以在多台机器上使用（不同的电脑上设置相同的Key值即可）。
优先级发送短信时，可以定义短信的优先级别，重要的短信定义的优先级可以高一些，普通短信可以使用低一点的优先级。
可以定义1-5共5个级别的优先级，其中1为最低优先级，5为最高优先级
1.4开发流程
合作伙伴必须通过亿美软通或是亿美软通代理商，取得SDK开发包和相关文档，
取得供由本SDK使用的序列号及密码，这些参数将用于服务注册及短信发送。
接口调用流程如下：
●永久执行
Ø序列号首次使用时执行一次，就像我们的信用卡一样，首次使用必须激活一次
Ø调用软件序列号注销以后，再次使用该序列号时必须重新激活
●运行时执行
Ø主要是发送短信接口，软件序列号激活以后便可以随时使用我们的短信发送接口，前提是软件序列号处于激活状态
●需要时执行
Ø需要时执行的方法，调用频率相对较低，我们可以在需要的时候调用一次啊，前提是软件序列号处于激活状态
●结束执行
Ø此接口一旦调用该软件序列号便不能在使用，即不能发送短信等，直到下次重新激活
2数据结构
2.1上行数据结构
●所属类：
MO
●用途保存上行短信接口函数返回的短信内容。
字段名
数据类型
说明
mobileNumber
String
手机号码
smsContent
String
内容
sentTime
Sting
发送时间（格式为yyyy-mm-ddhi24:
mi:
ss）
addSerial
Sting
发送者扩展号码（只有当发送者申请扩展号码功能后，该参数才有效）
addSerialRev
Sting
接收者扩展号码（只有当接收者申请扩展号码功能后，该参数才有效）
channelNumber
String
该字段用来接收上行短信的被叫号码
2.2状态报告数据结构
●所属类：
StatusReport
●用途保存状态报告接口函数返回的短信内容。
字段名
数据类型
说明
reportStatus
String
状态报告的值（0发送成功）
mobile
String
手机号码
submitDate
Sting
发送时间（格式为yyyy-mm-ddhi24:
mi:
ss）
receiveDate
Sting
接收时间（格式为yyyy-mm-ddhi24:
mi:
ss）
errorCode
Sting
未发送成功错误编码
Memo
Sting
备注
serviceCodeAdd
Sting
短信下行时服务号码
seqID
Long
自定义唯一的消息ID，长度6位，消息流水号,顺序累加,步长为1,循环使用
3功能介绍及使用
3.1注册序列号
●功能介绍
完成对序列号的注册。
●序列号说明
（1）软件序列号首次使用必须注册，就像信用卡首次使用必须激活一样。
（2）软件序列号只需注册成功一次即可，注册成功后，即使重启电脑，都不需再次注册序列号。
（3）序列号注册成功后，需记住密码并妥善保管。
（4）试用SDK接口时，亿美提供测试序列号，并提供适当测试余额。
（5）正式应用SDK接口时，亿美提供正式序列号，在应用时，只需重新注册一次序列号即可，其它接口不变。
●函数声明
publicintregistEx（StringsoftwareSerialNo,Stringkey,Stringserialpass）
●参数详解
参数名称
说明
softwareSerialNo
软件序列号，必须输入
key
要注册的关键字，必须输入
1．用户自定义key值，长度不超过15个字符的字符串（可包含数字和字母）
2．将key做好备份，不要遗忘
3．请做好保密工作，因客户自身原因泄露该关键字造成的经济损失北京亿美软通科技有限公司不承担任何责任
serialpass
软件序列号密码，密码（6位），必须输入
●返回值
返回值
描述
0
注册成功
101、303
客户端网络故障
305
服务器端返回错误，错误的返回值（返回值不是数字字符串）
999
操作频繁
-1
系统异常
-2
客户端异常
-101
命令不被支持
-104
请求超过限制
-110
号码注册激活失败
-126
路由信息失败
-190
数据操作失败
-1100
序列号错误，序列号不存在内存中，或尝试攻击的用户
-1103
序列号Key错误
-1102
序列号密码错误
-1104
路由失败，请联系系统管理员
-1105
注册号状态异常,未用1
-1107
注册号状态异常,停用3
-1108
注册号状态异常,停止5
-1901
数据库插入操作失败
-9001
序列号格式错误
-9002
密码格式错误
-9025
客户端请求sdk5超时
-9003
客户端Key格式错误
3.2注册企业信息
●功能介绍
用户序列号激活以后便可以通过该接口注册自己的详细信息，如果要修企业的某个信息，那么可重新调用该接口
●函数声明
publicintregistDetailInfo（StringsoftwareSerialNo,StringserialPwd,
StringeName,String_inkman,StringphoneNum,Stringmobile,
Stringemail,Stringfax,Stringaddress,Stringpostcode）
●参数详解
参数名称
说明
softwareSerialNo
软件序列号
key
关键字key，必须和软件序列号注册的key一致
eName
企业名称（最多60字节），必须输入
linkMan
联系人姓名（最多20字节），必须输入
phoneNum
联系电话（最多20字节），必须输入
mobile
联系手机（最多15字节），必须输入
email
电子邮件（最多60字节），必须输入
fax
联系传真（最多20字节），必须输入
address
公司地址（最多60字节），必须输入
postcode
邮政编码（最多6字节），必须输入
●返回值
返回值
描述
0
注册企业信息成功
101、303
客户端网络故障
305
服务器端返回错误，错误的返回值（返回值不是数字字符串）
307
目标电话号码不符合规则，电话号码必须是以0、1开头
999
操作频繁
-1
系统异常
-2
客户端异常
-101
命令不被支持
-104
请求超过限制
-111
企业注册失败
-126
路由信息失败
-190
数据操作失败
-1104
路由失败请联系系统管理员
-1901
数据库插入操作失败
-9001
序列号格式错误
-9002
密码格式错误
-9003
客户端Key格式错误
-9005
公司地址格式错误
-9006
企业中文名格式错误
-9007
企业中文名简称格式错误
-9008
邮件地址格式错误
-9009
企业英文名格式错误
-9010
企业英文名简称格式错误
-9011
传真格式错误
-9012
联系人格式错误
-9013
联系电话
-9014
邮编格式错误
-9025
客户端请求sdk5超时
3.3注销序列号
●功能介绍
软件注销返回0为成功（软件注销之后可以重新注册,余额保持注销前状态），软件注销以后必须重新激活才能使用短信发送接口
●函数声明
publicintlogout（StringsoftwareSerialNo,Stringkey）
●参数详解
返回值
描述，其它的请参见第四章
softwareSerialNo
软件序列号
key
关键字key，和软件注册时的关键字必须一致
●返回值
返回值
描述
0
注销成功
101、303
客户端网络故障
305
服务器端返回错误，错误的返回值（返回值不是数字字符串）
999
操作频繁
-1
系统异常
-2
客户端异常
-101
命令不被支持
-104
请求超过限制
-122
号码注销激活失败
-126
路由信息失败
-1104
路由信息失败，请联系系统管理员
-190
数据操作失败
-1902
数据库更新操作失败
-9001
序列号格式错误
-9002
密码格式错误
-9003
客户端Key格式错误
-9025
客户端请求sdk5超时
-1100
序列号错误，序列号不存在内存中，或尝试攻击的客户
3.4查询单价
●功能介绍
获取发送一条短信所需要的费用
●函数声明
publicdoublegetEachFee（StringsoftwareSerialNo,Stringkey）
●参数详解
参数名称
说明
softwareSerialNo
软件序列号
key
关键字,必须和软件注册时的关键字保持一致
●返回值：
单价
3.5序列号充值
●功能介绍
获得充值卡后，调用此方法传入您的序列号KEY，卡号及密码即可对该序列号充值。
●函数声明
publicintchargeUp（StringsoftwareSerialNo,Stringkey,StringcardNo,StringcardPass）
●参数详解
参数名称
说明
softwareSerialNo
软件序列号
key
关键字，和软件注册的关键字必须一致
cardNo
充值卡号
cardPass
充值卡密码
●返回值
返回值
描述
0
充值成功
101、303
客户端网络故障
305
服务器端返回错误，错误的返回值（返回值不是数字字符串）
999
操作频繁
-1
系统异常
-2
客户端异常
-101
命令不被支持
-104
请求超过限制
-126
路由信息失败
-190
数据操作失败
-9001
序列号格式错误
-9002
密码格式错误
-9003
客户端Key格式错误
-113
充值失败
-1131
充值卡无效
-1132
充值密码无效
-1133
充值卡绑定异常
-1134
充值状态无效
-1135
充值金额无效
-1902
数据更新操作失败
-9023
充值卡号格式错误
-9024
充值密码格式错误
-9025
客户端请求sdk5超时
3.6发送短信
●功能介绍
短信发送函数,可发送即时短信，也可发送定时短信，当sendTime不为空且是正确的时间各式，那么该条短信就是定时短信；当sendTime值为空时，则为即时短信。
●函数声明
publicintsendSMS（StringsoftwareSerialNo,Stringkey,StringsendTime,
String[]mobiles,StringsmsContent,StringaddSerial,
StringsrcCharset,intsmsPriority,longsmsID）
●参数详解
参数名称
说明
softwareSerialNo
软件序列号
key
用户自定义key值，长度不超过15个字符字，和软件序列号注册时的关键字保持一致
sendTime
定时短信的定时时间，格式为:
年年年年月月日日时时分分秒秒,例如:
010代表2009年5月4日11时10分10秒，短信会在指定的时间发送出去
sendTime值为空时，为即时发送短信
sendTime值不为空时，为定时发送短信
mobiles
手机号码（字符串数组,最多为200个手机号码）
smsContent
短信内容（最多500个汉字或1000个纯英文，emay服务器程序能够自动分割；亿美有多个通道为客户提供服务，所以分割原则采用最短字数的通道为分割短信长度的规则，请客户应用程序不要自己分割短信以免造成混乱）
addSerial
扩展号码（长度小于15的字符串）用户可通过附加码自定义短信类别
扩展号码的功能，需另外申请，当未申请扩展号码功能时，该参数默认为空值即可。
srcCharset
字符编码，默认为"GBK"
smsPriority
短信等级，范围1~5，数值越高优先级越高
smsID
短信ID，自定义唯一的消息ID，数字位数最大19位，与状态报告ID一一对应，需用户自定义ID规则确保ID的唯一性。
如果smsID为0将获取不到相应的状态报告信息。
返回值
返回值
描述
0
短信发送成功
305
服务器端返回错误，错误的返回值（返回值不是数字字符串）
101、303
客户端网络故障
307
目标电话号码不符合规则，电话号码必须是以0、1开头
997
平台返回找不到超时的短信，该信息是否成功无法确定
998
由于客户端网络问题导致信息发送超时，该信息是否成功下发无法确定
-1
系统异常
-2
客户端异常
-101
命令不被支持
-104
请求超过限制
-117
发送短信失败
-127
没有余额
-128
余额不足
-1104
路由失败，请联系系统管理员
-9016
发送短信包大小超出范围
-9017
发送短信内容格式错误
-9018
发送短信扩展号格式错误
-9019
发送短信优先级格式错误
-9020
发送短信手机号格式错误
-9021
发送短信定时时间格式错误
-9022
发送短信唯一序列值错误
-9001
序列号格式错误
-9002
密码格式错误
-9003
客户端Key格式错误
-9025
客户端请求sdk5超时
3.7接收短信
●功能介绍
从EUCP平台接收手机用户上行的短信，返回上行短信，该list的每个元素为一个MO。
接收短信需要申请才可使用。
●函数声明
publicListgetMO（StringsoftwareSerialNo,Stringkey）throwsException
●参数详解
参数
说明
softwareSerialNo
软件序列号
key
关键字，必须和注册时的关键字保持一致
●返回值
返回结果
说明
List
接收短信集合，集合中的值为类型为MO的对象，MO的结构请参考数据结构部分
3.8修改密码
●功能介绍
修改软件序列号的密码
●函数声明
publicintserialPwdUpd（StringsoftwareSerialNo,Stringkey,StringserialPwd,StringserialPwdNew）
●参数详解
参数名称
说明
softwareSerialNo
软件序列号
key
关键字
serialPwd
旧密码
serialPwdNew
新密码，6位，必须是数字字符串，必须输入
●返回值
返回值
描述
0
密码修改成功
101、303
客户端网络故障
305
服务器端返回错误，错误的返回值（返回值不是数字字符串）
308
新密码不是数字，必须是数字
999
操作频繁
-1
系统异常
-2
客户端异常
-101
命令不被支持
-104
请求超过限制
-120
修改密码失败
-9025
客户端请求sdk5超时
-9015
新密码格式错误
-9001
序列号格式错误
-9002
密码格式错误
-9003
客户端Key格式错误
3.9查询余额
●功能介绍
获得序列号当前余额
●函数声明
publicdoublegetBalance（StringsoftwareSerialNo,Stringkey）throwsException
●参数详解
参数名称
说明
softwareSerialNo
软件序列号
key
关键字,必须和软件注册时的关键字保持一致
●返回值：
余额。
3.10接收状态报告
●功能介绍
接收短信发送状态报告
●函数声明
publicListgetReport（StringsoftwareSerialNo,Stringkey）
●参数详解
参数
说明
softwareSerialNo
软件序列号
Key
关键字，必须和注册时的key保持一致
●返回值
返回结果
说明
List
接收短信集合，集合中的值为类型为的StatusReport对象，StatusReport的结构请参考数据结构部分
升级会员 