大汉三通短信云接口手册V1.5.5

《大汉三通短信云接口手册V1.5.5》由会员分享，可在线阅读，更多相关《大汉三通短信云接口手册V1.5.5（22页珍藏版）》请在装配图网上搜索。

1、大汉三通短信云接口手册大汉三通短信云接口手册产品名称大汉三通短信云接口手册版本编号SMSC-20160426发布者上海大汉三通数据通信有限公司发布日期2016-04-26最后修改日期2016-05-30目录1、引言51.1.目的51.2.名词解释52、系统结构53、快速开发代码实例63.1.Java开发63.1.1.短信http接口（Json格式）64、短信接口64.1.http接口（json格式）64.1.1.短信下发64.1.2.批量短信下发84.1.3.短信状态报告104.1.4.获取回复短信114.1.5.查询余额124.1.6.检测黑名单134.1.7.检测敏感词145、短信错误码1

2、55.1.提交响应错误码155.2.状态报告错误码166、常见问题汇总177、动态短信验证码安全防护方案198、技术支持20保密本文件及其内容为上海大汉三通通信股份有限公司保密资料。本文件及其内容永远属于上海大汉三通通信股份有限公司拥有财产，在无上海大汉三通通信股份有限公司采用书面形式表示同意外，本文件a. 不可以用于其他非原指定用途；b. 不可以向第三方披露；c. 不可采用任何形式进行复制和传播，包括但不限于传真、纸张邮件和电子邮件。文档修改历史版本修改人日期描述1.5.1窦凤立2016-04-26改版1.5.4Aaron2016-05-23新增批量下发短信接口1、 引言1.1. 目的该接口

3、手册编写目的在于描述短信云CTC-OSS（以下简称CTC- OSS）具体的接口协议，供设计和开发人员在开发过程中参考，也使用户对该平台的短信上、下行流程有一个全面的了解。1.2. 名词解释缩略语英文全名中文全名CTC- OSS大汉三通短信云HTTPHyper Text Transfer Protocol超文本传输协议SMSShort Messaging Service短消息服务MO（上行短信）Message Original手机用户回复的短消息MT（下行短信）Message Terminal手机用户收到的短消息report（状态报告）Report运营商下发给手机用户的结果2、 系统结构从上图可

4、以看出，企业用户通过Internet网络接入大汉短信云，大汉短信云再连接到各运营商，为手机用户提供短、彩信息服务。企业用户与大汉短信云之间采用本文中定义的接口进行通信。3、 快速开发代码实例3.1. Java开发3.1.1. 短信http接口（Json格式） 目录路径：javasms_httpjson 开发请参照：javasms_httpjsonreadme.txt4、 短信接口4.1. http接口（json格式）注：终端客户的接入方式设置为http接入时才能使用此接口。该接口数据输入输出均采用json格式封装的字符串，编码（对整个请求的字符串编码）统一为UTF-8，采用post方式提交请求

5、。4.1.1. 短信下发访问地址：备用地址：提交方式：只支持POST名称Submit功能发送一条或者多条内容相同的短信输入说明参数值说明：以下json内容为提交请求数据格式：account:8528,password:e717ebfd5271ea4a98bd38653c01113d,msgid:2c92825934837c4d0134837dcba00150,phones:15711666132,content:您好，您的手机验证码为：430237。,sign:【8528】,subcode:8528,sendtime:201405051230,msgmode:0字段说明account：用户账号

6、；password：账号密码，需采用MD5加密(32位小写)；msgid：该批短信编号(32位UUID)，需保证唯一，选填；phones：接收手机号码，多个手机号码用英文逗号分隔，最多500个，必填；content：短信内容，最多350个汉字，必填,内容中不要出现【】这两种方括号，该字符为签名专用；sign：短信签名，该签名需要提前报备，生效后方可使用，不可修改，必填，示例如：【大汉三通】；subcode：短信签名对应子码(大汉三通提供)+自定义扩展子码(选填)，必须是数字，选填，未填使用签名对应子码；sendtime：定时发送时间，格式yyyyMMddHHmm，为空或早于当前时间则立即发送；

7、输出说明该响应为提交响应，发送到手机是否成功请获取状态报告确认响应数据格式:msgid:f02adaaa99c54ea58d626aac2f4ddfa8,result:0,desc:提交成功,failPhones:12935353535,110,130123123字段说明msgid：该批短信编号；result：该批短信提交结果；说明请参照：5.1.提交响应错误码；desc:状态描述；failPhones:如果提交的号码中含有错误（格式）号码将在此显示。4.1.2. 批量短信下发访问地址：备用地址：提交方式：只支持POST名称Submit功能批量发送不同内容短信输入说明参数值说明：以下json内

8、容为提交请求数据格式：account:dh8528,password:bb43a2c4081bec02fca7b72f38e63021,data:msgid:93786e387cf6462b9b60a36f8e7f1b27,phones:11111111,15711666133,1738786465,44554545,content:您好！你有一个快递,请注意查收。,sign:【客户签名】,subcode:8528,sendtime:,msgid:93786e387cf6462b9b60a36f8e7f1b27,phones:15711616131,content:您的订单今日送达，谢谢,si

9、gn:【客户签名】,subcode:8527,sendtime:字段说明account：用户账号；password：账号密码，需采用MD5加密(32位小写)；msgid：该批短信编号(32位UUID)，需保证唯一，选填；phones：接收手机号码，多个手机号码用英文逗号分隔，最多500个，必填；content：短信内容，最多350个汉字，必填,内容中不要出现【】这两种方括号，该字符为签名专用；sign：短信签名，该签名需要提前报备，生效后方可使用，不可修改，必填，示例如：【大汉三通】；subcode：短信签名对应子码(大汉三通提供)+自定义扩展子码(选填)，必须是数字，选填，未填使用签名对应子

10、码；sendtime：定时发送时间，格式yyyyMMddHHmm，为空或早于当前时间则立即发送；输出说明该响应为提交响应，发送到手机是否成功请获取状态报告确认响应数据格式:result:0,desc:提交成功,data:msgid:93786e387cf6462b9b60a36f8e7f1b27,status:4,desc:错误号码/限制运营商号码,failPhones:44554545,1738786465,11111111字段说明result：该数据包短信提交结果；说明请参照：5.1.提交响应错误码；desc:状态描述；status:每一批失败短信的错误码；说明请参照：5.1.提交响应错误

11、码；msgid：每一批短信编号；failPhones:如果提交的号码中含有错误（格式）号码将在此显示。4.1.3. 短信状态报告访问地址：提交方式：必须POST名称report功能获取状态报告，请求无数据返回，建议客户端休眠30秒再进行请求，每次最多取50条状态报告。输入说明参数值说明：以下json内容为提交请求数据格式：account:8528,password:e717ebfd5271ea4a98bd38653c01113d,msgid:2c92825934837c4d0134837dcba00150,phone:15711666XXX字段说明account：用户账号；password：账

12、号密码，需采用MD5加密(32位小写)；msgid：下行短信编号，选填；phone：接收下行手机号码，选填。输出说明响应数据格式:result:0,desc:成功,reports:msgid:2c92825934837c4d0134837dcba00150,phone:13534698345,status:0,desc:成功,wgcode:DELIVRD,time:2015-03-17 16:32:20,smsCount:1,smsIndex:1字段说明result：接口调用结果，说明请参照：5.1.提交响应错误码；当result为0时reports字段将出现0到1次，否则reports字段不

13、出现；msgid：短信编号；phone：下行手机号码；status：短信发送结果：0成功；1接口处理失败；2运营商网关失败；desc：当status为1时，以desc的错误码为准。说明请参照：5.2.状态报告错误码；wgcode：当status为2时，表示运营商网关返回的原始值；time：状态报告接收时间格式为yyyy-MM-ddHH:mm:ss。smsCount：长短信条数。smsIndex：长短信第几条标示。4.1.4. 获取回复短信访问地址：提交方式：必须POST名称deliver功能获取回复短信，请求无数据返回，建议客户端休眠30秒再进行请求，每次最多取150条上行回复。输入说明参数值

14、说明：以下json内容为提交请求数据格式：account:8528,password:e717ebfd5271ea4a98bd38653c01113d字段说明account：用户账号；password：账号密码，需采用MD5加密(32位小写)。输出说明响应数据格式：result:0,desc:成功,delivers:phone:15711666132,content:短信内容，subcode:4210delivertime:2015-03-11 11:00:00字段说明result：接口调用结果，说明请参照：5.1.提交响应错误码；当result为0时delivers字段将出现0到1次，否则d

15、elivers字段不出现；phone：上行手机号码；content：上行短信内容；subcode：子号码；delivertime：上行接收时间，格式yyyy-MM-ddHH:mm:ss。4.1.5. 查询余额访问地址：提交方式：必须POST名称balance功能获取短信余额输入说明参数值说明：以下json内容为提交请求数据格式：account:8528,password:e717ebfd5271ea4a98bd38653c01113d字段说明account：用户账号；password：账号密码，需采用MD5加密(32位小写)。输出说明返回的结果json格式如下：响应数据格式:result:0,

16、desc:成功,smsBalance: amount:9999999973,number:9999999973,freeze:16.0字段说明result：接口调用结果，说明请参照：5.1.提交响应错误码；如果result为0时smsBalance标签对将出现1次，否则smsBalance标签不出现；amount：剩余金额，保留3位小数，单位：元；number：剩余短信条数；freeze：冻结金额，保留3位小数，单位：元。4.1.6. 检测黑名单访问地址：提交方式：必须POST名称checkBlacklist功能检测黑名单输入说明参数值说明：以下json内容为提交请求数据格式：account:

17、8528,password:e717ebfd5271ea4a98bd38653c01113d,phones:15711666132字段说明account：用户账号；password：账号密码，需采用MD5加密(32位小写)；phones：需要检测的手机号码，多个号码之间用英文逗号分隔。输出说明响应数据格式:result:0,desc:提交成功,blacklist:15711666132字段说明result：接口调用结果，说明请参照：5.1.提交响应错误码；desc:状态描述；blacklist：黑名单号码，多个黑名单手机号之间用英文逗号分隔。4.1.7. 检测敏感词访问地址：提交方式：必须PO

18、ST名称checkKeyWord功能检测敏感词输入说明参数说明：以下json内容为提交请求数据格式：account:8528,password:e717ebfd5271ea4a98bd38653c01113d,content:低价处理二手车字段说明account：用户账号；password：账号密码，需采用MD5加密(32位小写)；content：要检测敏感词的内容。输出说明响应数据格式：result:0,desc:提交成功,keywords:处理,二手字段说明result：接口调用结果，说明请参照：5.1.提交响应错误码；keywords：敏感词信息，多个之间用英文逗号分隔。5、 短信错误码

19、5.1. 提交响应错误码错误码描述0提交成功1账号无效2密码错误3msgid太长，不得超过32位5手机号码个数超过最大限制(500个)6短信内容超过最大限制(350字)7扩展子号码无效8定时时间格式错误14手机号码为空19用户被禁发或禁用20ip鉴权失败21短信内容为空22数据包大小不匹配98系统正忙99消息格式错误5.2. 状态报告错误码错误码描述4手机号码无效5签名不合法6短信内容超过最大限制9请求来源地址无效10内容包含敏感词11余额不足12购买产品或订购还未生效或产品已暂停使用13账号被禁用或禁发14不支持该运营商16发送号码数没有达到该产品的最小发送数19黑名单号码20该模板ID已被

20、禁用21非法模板ID22不支持的MSGFMT23子号码无效24内容为空25号码为空26单个号码相同内容限制27单个号码次数限制28账号被拦截，不允许发送96处理失败97接入方式错误98系统繁忙99消息格式错误6、 常见问题汇总1. 提交短信返回“系统繁忙”。请联系客服人员。2. 提示用户名、密码错误。A、检查账号是否正确、密码是否为32位md5小写加密；B、接口地址是否正确。3. 提交短信返回“内容不合法”。下发短信内容包含敏感词内容，修改短信内容重新发送。如不清楚哪部分为敏感词内容，可登录平台发送页面进行查询，或调用检查敏感词接口。4. 提交短信失败，返回“签名不合法”。sign:【大汉三通

21、】标签内容为“大汉三通”，如返回“签名不合法”，请检查该标签内容是否由“【】”括起，再检查该“【大汉三通】”是否已经在短信云报备成功。5. 获取状态报告和上行时经常出现“请求太快”。状态报告和上行的获取机制为：当获取上行和状态报告有数据时，可不休眠继续获取；无数据时，休眠30秒。6. 定时下发短信时，短信立即下发。定时时间早于服务器当前时间，请检查时间设置。7. 发送成功但没有收到短信首先需要确认接口中是返回response成功还是report成功，在确认我们平台显示是发送成功的前提下，短信发送成功是网关返回状态，手机没有收到短信原因有可能被手机安全软件拦截，拦截主要是根据内容和黑白名单进行拦

22、截。被拦截的短信是有状态返回，返回状态是成功。包括类似：“你好”或“测试“均会被拦截。以360手机卫士为例，拦截一般可以通过以下方式处理：1.打开360安全卫士-打开骚扰拦截-短信拦截-选择被拦截的短信-恢复回话。2.将此号码加入白名单。8. 手机短信状态说明短信从企业系统到手机终端用户流转图如下：提交成功（response成功）提交到运营商网关成功; 提交失败（response失败）提交到运营商网关失败; 发送成功（状态报告成功）短信的状态报告显示终端接收成功; 发送失败（状态报告失败）短信的状态报告显示终端接收失败; 短信一般在48小时有效,短信的状态报告在48小时内都可能回来。9. 账号

23、IP绑定每个接口账号需要绑定固定IP，最多绑定5个IP以内（包括5个），客户不能自己操作，需商务提流程操作，如果IP未绑定，服务器不做响应。客户端可以用“telnet 123.57.4.187 80”来检验IP是否有报备。（不是根据该手册开发不能使用此方法）（另外，如果返回错误码“20：IP鉴权失败”也是IP没有绑定，由于接口开发不是根据该最新手册导致）10. 提交相应为0，但描述不是提交成功提交响应result=0并不一定所有手机号码都提交成功，如果有非手机号及不支持的运营商号码，会在blacklist标签里返回。7、 动态短信验证码安全防护方案验证码短信属于移动集团非常优质的短信应用，但近

24、期接移动集团反馈：部分用户投诉连续收到莫名验证码短信，而用户本身并未在该相关网站获取验证码，影响用户正常的工作、生活，从而产生大量投诉，同时对客户的品牌形象、经济投入也造成非常大的影响。 经分析该问题是由一种互联网恶意攻击方法-“短信轰炸机”形成，该攻击方式循环利用不同业务中的注册逻辑向任意非注册的手机号码发送短信动态验证码（如用户注册、好友邀请、密码找回等等），甚至可向多个手机用户同时连续发送大量验证码短信，严重影响用户的正常使用，造成不良影响与大量投诉。由于投诉量与端口关停、处罚等紧密相关，相关行为也会对客户的正常业务造成严重影响及品牌形象的损失。动态短信验证码安全防护方案是针对动态短信验

25、证码功能的安全实施方法与要求，适用于具备动态短信验证码功能的业务与系统。请相关客户对验证码类信息下发机制进行优化，主要如下（详细方案请参见附件：动态短信验证码安全防护方案）：序号措施描述针对性解决的问题备注1使用安全图片验证码防止通过自动化工具进行攻击请求图片校验码一定在要在点击获取短信验证码之前，从而起到校验作用，且每次在服务端动态变化2单IP的请求次数限定防止攻击者对服务器进行大量无效请求（在图片验证码未破解的情况下，自动化工具形成错误请求），增加服务器负担根据业务情况设置ip限制次数3单用户动态短信请求间隔时长限制防止对单个用户形成手工频繁攻击；防止图片验证码失效后对用户形成大量攻击。进

26、一步保障用户体验每次点击短信验证码，倒计时的时间戳在60秒以上，即当单个用户请求发送一次动态短信之后，服务器端锁定60秒（以上）后，才能进行第二次动态短信请求。4单用户获取动态验证码次数限制防止因图片验证码被破解，用户频繁收到莫名验证码短信一般单个用户请求短信验证码次数限制：一小时不超过3条，24小时不超过5条。此限制只针对获取短信验证码模块生效，客户其他业务（订单通知、支付确认等）可根据实际情况选择是否限制8、 技术支持如果您在测试、使用过程中遇到了问题，请发送邮件到：E-Mail: 8372注意：在发送邮件时一定尽量提供您的运行环境，包括JDK版本，Web容器名称、版本，您的配置信息，以及系统控制台中打印出的信息。这样我们才能比较快的定位到问题，同时也可以节约您的测试时间。上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第22页共22页版权所有(C) 2003-2033网址：全国热线：400-820-8121