平台接口说明

1、短信平台接口说明目录1普通短信发送31.1短信提交地址31.2参数定义31.3短信提交响应41.3.1格式说明41.3.2示例41.3.3响应状态值说明51.4注意事项61.5短信发送例子62变量短信发送62.1系统提交URL地址72.2参数定义72.3提交响应72.3.1提交成功72.3.2提交失败82.3.3响应状态值说明82.4示例83短信包发送93.1系统提交URL地址93.2参数定义93.3提交响应93.3.1提交成功93.3.2提交失败103.3.3响应状态值说明103.4示例104状态报告推送104.1参数定义114.2状态报告值114.3示例115短信接收125.1参数定义12

2、5.2示例126额度查询接口136.1接口地址136.2参数定义136.3提交响应136.4提交响应值136.5示例147附录14本文档主要定了短信平台对用户开放的主要接口和定义。1 普通短信发送用户通过HTTP的POST方式提交短信发送请求。短信发送接口，区分为短信单发和短信群发两个接口。1.1 短信提交地址短信提交分为单发和群发（账户是否具有单发和群发的功能需要管理员进行功能的开通）。单发只能提交单个手机号码，群发可以提交不超过50000个手机号码，每个号码用英文逗号间隔。区别单发和群发主要在于发送的接口URL地址入口不同。单发的URL地址为：http:/IP:PORT/msg/HttpS

3、endSM，群发的URL地址为：http:/IP:PORT/msg/HttpBatchSendSM。注：其中IP:PORT为服务部署的地址和端口。1.2 参数定义序号参数说明1account必填参数。用户账号2pswd必填参数。用户密码3mobile必填参数。合法的手机号码，号码间用英文逗号分隔4msg必填参数。短信内容，短信内容长度不能超过585个字符。使用URL方式编码为UTF-8格式。短信内容超过70个字符（企信通是60个字符）时，会被拆分成多条，然后以长短信的格式发送。5needstatus必填参数。是否需要状态报告，取值true或false，true，表明需要状态报告；false不需

4、要状态报告6product可选参数。用户订购的产品id，不填写（针对老用户）系统采用用户的默认产品，用户订购多个产品时必填，否则会发生计费错误。7extno可选参数，扩展码，用户定义扩展码，3位1.3 短信提交响应用户短信通过http请求提交到服务器后，服务器返回响应码，响应码的格式如下：resptime,respstatusmsgid1.3.1 格式说明短信提交响应分为两行，第一行为响应时间和状态，第二行为服务器给出提交msgid。无论发送的号码是多少，一个发送请求只返回一个msgid，如果响应的状态不是“0”，则没有msgid即第二行数据。（每行以换行符(0x0a,即n)分割）1.3.2

5、示例Ø 提交成功20110725160412,01234567890100响应时间为20110725160412，响应状态为0 表明那个成功提交到服务器；1234567890100为返回的msgid，这个工状态报告匹配时使用。20110725160412,101Ø 提交失败Ø本示例表明用户提交失败，返回错误码为101，服务器端并未返回msgid。1.3.3 响应状态值说明代码说明0提交成功101无此用户102密码错103提交过快（提交速度超过流速限制）104系统忙（因平台侧原因，暂时无法处理提交的短信）105敏感短信（短信内容包含敏感词）106消息长度错（>

6、536或<=0）107包含错误的手机号码108手机号码个数错（群发>50000或<=0;单发>200或<=0）109无发送额度（该用户可用短信数已使用完）110不在发送时间内111超出该账户当月发送额度限制112无此产品，用户没有订购该产品113extno格式错（非数字或者长度不对）115自动审核驳回116签名不合法，未带签名（用户必须带签名的前提下）117IP地址认证错,请求调用的IP地址不是系统登记的IP地址118用户没有相应的发送权限119用户已过期1.4 注意事项用户群发短信如果有审核的限制，则客户的短信必须经过管理人员的审核，审核通过后才能被提交到行业网

7、关进行短信实际发送。用户群发短信必须满足手机号码最低个数的限制，低于系统设定的群发最小手机号码数，则该提交请求会被拒绝，响应码为108。1.5 短信发送例子Ø 短信单发40/msg/HttpSendSM?account=111111&pswd=123456&mobile13800138000&msg=test&needstatus=true&product=99999Ø 短信群发40/msg/HttpBatchSendSM?accou

8、nt=test01&pswd=123456&mobile13800138000&msg=test&needstatus=true&product=274463133短信单发和群发的url入口地址有区别，并且其中的IP地址192.l68.168.168需要根据系统部署的实际地址填写。2 变量短信发送用户通过HTTP的POST方式提交短信发送请求。2.1 系统提交URL地址http:/IP:PORT/msg/HttpVarSM2.2 参数定义序号参数说明1account用户账号2pswd用户密码3msg短信模板。其中的变量用“$va

9、r”来替代。例如：“$var,你好！，请你于$var日参加活动”，该短信中具有两个变量参数。编码为UTF-8格式。4params变量短信的参数组。单次提交参数组的数目不能超过1000个。编码为UTF-8格式每一组参数之间用英文“；”间隔每一组参数内部用英文“，”间隔，其中第一个参数为手机号码，第二个参数为模板中第一个变量，第三个参数为模板中第二个变量，以此类推。例如李先生,2013-01-01王先生，2013-01-15表明提交了两个变量组，其中手机号码分别为13500210000。模板变量分别为：李先生，2013-

10、01-01和王先生，2013-01-15格式不符的参数，系统自动过滤掉。5needstatus是否需要状态报告，取值true或false，true，表明需要状态报告；false不需要状态报告6product用户订购的产品id，不填写（针对老用户）系统采用用户的默认产品。7extno可选参数，扩展码，用户定义扩展码，3位2.3 提交响应2.3.1 提交成功20110725160412,0,10,11234567890100响应时间为20110725160412，响应状态为0 表明那个成功提交到服务器，参数组个数为10表明提交参数params中格式正确的条数为10条, 发送包失败个数为1表明提交参

11、数msg中格式错误的条数为1条；1234567890100为返回的msgid，这个供状态报告匹配时使用。2.3.2 提交失败20110725160412,101本示例表明用户提交失败，返回错误码为101，服务器端并未返回msgid。2.3.3 响应状态值说明响应的值在1.2.3的基础上增加：代码说明114可用参数组个数错误（小于最小设定值或者大于1000）2.4 示例68/msg/HttpVarSM?account=111111&pswd=123456&msg=$var,你好！，请你于$var日参加活动&params=1380021

12、0000,李先生,2013-01-01王先生，2013-01-15&needstatus=true&product=999993 短信包发送用户通过HTTP的POST方式提交短信发送请求。3.1 系统提交URL地址http:/IP:PORT/msg/HttpPkgSM3.2 参数定义序号参数说明1account用户账号2pswd用户密码3msg发送包内容，格式为：mobile|content ,内容编码为utf-8格式。45msg第n个短信号码及内容，n<=10006needstatus是否需要状态报告，取值true或false，true，表明需

13、要状态报告；false不需要状态报告7product用户订购的产品id，不填写（针对老用户）系统采用用户的默认产品。8extno可选参数，扩展码，用户定义扩展码，3位3.3 提交响应3.3.1 提交成功20110725160412,0,10,11234567890100响应时间为20110725160412，响应状态为0 表明那个成功提交到服务器，发送包成功个数为10表明提交参数msg中格式正确的条数为10条, 发送包失败个数为1表明提交参数msg中格式错误的条数为1条；1234567890100为返回的msgid，这个供状态报告匹配时使用。3.3.2 提交失败20110725160412,1

14、01本示例表明用户提交失败，返回错误码为101，服务器端并未返回msgid。3.3.3 响应状态值说明响应的值在1.2.3的基础上增加：代码说明114可用参数组个数错误（小于最小该用户群发设定值或者大于1000）3.4 示例68/msg/HttpPkgSM?account=111111&pswd=123456&msg测试短信1&msg测试短信2&msg测试短信3&needstatus=true&product=99999&e

15、xtno=1234 状态报告推送如果管理员设置用户账户需要状态报告，并且也配置了账户的状态报告接收地址，则用户可以接收到其发送短信的状态报告。用户侧启动一个HTTP服务用于接收状态报告。4.1 参数定义序号参数说明1receiver接收状态报告验证的用户名（不是账户名），是按照用户要求配置的名称，可以为空2pswd接收状态报告验证的密码，可以为空3msgid提交短信时平台返回的msgid，参见1.24reportTime格式YYMMDDhhmm，其中YY=年份的最后两位（00-99），MM=月份（01-12），DD=日（01-31），hh=小时（00-23），mm=分钟（00-59）5mobi

16、le单一的手机号码6status状态报告数值4.2 状态报告值状态报告的值即，status后面的数据，如下状态值(字符串)说明DELIVRD短消息转发成功EXPIRED短消息超过有效期UNDELIV短消息是不可达的UNKNOWN未知短消息状态REJECTD短消息被短信中心拒绝DTBLACK目的号码是黑名单号码ERR:104系统忙REJECT审核驳回其他网关内部状态4.3 示例http:/pushUrl?receiver=admin&pswd=12345&msgid=12345&reportTime=1012241002&mobileam

17、p;status=DELIVRD其中，pushUrl为用户启动的服务地址。5 短信接收5.1 参数定义序号参数说明1receiver接收信息验证的用户名（不是账户名），是按照用户要求配置的名称，可以为空2pswd接收信息服务需验证的密码，可以为空3moTime格式YYMMDDhhmm，其中YY=年份的最后两位（00-99），MM=月份（01-12），DD=日（01-31），hh=小时（00-23），mm=分钟（00-59）4mobile单一的手机号码5msgMO短信内容，文字内容使用UTF-8编码6destcode用户上行的目的号码7isems是否为长短信的一部分，1:是，0，不是。不带该参数

18、，默认为普通短信8emsheadIsems为1时，本参数以ASCII码形式显示长短信的头信息。用“,”隔开，分为三个部分，第一部分标识该条长短信的ID（该ID为短信中心生成）；第二部分，表明该长短信的总条数（pk_total）；第三部分，该条短信为该长短信的第几条(pk_number)。例如：234,4,1，该短信的ID为234,该长短信的总长度为4条，1，当前为第一条。5.2 示例普通短信：http:/pushMoUrl?receiver=admin&pswd=12345&moTime=1208212205&mobileamp;destcode=1065751600001&msg=hello&destcode=10657109012345EMS短信：http:/pushMoUrl?receiver=admin&pswd=12345&moTime=1208212205&mobileamp;destcode=1065751600001&msg=hello&destcode=10657109012345&isems=1&emshead=255,5,5其中，pushUrl为用户启动的服务地址。6 额度查询接口6.1 接口地址http:/I