易信通平台接口手册(电信用户).docx

易信通平台接口手册EMS平台接口手册产品名称EMS平台发布日期2013/7/20目 录1、引言31.1.目的31.2.修改历史记录31.3.名称解释32、短信42.1.http接口42.1.1.短信发送42.1.2.短信接收52.1.3.查询状态报告62.1.4.查询余额82.1.5.查询关键字92.2.WebService接口102.2.1.短信发送102.2.2.短信接收112.2.3.查询状态报告132.2.4.查询余额142.2.5.查询关键字15附录：公共错误代码定义161、 引言1.1. 目的该接口手册编写目的在于描述企业信息系统（以下简称EMS）具体的接口协议，供接口用户进行接口的对接开发。1.2. 修改历史记录版 本修改人日 期描 述V陈林2013-07-20创建文档。V陈林2013-11-19增加2.1.2及2.2.2一对一批量发送，同时增加两个错误代码值13，14V陈林2013-12-10增加2.3 节 DB接口V陈林2014-03-09增加错误代码15 签名未报备V陈林2014-04-14DB接口升级：增加监控，路由功能V陈林2014-04-28增加错误代码16 单位时间内该号码最大发送限制V陈林2014-05-20增加错误代码17 校验签名时签名长度及格式非法1.3. 名称解释缩略语英文全名中文全名EMSEnterprise Message System企业信息系统SMSShort Messaging Service短消息服务MMSMultimedia Message Service多媒体消息APIApplication Programming Interface应用程序编程接口MOMessage Original消息上行MTMessage Terminal消息下行SPService Provider服务提供商CPContent Provider内容提供商2、 短信2.1. http接口2.1.1. 短信发送功能：发送短信地址： 2/sendSMS.action备注：建议采用post方法提交请求。请求参数定义如下： 参数名称描述字段值enterpriseID企业ID由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.smsId消息idString，可以为空。消息id是这个包唯一标识，若为空则系统随机分配一个唯一标识值。若不为空，由用户自己设置一个唯一标识值。该值做为应答及状态报告中的消息id一一对应。 subPort扩展端口String,可以为空。空表示不再扩展，若扩展必须是数字如：00，01，02若扩展输入00则手机收到端口号为：10657*00(备注：扩展必须此帐户配置通道支持)content短信内容String 不可以为空，内容采用utf-8编码mobiles接收手机号码String，不可以为空。支持移动，联通，电信混合提交;多个号码中间采用半角逗号分隔,每个包最大支持100个号码。例13000000000endTime定时发送时间String,可以为空。为空表示立即发送，定时时间格式为：yyyy-MM-dd HH:mm:ss返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录： 公共错误代码定义SmsId消息id,用于配对状态报告,每个包提交返回消息id唯一。若发送时设置消息id，则返回是设置消息id值。失败返回结果样例：1成功返回结果样例：0102012012002.1.2. 一对一批量发送功能：发送短信地址： 2/batchSingleSendSMS.action备注：建议采用post方法提交请求。请求参数定义如下： 参数名称描述字段值enterpriseID企业ID由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.batchSmsId消息id串String，可以为空。消息id串每一个号码即一条短信对应一个id值，该值唯一区分每一个短信。同一批次提交多个信息消息id值中间采用半角逗号分隔，若为空则系统随机分配一批消息id值，与号码串一一对应。若不为空，由用户自己设置一批消息id值，中间用半角逗号分隔，注意每一个消息id唯一。该值做为应答及状态报告中的消息id一一对应。 subPort扩展端口String,可以为空。空表示不再扩展，若扩展必须是数字如：00，01，02若扩展输入00则手机收到端口号为：10657*00(备注：扩展必须此帐户配置通道支持)batchContent短信内容String 不可以为空，内容采用utf-8编码,批量提交多个内容格式：内容1,内容2,内容3,内容n 若内容只有一个则格式：内容batchMobiles接收手机号码String，不可以为空。支持移动，联通，电信混合提交;多个号码中间采用半角逗号分隔,每个包最大支持100个号码。例13000000000endTime定时发送时间String,可以为空。为空表示立即发送，定时时间格式为：yyyy-MM-dd HH:mm:ss备注：批量发送一对一时，batchSmsId,batchContent,batchMobiles三个参数当batchSmsId不为空时，这三个参数分解出来短信对应个数必须一致，否则返回错误代码13（批量一对一参数格式错误）。返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义SmsIdList消息id节点集合，只有Result值为0，即处理成功时才有该节点。num属性表示返回多少个消息id值，这个值与发送时多少条一对一短信对应。Item节点表示批量提交中每一条短信提交结果信息index属性表示发送中这一批次提交中第N条短信smsId属性表示发送中这一批次提交中第index条短信返回的消息id值，该值若发送自定义则返回发送时定义值，若发送为空则系统生成唯一值。result属性表示发送中这一批次提交中第index条短信发送结果值，该结果值解释请参考公共错误代码定义。失败返回结果样例：1成功返回结果样例：02.1.3. 短信接收功能：短信接收地址： 2/getSmsMo.action备注：建议采用post方法提交请求。已被取出的上行信息下次不会再重复提取，若调用接口返回上行记录数不为0，则取完可继续提取。一旦返回结果上行记录为0，则30秒后再发送上行信息提取请求，否则连续出现多次请求返回结果为0时系统将会锁定帐户。被锁帐户5分钟后自动解锁。请求参数定义如下： 参数名称描述字段值enterpriseID企业ID由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义Mo上行节点，若Result值为0即成功时，才有该节点。该节点为上行信息节点。Mo节点num属于表示本次取出上行记录总数。例num=2表示有2个上行记录信息，即两个Item节点。Item上行记录节点信息,若Mo中num=0表示没上行，则没有Item子节点。id表示上行唯一标识值content 表示上行内容from_mobile表示发送手机号码to_port表示接收扩展端口,发送时subPort值rec_time收到上行时间失败返回结果样例：1成功返回结果样例：02.1.4. 查询状态报告功能：查询状态报告地址： 2/getSmsReport.action备注：建议采用post方法提交请求。已被取出的状态报告信息下次不会再重复提取，若调用接口返回状态报告记录数不为0，则取完可继续提取。一旦返回结果状态报告记录为0，则30秒后再发送状态报告提取请求，否则连续出现多次请求返回结果为0时系统将会锁定帐户。被锁帐户5分钟后自动解锁。请求参数定义如下： 参数名称描述字段值enterpriseID企业ID由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义Report状态报告节点，若Result值为0即成功时，才有该节点。Report节点num属于表示本次取出状态报告记录总数。例num=3表示有3个状态报告记录信息，即三个Item节点。Item状态报告记录节点信息,若Report中num=0表示没状态报告，则没有Item子节点。smsId 消息id,些值为提交结果返回smsId对应to_mobile 接收手机号，smsId与to_mobile唯一status状态0表示发送成功，2表示提交失败(网络或是审核不通过，或是移动网关异常提交返回应答失败)，3发送失败reportTime 状态报告返回时间desc 状态报告描述：失败描述详细失败原因失败返回结果样例：1成功返回结果样例：02.1.5. 查询余额功能：查询余额地址： 2/getSmsBalance.action备注：建议采用post方法提交请求。请求参数定义如下： 参数名称描述字段值enterpriseID企业ID由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义Balance余额，返回帐户可用短信条数。失败返回结果样例：1成功返回结果样例：02002.1.6. 查询关键字功能：查询关键字地址： 2/getSmsFiltrates.action备注：建议采用post方法提交请求。请求参数定义如下： 参数名称描述字段值enterpriseID企业ID由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.content检测内容String,不可以为空。内容采用utf-8编码返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义Filtrates内容包含关键字信息，多个关键字中间采用逗号分隔失败返回结果样例：1成功返回结果样例：0测试,汉奸,2.2. WebService接口wsdl地址：2/services/emsServices?wsdl2.2.1. 短信发送功能：发送短信接口名称： public String sendSMS(String enterpriseID,String loginName,String password,String smsId,String subPort,String content,String mobiles,String sendTime)接口参数详细描述： 参数名称描述字段值enterpriseID企业IDString,由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.smsId消息idString，可以为空。消息id是这个包唯一标识，若为空则系统随机分配一个唯一标识值。若不为空，由用户自己设置一个唯一标识值。该值做为应答及状态报告中的消息id一一对应。 subPort扩展端口String,可以为空。空表示不再扩展，若扩展必须是数字如：00，01，02若扩展输入00则手机收到端口号为：10657*00(备注：扩展必须此帐户配置通道支持)content短信内容String 不可以为空，内容采用utf-8编码mobiles接收手机号码String，不可以为空。支持移动，联通，电信混合提交;多个号码中间采用半角逗号分隔,每个包最大支持100个号码。例13000000000endTime定时发送时间String,可以为空。为空表示立即发送，定时时间格式为：yyyy-MM-dd HH:mm:ss返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义SmsId消息id,用于配对状态报告,每个包提交返回消息id唯一。若发送时设置消息id，则返回是设置消息id值。失败返回结果样例：1成功返回结果样例：0102012012002.2.2. 一对一批量发送功能：发送短信接口名称： public String batchSingleSendSMS(String enterpriseID,String loginName,String password,String batchSmsId,String subPort,String batchContent,String batchMobiles,String sendTime)接口参数详细描述： 参数名称描述字段值enterpriseID企业IDString,由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.batchSmsId消息id数组String，可以为空。消息id数组每一个号码即一条短信对应一个id值，该值唯一区分每一个短信。若为空则系统随机分配一批消息id值，与号码数组一一对应。若不为空，由用户自己设置一批消息id值，注意每一个消息id唯一。该值做为应答及状态报告中的消息id一一对应。 subPort扩展端口String,可以为空。空表示不再扩展，若扩展必须是数字如：00，01，02若扩展输入00则手机收到端口号为：10657*00(备注：扩展必须此帐户配置通道支持)batchContent短信内容数组String 不可以为空，内容采用utf-8编batchMobiles接收手机号码数组String，不可以为空。支持移动，联通，电信混合提交;每个包最大支持100个号码。sendTime定时发送时间String,可以为空。为空表示立即发送，定时时间格式为：yyyy-MM-dd HH:mm:ss备注：批量发送一对一时，batchSmsId,batchContent,batchMobiles三个参数当batchSmsId不为空时，这三个字符数组长度必须一致，否则返回错误代码13（批量一对一参数格式错误）。返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义SmsIdList消息id节点集合，只有Result值为0，即处理成功时才有该节点。num属性表示返回多少个消息id值，这个值与发送时多少条一对一短信对应。Item节点表示批量提交中每一条短信提交结果信息index属性表示发送中这一批次提交中第N条短信smsId属性表示发送中这一批次提交中第index条短信返回的消息id值，该值若发送自定义则返回发送时定义值，若发送为空则系统生成唯一值。result属性表示发送中这一批次提交中第index条短信发送结果值，该结果值解释请参考公共错误代码定义。失败返回结果样例：1成功返回结果样例：02.2.3. 短信接收功能：短信接收接口名称：public String getSmsMo(String enterpriseID,String loginName,String password)备注：已被取出的上行信息下次不会再重复提取，若调用接口返回上行记录数不为0，则取完可继续提取。一旦返回结果上行记录为0，则30秒后再发送上行信息提取请求，否则连续出现多次请求返回结果为0时系统将会锁定帐户。被锁帐户5分钟后自动解锁。接口参数详细描述： 参数名称描述字段值enterpriseID企业ID由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义Mo上行节点，若Result值为0即成功时，才有该节点。该节点为上行信息节点。Mo节点num属于表示本次取出上行记录总数。例num=2表示有2个上行记录信息，即两个Item节点。Item上行记录节点信息,若Mo中num=0表示没上行，则没有Item子节点。id表示上行唯一标识值content 表示上行内容from_mobile表示发送手机号码to_port表示接收扩展端口，发送时subPort值rec_time收到上行时间失败返回结果样例：1成功返回结果样例：0 2.2.4. 查询状态报告功能：查询状态报告接口名称：public String getSmsReport(String enterpriseID,String loginName,String password)备注：已被取出的状态报告信息下次不会再重复提取，若调用接口返回状态报告记录数不为0，则取完可继续提取。一旦返回结果状态报告记录为0，则30秒后再发送状态报告提取请求，否则连续出现多次请求返回结果为0时系统将会锁定帐户。被锁帐户5分钟后自动解锁。接口参数详细描述： 参数名称描述字段值enterpriseID企业ID由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义Report状态报告节点，若Result值为0即成功时，才有该节点。Report节点num属于表示本次取出状态报告记录总数。例num=3表示有3个状态报告记录信息，即三个Item节点。Item状态报告记录节点信息,若Report中num=0表示没状态报告，则没有Item子节点。smsId 消息id,些值为提交结果返回smsId对应to_mobile 接收手机号，smsId与to_mobile唯一status状态0表示发送成功，2表示提交失败(网络或是审核不通过，或是移动网关异常提交返回应答失败)，3发送失败reportTime 状态报告返回时间desc 状态报告描述：失败描述详细失败原因失败返回结果样例：1成功返回结果样例：02.2.5. 查询余额功能：查询余额接口名称：public String getSmsBalance(String enterpriseID,String loginName,String password)接口参数详细描述： 参数名称描述字段值enterpriseID企业ID由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义Balance余额，返回帐户可用短信条数。失败返回结果样例：1成功返回结果样例：02002.2.6. 查询关键字功能：查询关键字接口名称：public String getSmsFiltrates(String enterpriseID,String loginName,String password,String content)接口参数详细描述：参数名称描述字段值enterpriseID企业ID由系统开户设置,系统分配。不允许为空loginName登录名String，不允许为空。系统开户设置登录名 password登录密码String，不可以为空。密码采用32位小写MD5加密.content检测内容String,不可以为空。内容采用utf-8编码返回结果以xml形式返回，详细参数及示例如下：参数名称描述Response根节点Result提交返回结果状态，详细状态码详见附录：公共错误代码定义Filtrates内容包含关键字信息，多个关键字中间采用逗号分隔失败返回结果样例：1成功返回结果样例：0测试,汉奸,2.3. DB接口EMS DB接口目前支持3种数据库，分别为：oracle,sql server 2005,mysql三种。该接口功能强大，其主要功能特点如下：1、采用并行处理方式及压缩技术实现批量提交，速度产生量级的提升。2、支持长短信发送（最大支持2000字）、实时状态报告、子扩展、上行等功能。3、支持失败重发功能，对失败重发可自由控制重发次数4、支持余额监控，当没余额时自动停止发送等待充值完毕自动恢复正常发送。5、对余额、发送情况、系统所有线程全实现监控，有任何异常能做到实时报警提醒管理人员。6、支持号码及号段自定义路由功能。7、支持定时统计发送前一天发送报告，同时做数据备份。8、发送优先级，实现不同要求信息按指定级别发送。9、支持信息超时处理机制及发送时段控制，避免对用户产生骚扰。10、系统设计留有扩展保留字段，以便与客户业务系统对接提供无缝结合。11、采用缓存机制，提升系统处理能力。2.3.1. 配置说明系统采用java开发，jdk要求版本1.6或以上。数据库oracle支持所有版本系统，sql server2005及mysql 所有版本系列。Config目录为该系统配置文件目录，详细说明如下：1、Config/xml 目录为对应数据库版本emsconfig.xml文件，请选择合适数据库版本配置文件，然后改名为emsconfig.xml放到config目录下面。2、Lperties文件为日志配置文件一般默认配置即可，不需要做任何变动。3、emsconfig.xml 为整个系统配置核心文件，需要修改部分及说明如下：1oracle.jdbc.driver.OracleDriverjdbc:oracle:thin:数据库ip:1521:devdb数据库实例名emsdb数据库用户名emsdb数据库密码8815EMS_MT_TASKEMS_MT_MESSAGEEMS_MT_MESSAGE_HISTORYEMS_MO_M