亿美短信平台SDK4.2.0(WebService版都)用户手册.doc

1/16 页 案卷号案卷号 日期日期 亿美软通短信平台 SDK4.2.0（WebService 版） 用用 户户 手手 册册 作 者： 北京亿美软件科技有限公司 完成日期： 2010-08-16 签 收 人： 签收日期： 修改情况记录： 版本号修改批准人修改人安装日期签收人 北京亿美软通科技有限公司北京亿美软通科技有限公司 地址： 北京市朝阳区光华路 4 号东方梅地亚中心 C 座 20 层（100026） 网址：www.emay.cn 手机快捷网址：emay.m.cn 电话：010-58750575 传真：010-58750500 售前咨询：400-810-7255 售后服务：400-779-7255 手机中文实名：亿美软通 亿美 移动商务 2/16 页 目录目录 用 户 手 册.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 3/16 页 1 1 亿美软通亿美软通 WebServiceWebService 接口开发说明接口开发说明 1.11.1简介简介 亿美短信亿美短信 SDKSDK：是针对独立软件开发商（ISV）和系统集成商（SI）的软件开发 及技术产品服务的需求，提供的短信通讯开发组件（SDK，Software Development Kit) 1.21.2背景背景 系统名称：系统名称：亿美 SDK 移动商务开发组件 项目开发者项目开发者： 北京亿美软通科技有限公司 1.31.3定义定义 MTMT Message Terminal下行短信，即向手机终端发送短信 MOMO Message Original上行短信，即手机用户向特服号码发送短信 企业特服号码企业特服号码 由亿美为 SDK 用户分配的属于该用户专用的特服号码。每个 软件序列号对应一个企业特服号码。 扩展号码扩展号码 基于企业特服号码，企业自行扩展维护的子号码（最大 15 位） ，类似电话分机号码。 软件序列号软件序列号 由亿美分配给 SDK 用户，用来身份验证、计费的标识信息 EUCPEUCP Emay Unified Communication Platform亿美统一通讯平台 EUCP 实现了统一的接入，提供统一的服务 多运营商（中国移动、中国联通、中国网通、中国电信）的统一接入及服务提 供，只需通过一个 SDK 接入 EUCP 即可统一的与上述运营商的手机用户进行短信 通讯 4/16 页 余额余额 与 SDK 帐户即软件序列号对应的帐户余额，只有拥有足够的余额才能进行成功的短 信收发操作 KEYKEY 值值 默认情况下，注册序列号后，序列号会与电脑的硬件信息绑定，这样一个序列号只 能在一台定机器上使用。如果设置 Key 值，注册序列号后，序列号不会与电脑的硬件信息绑定 ，这样，一个序列号就可以在多台机器上使用（不同的电脑上设置相同的 Key 值即可） 。 优先级优先级 发送短信时，可以定义短信的优先级别，重要的短信定义的优先级可以高一些，普通 短信 可以使用低一点的优先级。可以定义 1-5 共 5 个级别的优先级，其中 1 为最低优先级，5 为最 高优先级 1.41.4开发流程开发流程 合作伙伴必须通过亿美软通或是亿美软通代理商，取得 SDK 开发包和相关文档， 取得供由本 SDK 使用的序列号及密码，这些参数将用于服务注册及短信发送。 接口调用流程如下： 永久执行永久执行 序列号首次使用时执行一次，就像我们的信用卡一样，首次使用必须激活一次 调用软件序列号注销以后，再次使用该序列号时必须重新激活 运行时执行运行时执行 主要是发送短信接口，软件序列号激活以后便可以随时使用我们的短信发送接口，前提是软件 序列号处于激活状态 需要时执行需要时执行 5/16 页 需要时执行的方法，调用频率相对较低，我们可以在需要的时候调用一次啊，前提是软件序列 号处于激活状态 结束执行结束执行 此接口一旦调用该软件序列号便不能在使用，即不能发送短信等，直到下次重新激活 2 2数据结构数据结构 2.12.1上行数据结构上行数据结构 所属类：MO 用途 保存上行短信接口函数返回的短信内容。 字段名字段名数据类型数据类型说明说明 mobileNumberString 手机号码 smsContentString 内容 sentTimeSting 发送时间（格式为 yyyy-mm-dd hi24:mi:ss） addSerialSting 发送者扩展号码（只有当发送者申请扩展号码功能后， 该参数才有效） addSerialRevSting 接收者扩展号码（只有当接收者申请扩展号码功能后， 该参数才有效） channelNumberString 该字段用来接收上行短信的被叫号码 2.2状态报告数据结构状态报告数据结构 所属类：StatusReport 用途 保存状态报告接口函数返回的短信内容。 字段名字段名数据类数据类 型型 说明说明 reportStatusString 状态报告的值（0 发送成功） mobileString 手机号码 submitDateSting 发送时间（格式为 yyyy-mm-dd hi24:mi:ss） receiveDateSting 接收时间（格式为 yyyy-mm-dd hi24:mi:ss） errorCodeSting 未发送成功错误编码 MemoSting 备注 6/16 页 serviceCodeAddSting 短信下行时服务号码 seqIDLong 自定义唯一的消息 ID，长度 6 位，消息流水号,顺序累 加,步长为 1,循环使用 3 3功能介绍及使用功能介绍及使用 3.13.1注册注册序列号序列号 功能介绍功能介绍 完成对序列号的注册。 序列号说明序列号说明 (1) 软件序列号首次使用必须注册，就像信用卡首次使用必须激活一样。 (2) 软件序列号只需注册成功一次即可，注册成功后，即使重启电脑，都不需再次注册序列号。 (3) 序列号注册成功后，需记住密码并妥善保管。 (4) 试用 SDK 接口时，亿美提供测试序列号，并提供适当测试余额。 (5) 正式应用 SDK 接口时，亿美提供正式序列号，在应用时，只需重新注册一次序列号即可，其它接 口不变。 函数声明函数声明 public int registEx(String softwareSerialNo, String key, String serialpass) 参数详解参数详解 参数名称参数名称说明说明 softwareSerialNo 软件序列号，必须输入 key 要注册的关键字，必须输入 1用户自定义 key 值， 长度不超过 15 个字符的 字符串(可包含数字和字母) 2将 key 做好备份，不要遗忘 3请做好保密工作，因客户自身原因泄露该关键 字造成的经济损失北京亿美软通科技有限公司不承 担任何责任 serialpass 软件序列号密码，密码（6 位） ，必须输入 返回值返回值 返回值返回值描述描述 7/16 页 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.23.2注册企业注册企业信息信息 功能介绍功能介绍 用户序列号激活以后便可以通过该接口注册自己的详细信息，如果要修企业的某个 信息，那么可重新调用该接口 函数声明函数声明 public int registDetailInfo(String softwareSerialNo, String serialPwd, 8/16 页 String eName, String inkman, String phoneNum, String mobile, String email, String fax, String address, String postcode) 参数详解参数详解 参数名称参数名称说明说明 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密码格式错误 9/16 页 -9003客户端 Key 格式错误 -9005公司地址格式错误 -9006企业中文名格式错误 -9007企业中文名简称格式错误 -9008邮件地址格式错误 -9009企业英文名格式错误 -9010企业英文名简称格式错误 -9011传真格式错误 -9012联系人格式错误 -9013联系电话 -9014邮编格式错误 -9025客户端请求 sdk5 超时 3.33.3注销注销序列号序列号 功能介绍功能介绍 软件注销返回 0 为成功(软件注销之后可以重新注册,余额保持注销前状态)，软件 注销以后必须重新激活才能使用短信发送接口 函数声明函数声明 public int logout(String softwareSerialNo, String key) 参数详解参数详解 返回值返回值描述，其它的请参见第四章描述，其它的请参见第四章 softwareSerialNo 软件序列号 key 关键字 key，和软件注册时的关键字必须一致 返回值返回值 返回值返回值描述描述 0注销成功 101、303客户端网络故障 305服务器端返回错误，错误的返回值（返回值不是数字 字符串） 999操作频繁 -1系统异常 -2客户端异常 -101命令不被支持 10/16 页 -104请求超过限制 -122号码注销激活失败 -126路由信息失败 -1104路由信息失败，请联系系统管理员 -190数据操作失败 -1902数据库更新操作失败 -9001序列号格式错误 -9002密码格式错误 -9003客户端 Key 格式错误 -9025客户端请求 sdk5 超时 -1100序列号错误，序列号不存在内存中，或尝试攻 击的客户 3.43.4查询查询单价单价 功能介绍功能介绍 获取发送一条短信所需要的费用 函数声明函数声明 public double getEachFee(String softwareSerialNo, String key) 参数详解参数详解 参数名称参数名称说明说明 softwareSerialNo 软件序列号 key 关键字,必须和软件注册时的关键字保持一致 返回值返回值 ：单价：单价 3.53.5序列号充值序列号充值 功能介绍功能介绍 获得充值卡后，调用此方法传入您的序列号 KEY，卡号及密码即可对该序列号 充值。 函数声明函数声明 public int chargeUp(String softwareSerialNo, String key, String cardNo,String cardPass) 参数详解参数详解 参数名称参数名称说明说明 11/16 页 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 超时 12/16 页 3.63.6发送短信发送短信 功能介绍功能介绍 短信发送函数,可发送即时短信，也可发送定时短信，当 sendTime 不为空且是 正确的时间各式，那么该条短信就是定时短信；当 sendTime 值为空时，则为 即时短信。 函数声明函数声明 public int sendSMS(String softwareSerialNo, String key, String sendTime, String mobiles, String smsContent, String addSerial, String srcCharset, int smsPriority,long smsID) 参数详解参数详解 参数名称参数名称说明说明 softwareSerialNo软件序列号 key 用户自定义 key 值， 长度不超过 15 个字符字，和软件 序列号注册时的关键字保持一致 sendTime 定时短信的定时时间，格式为:年年年年月月日日时时分 分秒秒,例如:20090504111010 代表 2009 年 5 月 4 日 11 时 10 分 10 秒，短信会在指定的时间发送出去 sendTime 值为空时，为即时发送短信 sendTime 值不为空时，为定时发送短信 mobiles 手机号码(字符串数组,最多为 200 个手机号码) smsContent 短信内容(最多 500 个汉字或 1000 个纯英文，emay 服务 器程序能够自动分割；亿美有多个通道为客户提供服务， 所以分割原则采用最短字数的通道为分割短信长度的规 则，请客户应用程序不要自己分割短信以免造成混乱) addSerial 扩展号码 (长度小于 15 的字符串) 用户可通过附加码自 定义短信类别 扩展号码的功能，需另外申请，当未申请扩展号码功能 时，该参数默认为空值即可。 srcCharset 字符编码，默认为“GBK“ smsPriority 短信等级，范围 15，数值越高优先级越高 smsID 短信 ID，自定义唯一的消息 ID，数字位数最大 19 位， 与状态报告 ID 一一对应，需用户自定义 ID 规则确保 ID 的唯一性。如果 smsID 为 0 将获取不到相应的状态 报告信息。 返回值返回值 返回值返回值描述描述 0短信发送成功 13/16 页 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.73.7接收短信接收短信 功能介绍功能介绍 从 EUCP 平台接收手机用户上行的短信，返回上行短信，该 list 的每个元素为一个 MO。 14/16 页 接收短信需要申请才可使用。 函数声明函数声明 public List getMO(String softwareSerialNo, String key) throws Exception 参数详解参数详解 参数参数说明说明 softwareSerialNo 软件序列号 key 关键字，必须和注册时的关键字保持一致 返回值返回值 返回结果返回结果说明说明 List 接收短信集合，集合中的值为类型为 MO 的对象，MO 的 结构请参考数据结构部分 3.83.8修改密码修改密码 功能介绍功能介绍 修改软件序列号的密码 函数声明函数声明 public int serialPwdUpd(String softwareSerialNo, String key,String serialPwd, String serialPwdNew) 参数详解参数详解 参数名称参数名称说明说明 softwareSerialNo 软件序列号 key 关键字 serialPwd 旧密码 serialPwdNew 新密码，6 位，必须是数字字符串，必须输入 返回值返回值 返回值返回值描述描述 0密码修改成功 101、303客户端网络故障 305服务器端返回错误，错误的返回值（返回值不是数字 字符串） 308新密码不是数字，必须是数字 999操作频繁 -1系统异常 15/16 页 -2客户端异常 -101命令不被支持 -104请求超过限制 -120修改密码失败 -9025 客户端请求 sdk5 超时 -9015 新密码格式错误 -9001序列号格式错误 -9002密码格式错误 -9003客户端 Key 格式错误 3.93.9查询余额查询余额 功能介绍功能介绍 获得序列号当前余额 函数声明函数声明 public double getBalance(String softwareSerialNo, String key)throws Exception 参数详解参数详解 参数名称参数名称说明说明 softwareSerialNo 软件序列号 key 关键字,必须和软件注册时的关键字保持一致 返回值返回值 ： 余额。余额。 3.103.10 接收状态报告接收状态报告 功能介绍功能介绍 接收短信发送状态报告 函数声明函数声明 public List getReport(String softwareSerialNo, String key) 参数详解参数详解 参数参数说明说明 softwareSerialNo 软件序列号 Key 关键字，必须和注册时的 key 保持一致 16/16 页 返回值返回值 返回结果返回结果说明说明 List 接收短信集合，集合中的值为类型为的 StatusReport 对象，StatusReport 的结构请 参考数据结构部分