短信平台接口说明.doc

短信平台接口说明Version 3.6目录1普通短信发送41.1短信提交地址41.2参数定义41.3短信提交响应51.3.1格式说明51.3.2示例51.3.3响应状态值说明61.4注意事项61.5短信发送例子72变量短信发送72.1系统提交URL地址72.2参数定义72.3提交响应82.3.1提交成功82.3.2提交失败92.3.3响应状态值说明92.4示例93短信包发送93.1系统提交URL地址93.2参数定义103.3提交响应103.3.1提交成功103.3.2提交失败113.3.3响应状态值说明113.4示例114状态报告推送114.1参数定义124.2状态报告值124.3示例125短信接收135.1参数定义135.2示例136额度查询接口136.1接口地址136.2参数定义136.3提交响应146.4提交响应值146.5示例147附录14版本修订历史项目日期修订内容备注12012-09-27修订章节结构，整理章节逻辑22012-11-25增加提交短信的参数product的定义及返回值的增加。1.1及1.2.3和1.432013-01-10增加扩展码1.142013-01-10增加变量短信提交调整章节结构，增加调整后的章节252013-01-315.1，增加MO目的号码62013-01-31增加3，包发送方式72013-03-03增加查询额度的接口调整章节结构，增加调整后章节6，原来章节6及其后依次增加本文档主要定了短信平台对用户开放的主要接口和定义。1 普通短信发送用户通过HTTP的POST方式提交短信发送请求。短信发送接口，区分为短信单发和短信群发两个接口。1.1 短信提交地址短信提交分为单发和群发（账户是否具有单发和群发的功能需要管理员进行功能的开通）。单发只能提交单个手机号码，群发可以提交不超过50000个手机号码，每个号码用英文逗号间隔。区别单发和群发主要在于发送的接口URL地址入口不同。单发的URL地址为：http:/IP:PORT/msg/HttpSendSM，群发的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不需要状态报告6product可选参数。用户订购的产品id，不填写（针对老用户）系统采用用户的默认产品，用户订购多个产品时必填，否则会发生计费错误。7extno可选参数，扩展码，用户定义扩展码，3位1.3 短信提交响应用户短信通过http请求提交到服务器后，服务器返回响应码，响应码的格式如下：resptime,respstatusmsgid1.3.1 格式说明短信提交响应分为两行，第一行为响应时间和状态，第二行为服务器给出提交msgid。无论发送的号码是多少，一个发送请求只返回一个msgid，如果响应的状态不是“0”，则没有msgid即第二行数据。（每行以换行符(0x0a,即n)分割）1.3.2 示例 提交成功20110725160412,01234567890100响应时间为20110725160412，响应状态为0 表明那个成功提交到服务器；1234567890100为返回的msgid，这个工状态报告匹配时使用。20110725160412,101 提交失败本示例表明用户提交失败，返回错误码为101，服务器端并未返回msgid。1.3.3 响应状态值说明代码说明0提交成功101无此用户102密码错103提交过快（提交速度超过流速限制）104系统忙（因平台侧原因，暂时无法处理提交的短信）105敏感短信（短信内容包含敏感词）106消息长度错（536或50000或200或=0）109无发送额度（该用户可用短信数已使用完）110不在发送时间内111超出该账户当月发送额度限制112无此产品，用户没有订购该产品113extno格式错（非数字或者长度不对）1.4 注意事项用户群发短信如果有审核的限制，则客户的短信必须经过管理人员的审核，审核通过后才能被提交到行业网关进行短信实际发送。用户群发短信必须满足手机号码最低个数的限制，低于系统设定的群发最小手机号码数，则该提交请求会被拒绝，响应码为108。1.5 短信发送例子 短信单发68/msg/HttpSendSM?account=111111&pswd=123456&mobile13800138000&msg=test&needstatus=true&product=99999 短信群发68/msg/HttpBatchSendSM?account=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短信模板。其中的变量用“$var”来替代。例如：“$var,你好！，请你于$var日参加活动”，该短信中具有两个变量参数。编码为UTF-8格式。4params变量短信的参数组。单次提交参数组的数目不能超过1000个。编码为UTF-8格式每一组参数之间用英文“；”间隔每一组参数内部用英文“，”间隔，其中第一个参数为手机号码，第二个参数为模板中第一个变量，第三个参数为模板中第二个变量，以此类推。例如李先生,2013-01-01王先生，2013-01-15表明提交了两个变量组，其中手机号码分别为13500210000。模板变量分别为：李先生，2013-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表明提交参数msg中格式错误的条数为1条；1234567890100为返回的msgid，这个供状态报告匹配时使用。2.3.2 提交失败20110725160412,101本示例表明用户提交失败，返回错误码为101，服务器端并未返回msgid。2.3.3 响应状态值说明响应的值在1.2.3的基础上增加：代码说明114可用参数组个数错误（小于最小设定值或者大于1000）2.4 示例http:/ 6/msg/HttpVarSM?account=111111&pswd=123456&msg=$var,你好！，请你于$var日参加活动¶ms李先生,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，表明需要状态报告；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,101本示例表明用户提交失败，返回错误码为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&extno=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）5mobile单一的手机号码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&mobilestatus=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用户上行的目的号码5.2 示例http:/pushMoUrl?receiver=admin&pswd=12345&moTime=1208212205&mobiledestcode=1065751600001&msg=hello其中，pushUrl为用户启动的服务地址。6 额度查询接口6.1 接口地址http:/IP:P