亿美短信平台SDK420WebService版用户手册.docx

1、亿美短信平台SDK420WebService版用户手册案卷号日期亿美软通短信平台SDK4.2.0（WebService版）用 户 手 册 作 者： 北京亿美软件科技有限公司 完成日期： 2010-08-16 签 收 人： 签收日期： 修改情况记录：版本号修改批准人修改人安装日期签收人北京亿美软通科技有限公司地址：北京市朝阳区光华路4号东方梅地亚中心C座20层（）网址： 手机快捷网址：电话：010- 传真：010-售前咨询：400-810-7255 售后服务：400-779-7255手机中文实名：亿美软通 亿美 移动商务目录用 户 手 册 11亿美软通WebService接口开发说明 31.1

2、简介 31.2 背景 31.3 定义 31.4 开发流程 42 数据结构 52.1 上行数据结构 52.2 状态报告数据结构 53 功能介绍及使用 53.1 注册序列号 53.2 注册企业信息 63.3 注销序列号 73.4 查询单价 83.5 序列号充值 83.6 发送短信 83.7 接收短信 93.8 修改密码 103.9 查询余额 11 3.10 状态报告.121亿美软通WebService接口开发说明1.1 简介亿美短信SDK：是针对独立软件开发商（ISV）和系统集成商（SI）的软件开发及技术产品服务的需求，提供的短信通讯开发组件（SDK，Software Development Ki

3、t)1.2 背景系统名称：亿美SDK移动商务开发组件项目开发者： 北京亿美软通科技有限公司1.3 定义MT Message Terminal下行短信，即向手机终端发送短信MO Message Original上行短信，即手机用户向特服号码发送短信企业特服号码 由亿美为SDK用户分配的属于该用户专用的特服号码。每个 软件序列号对应一个企业特服号码。扩展号码 基于企业特服号码，企业自行扩展维护的子号码（最大15位），类似电话分机号码。软件序列号 由亿美分配给SDK用户，用来身份验证、计费的标识信息EUCP Emay Unified Communication Platform亿美统一通讯平台EUC

4、P实现了统一的接入，提供统一的服务多运营商（中国移动、中国联通、中国网通、中国电信）的统一接入及服务提供，只需通过一个SDK接入EUCP即可统一的与上述运营商的手机用户进行短信通讯余额 与SDK帐户即软件序列号对应的帐户余额，只有拥有足够的余额才能进行成功的短信收发操作KEY值 默认情况下，注册序列号后，序列号会与电脑的硬件信息绑定，这样一个序列号只能在一台定机器上使用。如果设置Key值，注册序列号后，序列号不会与电脑的硬件信息绑定，这样，一个序列号就可以在多台机器上使用（不同的电脑上设置相同的Key值即可）。优先级 发送短信时，可以定义短信的优先级别，重要的短信定义的优先级可以高一些，普通短

5、信 可以使用低一点的优先级。可以定义1-5 共5个级别的优先级，其中1为最低优先级，5为最高优先级1.4 开发流程合作伙伴必须通过亿美软通或是亿美软通代理商，取得SDK开发包和相关文档，取得供由本SDK使用的序列号及密码，这些参数将用于服务注册及短信发送。接口调用流程如下： 永久执行 序列号首次使用时执行一次，就像我们的信用卡一样，首次使用必须激活一次 调用软件序列号注销以后，再次使用该序列号时必须重新激活 运行时执行 主要是发送短信接口，软件序列号激活以后便可以随时使用我们的短信发送接口，前提是软件序列号处于激活状态 需要时执行 需要时执行的方法，调用频率相对较低，我们可以在需要的时候调用一

6、次啊，前提是软件序列号处于激活状态 结束执行 此接口一旦调用该软件序列号便不能在使用，即不能发送短信等，直到下次重新激活2 数据结构2.1 上行数据结构 所属类：MO 用途 保存上行短信接口函数返回的短信内容。字段名数据类型说明mobileNumberString手机号码smsContentString内容sentTimeSting发送时间（格式为yyyy-mm-dd hi24:mi:ss）addSerialSting发送者扩展号码（只有当发送者申请扩展号码功能后，该参数才有效）addSerialRevSting接收者扩展号码（只有当接收者申请扩展号码功能后，该参数才有效）channelNum

7、berString该字段用来接收上行短信的被叫号码2.2 状态报告数据结构 所属类：StatusReport 用途 保存状态报告接口函数返回的短信内容。字段名数据类型说明reportStatusString状态报告的值（0发送成功）mobileString手机号码submitDateSting发送时间（格式为yyyy-mm-dd hi24:mi:ss）receiveDateSting接收时间（格式为yyyy-mm-dd hi24:mi:ss）errorCodeSting未发送成功错误编码MemoSting备注serviceCodeAddSting短信下行时服务号码seqIDLong自定义唯一的

8、消息ID，长度6位，消息流水号,顺序累加,步长为1,循环使用3 功能介绍及使用 3.1 注册序列号 功能介绍完成对序列号的注册。 序列号说明(1) 软件序列号首次使用必须注册，就像信用卡首次使用必须激活一样。(2) 软件序列号只需注册成功一次即可，注册成功后，即使重启电脑，都不需再次注册序列号。(3) 序列号注册成功后，需记住密码并妥善保管。(4) 试用SDK接口时，亿美提供测试序列号，并提供适当测试余额。(5) 正式应用SDK接口时，亿美提供正式序列号，在应用时，只需重新注册一次序列号即可，其它接口不变。 函数声明public int registEx(String softwareSeri

9、alNo, String key, String serialpass) 参数详解 参数名称说明softwareSerialNo软件序列号，必须输入key要注册的关键字，必须输入1 用户自定义key值， 长度不超过15个字符的字符串(可包含数字和字母)2 将key做好备份，不要遗忘3 请做好保密工作，因客户自身原因泄露该关键字造成的经济损失北京亿美软通科技有限公司不承担任何责任serialpass软件序列号密码，密码（6位），必须输入 返回值返回值描述0注册成功101、303客户端网络故障305服务器端返回错误，错误的返回值（返回值不是数字字符串）999操作频繁-1系统异常-2客户端异常-10

10、1命令不被支持-104请求超过限制-110号码注册激活失败-126路由信息失败-190数据操作失败-1100序列号错误，序列号不存在内存中，或尝试攻击的用户-1103序列号Key错误-1102序列号密码错误-1104路由失败，请联系系统管理员-1105注册号状态异常, 未用 1-1107注册号状态异常, 停用 3-1108注册号状态异常, 停止 5-1901数据库插入操作失败-9001序列号格式错误-9002密码格式错误-9025客户端请求sdk5超时-9003客户端Key格式错误3.2 注册企业信息 功能介绍用户序列号激活以后便可以通过该接口注册自己的详细信息，如果要修企业的某个信息，那么可

11、重新调用该接口 函数声明public int registDetailInfo(String softwareSerialNo, String serialPwd, String eName, String _inkman, String phoneNum, String mobile, String email, String fax, String address, String postcode) 参数详解参数名称说明softwareSerialNo软件序列号key关键字key，必须和软件序列号注册的key一致eName企业名称(最多60字节)，必须输入linkMan联系人姓名(最多20

12、字节)，必须输入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

13、数据操作失败-1104路由失败请联系系统管理员-1901数据库插入操作失败-9001序列号格式错误-9002密码格式错误-9003客户端Key格式错误-9005公司地址格式错误-9006企业中文名格式错误-9007企业中文名简称格式错误-9008邮件地址格式错误-9009企业英文名格式错误-9010企业英文名简称格式错误-9011传真格式错误-9012联系人格式错误-9013联系电话-9014邮编格式错误-9025客户端请求sdk5超时3.3 注销序列号 功能介绍软件注销返回0为成功(软件注销之后可以重新注册,余额保持注销前状态)，软件注销以后必须重新激活才能使用短信发送接口 函数声明publ

14、ic int logout(String softwareSerialNo, String key) 参数详解返回值描述，其它的请参见第四章softwareSerialNo 软件序列号key关键字key，和软件注册时的关键字必须一致 返回值返回值描述0注销成功101、303客户端网络故障305服务器端返回错误，错误的返回值（返回值不是数字字符串）999操作频繁-1系统异常-2客户端异常-101命令不被支持-104请求超过限制-122号码注销激活失败-126路由信息失败-1104路由信息失败，请联系系统管理员-190数据操作失败-1902数据库更新操作失败-9001序列号格式错误-9002密码格

15、式错误-9003客户端Key格式错误-9025客户端请求sdk5超时-1100序列号错误，序列号不存在内存中，或尝试攻击的客户3.4 查询单价 功能介绍获取发送一条短信所需要的费用 函数声明public double getEachFee(String softwareSerialNo, String key) 参数详解参数名称说明softwareSerialNo 软件序列号key关键字,必须和软件注册时的关键字保持一致 返回值 ：单价 3.5 序列号充值 功能介绍获得充值卡后，调用此方法传入您的序列号KEY，卡号及密码即可对该序列号充值。 函数声明public int chargeUp(St

16、ring softwareSerialNo, String key, String cardNo,String cardPass) 参数详解参数名称说明softwareSerialNo软件序列号key关键字，和软件注册的关键字必须一致cardNo充值卡号cardPass充值卡密码 返回值返回值描述0充值成功101、303客户端网络故障305服务器端返回错误，错误的返回值（返回值不是数字字符串）999操作频繁-1系统异常-2客户端异常-101命令不被支持-104请求超过限制-126路由信息失败-190数据操作失败-9001序列号格式错误-9002密码格式错误-9003客户端Key格式错误-113

17、充值失败-1131充值卡无效-1132充值密码无效-1133充值卡绑定异常-1134充值状态无效-1135充值金额无效-1902数据更新操作失败-9023充值卡号格式错误-9024充值密码格式错误-9025客户端请求sdk5超时3.6 发送短信 功能介绍短信发送函数,可发送即时短信，也可发送定时短信，当sendTime不为空且是正确的时间各式，那么该条短信就是定时短信；当sendTime值为空时，则为即时短信。 函数声明public int sendSMS(String softwareSerialNo, String key, String sendTime, String mobiles,

18、 String smsContent, String addSerial, String srcCharset, int smsPriority,long smsID) 参数详解参数名称说明softwareSerialNo软件序列号key用户自定义key值， 长度不超过15个字符字，和软件序列号注册时的关键字保持一致sendTime定时短信的定时时间，格式为:年年年年月月日日时时分分秒秒,例如:010 代表2009年5月4日 11时10分10秒，短信会在指定的时间发送出去sendTime值为空时，为即时发送短信sendTime值不为空时，为定时发送短信mobiles手机号码(字符串数组,最多为

19、200个手机号码)smsContent短信内容(最多500个汉字或1000个纯英文，emay服务器程序能够自动分割；亿美有多个通道为客户提供服务，所以分割原则采用最短字数的通道为分割短信长度的规则，请客户应用程序不要自己分割短信以免造成混乱)addSerial扩展号码 (长度小于15的字符串) 用户可通过附加码自定义短信类别 扩展号码的功能，需另外申请，当未申请扩展号码功能时，该参数默认为空值即可。srcCharset字符编码，默认为GBKsmsPriority短信等级，范围15，数值越高优先级越高smsID短信ID，自定义唯一的消息ID，数字位数最大19位，与状态报告ID一一对应，需用户自定

20、义ID规则确保ID的唯一性。如果smsID为0将获取不到相应的状态报告信息。返回值返回值描述0短信发送成功305服务器端返回错误，错误的返回值（返回值不是数字字符串）101、303客户端网络故障307目标电话号码不符合规则，电话号码必须是以0、1开头997平台返回找不到超时的短信，该信息是否成功无法确定998由于客户端网络问题导致信息发送超时，该信息是否成功下发无法确定-1系统异常-2客户端异常-101命令不被支持-104请求超过限制-117发送短信失败-127没有余额-128余额不足-1104路由失败，请联系系统管理员-9016发送短信包大小超出范围-9017发送短信内容格式错误-9018发

21、送短信扩展号格式错误-9019发送短信优先级格式错误-9020发送短信手机号格式错误-9021发送短信定时时间格式错误-9022发送短信唯一序列值错误-9001序列号格式错误-9002密码格式错误-9003客户端Key格式错误-9025客户端请求sdk5超时3.7 接收短信 功能介绍 从EUCP平台接收手机用户上行的短信，返回上行短信，该list的每个元素为一个MO。接收短信需要申请才可使用。 函数声明public List getMO(String softwareSerialNo, String key) throws Exception 参数详解参数说明softwareSerialNo软

22、件序列号key关键字，必须和注册时的关键字保持一致 返回值返回结果说明List接收短信集合，集合中的值为类型为MO的对象，MO的结构请参考数据结构部分3.8 修改密码 功能介绍修改软件序列号的密码 函数声明public int serialPwdUpd(String softwareSerialNo, String key,String serialPwd, String serialPwdNew) 参数详解参数名称说明softwareSerialNo软件序列号key关键字serialPwd旧密码serialPwdNew新密码，6位，必须是数字字符串，必须输入 返回值返回值描述0密码修改成功1

23、01、303客户端网络故障305服务器端返回错误，错误的返回值（返回值不是数字字符串）308新密码不是数字，必须是数字999操作频繁-1系统异常-2客户端异常-101命令不被支持-104请求超过限制-120修改密码失败-9025客户端请求sdk5超时-9015新密码格式错误-9001序列号格式错误-9002密码格式错误-9003客户端Key格式错误3.9 查询余额 功能介绍 获得序列号当前余额 函数声明public double getBalance(String softwareSerialNo, String key)throws Exception 参数详解参数名称说明softwareSerialNo 软件序列号key关键字,必须和软件注册时的关键字保持一致 返回值 ： 余额。 3.10 接收状态报告 功能介绍接收短信发送状态报告 函数声明public List getReport(String softwareSerialNo, String key) 参数详解参数说明softwareSerialNo软件序列号Key关键字，必须和注册时的key保持一致 返回值返回结果说明List接收短信集合，集合中的值为类型为的StatusReport对象，StatusReport的结构请参考数据结构部分