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

小程序1150 更新时间：2025-06-08 06:59:17

2023年7月31日发(作者：)

大汉三通短信云接口手册

产品名称

版本编号

发布者

发布日期

大汉三通短信云接口手册SMSC-20160426

上海大汉三通数据通信有限公司

2016-04-26

最后修改日期 2016-09-18

大汉三通短信云接口手册

1、引言 ............................................................................................................................... 5

1.1.

1.2.

目的 ..................................................................................................................5

名词解释 ...........................................................................................................5

2、系统结构 ........................................................................................................................ 5

3、快速开发代码实例 .......................................................................................................... 6

3.1. Java开发 ...........................................................................................................6

3.1.1. 短信http接口（Json格式）........................................................................6

4、短信接口 ........................................................................................................................ 6

4.1. http接口（json格式） .......................................................................................6

4.1.1.

4.1.2.

4.1.3.

4.1.4.

短信下发 ....................................................................................................6

批量短信下发 .............................................................................................8

短信状态报告 ........................................................................................... 10

获取回复短信 ........................................................................................... 11

5、短信错误码 ................................................................................................................... 13

5.1.

5.2.

提交响应错误码 .............................................................................................. 13

状态报告错误码 .............................................................................................. 14

6、常见问题汇总 ............................................................................................................... 15

7、动态短信验证码安全防护方案....................................................................................... 17

8、技术支持 ...................................................................................................................... 18

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第2页共18页

保密

本文件及其内容为上海大汉三通通信股份有限公司保密资料。本文件及其内容永远属于上海大汉三通通信股份有限公司拥有财产，在无上海大汉三通通信股份有限公司采用书面形式表示同意外，本文件

a. 不可以用于其他非原指定用途；

b. 不可以向第三方披露；

c.

不可采用任何形式进行复制和传播，包括但不限于传真、纸张邮件和电子邮件。

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第3页共18页

文档修改历史

版本

1.5.1

1.5.4

1.5.8

修改人

窦凤立

Aaron

窦凤立

日期

2016-04-26

2016-05-23

2016-09-18

描述

改版

新增批量下发短信接口

修改接口地址

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第4页共18页

1、引言

1.1. 目的

该接口手册编写目的在于描述短信云CTC-OSS（以下简称CTC- OSS）具体的接口协议，供设计和开发人员在开发过程中参考，也使用户对该平台的短信上、下行流程有一个全面的了解。

1.2. 名词解释

缩略语

CTC- OSS

HTTP

SMS

MO（上行短信）

MT（下行短信）

Hyper Text Transfer Protocol

Short Messaging Service

Message Original

Message Terminal

英文全名中文全名

大汉三通短信云

超文本传输协议

短消息服务

手机用户回复的短消息

手机用户收到的短消息

运营商下发给手机用户的结果 report（状态报告） Report

2、系统结构

企业用户手机用户运营商网关Internet网络企业用户手机用户大汉短信云运营商网关手机用户企业用户

从上图可以看出，企业用户通过Internet网络接入大汉短信云，大汉短信云再连接到各运营商，为手机用户提供短、彩信息服务。

企业用户与大汉短信云之间采用本文中定义的接口进行通信。

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第5页共18页

3、快速开发代码实例

3.1. Java开发

3.1.1. 短信http接口（Json格式）

 目录路径：javasms_httpjson

 开发请参照：javasms_

4、短信接口

4.1. http接口（json格式）

注：终端客户的接入方式设置为http接入时才能使用此接口。

该接口数据输入输出均采用json格式封装的字符串，编码（对整个请求的字符串编码）统一为UTF-8，采用post方式提交请求。

4.1.1. 短信下发

访问地址：/json/sms/Submit

提交方式：只支持POST

名称

功能发送一条或者多条内容相同的短信

参数值说明：

以下json内容为提交请求数据格式：

{"account":"8528",

输入说明

"password":"e717ebfd5271ea4a98bd38653c01113d",

"msgid":"2c92825934837c4d0134837dcba00150",

"phones":"157****6132","content":"您好，您的手机验证码为：430237。",

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第6页共18页

Submit 大汉三通短信云接口手册

"sign":"【8528】","subcode":"8528",

"sendtime":"2"

}

字段说明

account：用户账号；

password：账号密码，需采用MD5加密(32位小写)；

msgid：该批短信编号(32位UUID)，需保证唯一，选填；

phones：接收手机号码，多个手机号码用英文逗号分隔，最多500个，必填；

content：短信内容，最多350个汉字，必填,内容中不要出现【】[]这两种方括号，该字符为签名专用；

sign：短信签名，该签名需要提前报备，生效后方可使用，不可修改，必填

，示例如：【大汉三通】；

subcode：短信签名对应子码(大汉三通提供)+自定义扩展子码(选填)，必须是数字，选填，未填使用签名对应子码；

sendtime：定时发送时间，格式yyyyMMddHHmm，为空或早于当前时间则立即发送；

该响应为提交响应，发送到手机是否成功请获取状态报告确认

响应数据格式:

{"msgid":"f02adaaa99c54ea58d626aac2f4ddfa8",

"result":"0",

"desc":"提交成功",

"failPhones":",110,130123123"

输出说明

}

字段说明

msgid：该批短信编号；

result：该批短信提交结果；说明请参照：5.1.提交响应错误码；

desc:状态描述；

failPhones:如果提交的号码中含有错误（格式）号码将在此显示。

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第7页共18页

4.1.2. 批量短信下发

访问地址：/json/sms/BatchSubmit

提交方式：只支持POST

名称

功能

参数值说明：

以下json内容为提交请求数据格式：

{"account":"dh8528",

"password":"bb43a2c4081bec02fca7b72f38e63021",

"data":[{

"msgid":"93786e387cf6462b9b60a36f8e7f1b27",

"phones":"11111111,157****6133,1738786465,44554545","content":"您好！你有一个快递,请注意查收。",

"sign":"【客户签名】",

"subcode":"8528",

"sendtime":""

输入说明

},{

"msgid":"93786e387cf6462b9b60a36f8e7f1b27",

"phones":"157****6131","content":"您的订单今日送达，谢谢",

"sign":"【客户签名】",

"subcode":"8527",

"sendtime":""

}]

}

字段说明

account：用户账号；

password：账号密码，需采用MD5加密(32位小写)；

msgid：该批短信编号(32位UUID)，需保证唯一，必填；

phones：接收手机号码，多个手机号码用英文逗号分隔，最多500个，必填；

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第8页共18页

Submit

批量发送不同内容短信大汉三通短信云接口手册

content：短信内容，最多350个汉字，必填,内容中不要出现【】[]这两种方括号，该字符为签名专用；

sign：短信签名，该签名需要提前报备，生效后方可使用，不可修改，必填

，示例如：【大汉三通】；

subcode：短信签名对应子码(大汉三通提供)+自定义扩展子码(选填)，必须是数字，选填，未填使用签名对应子码；

sendtime：定时发送时间，格式yyyyMMddHHmm，为空或早于当前时间则立即发送；

该响应为提交响应，发送到手机是否成功请获取状态报告确认

响应数据格式:

{"result":"0",

"desc":"提交成功",

"data":[{

"msgid":"93786e387cf6462b9b60a36f8e7f1b27",

"status":"4",

输出说明

}

字段说明

result：该数据包短信提交结果；说明请参照：5.1.提交响应错误码；

desc:状态描述；

status:每一批失败短信的错误码；说明请参照：5.1.提交响应错误码；

msgid：每一批短信编号；

failPhones:如果提交的号码中含有错误（格式）号码将在此显示。

}]

"desc":"错误号码/限制运营商号码",

"failPhones":"44554545,1738786465,11111111"

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第9页共18页

4.1.3. 短信状态报告

访问地址：/json/sms/Report

提交方式：必须POST

名称

功能

report

获取状态报告，有数据时无需休眠；当请求无数据返回时，建议客户端休眠30秒再进行请求。每次最多取200条状态报告。

参数值说明：

以下json内容为提交请求数据格式：

{"account":"8528",

"password":"e717ebfd5271ea4a98bd38653c01113d",

输入说明

}

字段说明

account：用户账号；

password：账号密码，需采用MD5加密(32位小写)；

响应数据格式:

{"result":"0",

"desc":"成功",

"reports":[

{"msgid":"2c92825934837c4d0134837dcba00150",

"phone":"135****8345","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字段不出现；

msgid：短信编号；

phone：下行手机号码；

status：短信发送结果：

0——成功；1——接口处理失败；2——运营商网关失败；

desc：当status为1时，以desc的错误码为准。说明请参照：5.2.状态报告错误码；

wgcode：当status为2时，表示运营商网关返回的原始值；

time：状态报告接收时间格式为yyyy-MM-ddHH:mm:ss。

smsCount：长短信条数。

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第10页共18页

}] 大汉三通短信云接口手册

smsIndex：长短信第几条标示。

4.1.4. 获取回复短信

访问地址：/json/sms/Deliver

提交方式：必须POST

名称

功能

取150条上行回复。

参数值说明：

以下json内容为提交请求数据格式：

{"account":"8528",

"password":"e717ebfd5271ea4a98bd38653c01113d"

输入说明

}

字段说明

account：用户账号；

password：账号密码，需采用MD5加密(32位小写)。

响应数据格式：

{"result":"0",

"desc":"成功",

"delivers":[

{"phone":"157****6132","content":"短信内容"，

"subcode":"4210"

"delivertime":"2015-03-11 11:00:00"}]

输出说明

}

字段说明

result：接口调用结果，说明请参照：5.1.提交响应错误码；

当result为0时delivers字段将出现0到1次，否则delivers字段不出现；

phone：上行手机号码；

content：上行短信内容；

subcode：子号码；

delivertime：上行接收时间，格式yyyy-MM-ddHH:mm:ss。

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第11页共18页

deliver

获取回复短信，请求无数据返回，建议客户端休眠30秒再进行请求，每次最多大汉三通短信云接口手册

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第12页共18页

5、短信错误码

5.1. 提交响应错误码

错误码

0

1

2

3

6

7

8

14

19

20

21

22

98

99

提交成功

账号无效

密码错误

msgid太长，不得超过32位

短信内容超过最大限制

扩展子号码无效

定时时间格式错误

手机号码为空

用户被禁发或禁用

ip鉴权失败

短信内容为空

数据包大小不匹配

系统正忙

消息格式错误

描述

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第13页共18页

5.2. 状态报告错误码

错误码

4

5

6

9

10

11

12

13

14

16

19

20

21

22

23

24

25

26

27

28

96

97

98

99

手机号码无效

签名不合法

短信内容超过最大限制

请求来源地址无效

内容包含敏感词

余额不足

购买产品或订购还未生效或产品已暂停使用

账号被禁用或禁发

不支持该运营商

发送号码数没有达到该产品的最小发送数

黑名单号码

该模板ID已被禁用

非法模板ID

不支持的MSGFMT

子号码无效

内容为空

号码为空

单个号码相同内容限制

单个号码次数限制

账号被拦截，不允许发送

处理失败

接入方式错误

系统繁忙

消息格式错误

描述

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第14页共18页

6、常见问题汇总

1. 提交短信返回“系统繁忙”。

请联系客服人员。

2. 提示用户名、密码错误。

A、检查账号是否正确、密码是否为32位md5小写加密；

B、接口地址是否正确。

3. 提交短信返回“内容不合法”。

下发短信内容包含敏感词内容，修改短信内容重新发送。如不清楚哪部分为敏感词内容，可登录平台发送页面进行查询，或调用检查敏感词接口。

4. 提交短信失败，返回“签名不合法”。

"sign":"【大汉三通】"标签内容为“大汉三通”，如返回“签名不合法”，请检查该标签内容是否由“【】”括起，再检查该“【大汉三通】”是否已经在短信云报备成功。

5. 获取状态报告和上行时经常出现“请求太快”。

状态报告和上行的获取机制为：当获取上行和状态报告有数据时，可不休眠继续获取；无数据时，休眠30秒。

6. 定时下发短信时，短信立即下发。

定时时间早于服务器当前时间，请检查时间设置。

7. 发送成功但没有收到短信

首先需要确认接口中是返回response成功还是report成功，在确认我们平台显示是发送成功的前提下，短信发送成功是网关返回状态，手机没有收到短信原因有可能被手机安全软件拦截，拦截主要是根据内容和黑白名单进行拦截。被拦截的短信是有状态返回，返回状态是成功。包括类似：“你好”或“测试“均会被拦截。以360手机卫士为例，拦截一般可以通过以下方式处理：1.打开360安全卫士---》打开骚扰拦截---》短信拦截--->选择被拦截的短信----》恢复回话。2.将此号码加入白名单。

8. 手机短信状态说明

短信从企业系统到手机终端用户流转图如下：

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第15页共18页

提交成功（response成功）——提交到运营商网关成功; 提交失败（response失败）—提交到运营商网关失败; 发送成功（状态报告成功）—短信的状态报告显示终端接收成功; 发送失败（状态报告失败）——短信的状态报告显示终端接收失败; 短信一般在48小时有效,短信的状态报告在48小时内都可能回来。

9. 账号IP绑定

每个接口账号需要绑定固定IP，最多绑定5个IP以内（包括5个），客户不能自己操作，需商务提流程操作，如果IP未绑定，服务器不做响应。

客户端可以用“telnet 80”来检验IP是否有报备。（不是根据该手册开发不能使用此方法）

（另外，如果返回错误码“20：IP鉴权失败”也是IP没有绑定，由于接口开发不是根据该最新手册导致）

10. 提交相应为0，但描述不是提交成功

提交响应result=0并不一定所有手机号码都提交成功，如果有非手机号及不支持的运营商号码，会在blacklist标签里返回。

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第16页共18页

7、动态短信验证码安全防护方案

验证码短信属于移动集团非常优质的短信应用，但近期接移动集团反馈：部分用户投诉连续收到莫名验证码短信，而用户本身并未在该相关网站获取验证码，影响用户正常的工作、生活，从而产生大量投诉，同时对客户的品牌形象、经济投入也造成非常大的影响。

经分析该问题是由一种互联网恶意攻击方法--“短信轰炸机”形成，该攻击方式循环利用不同业务中的注册逻辑向任意非注册的手机号码发送短信动态验证码（如用户注册、好友邀请、密码找回等等），甚至可向多个手机用户同时连续发送大量验证码短信，严重影响用户的正常使用，造成不良影响与大量投诉。

由于投诉量与端口关停、处罚等紧密相关，相关行为也会对客户的正常业务造成严重影响及品牌形象的损失。《动态短信验证码安全防护方案》是针对动态短信验证码功能的安全实施方法与要求，适用于具备动态短信验证码功能的业务与系统。请相关客户对验证码类信息下发机制进行优化，主要如下（详细方案请参见附件：《动态短信验证码安全防护方案》）：

中国移动动态短信验证码安全防护方案.

序号

1

措施描述

使用安全图片验证码

针对性解决的问题

防止通过自动化工具进行攻击请求

备注

图片校验码一定在要在点击获取短信验证码之前，从而起到校验作用，且每次在服务端动态变化

2

单IP的请求次数限定

防止攻击者对服务器进行大量无根据业务情况设置ip限制次数

效请求（在图片验证码未破解的情况下，自动化工具形成错误请求），增加服务器负担

3

单用户动态短信防止对单个用户形成手工频繁攻每次点击短信验证码，倒计时的时请求间隔时长限击；

制

间戳在60秒以上，即当单个用户防止图片验证码失效后对用户形请求发送一次动态短信之后，服成大量攻击。

务器端锁定60秒（以上）后，才能进行第二次动态短信请求。

进一步保障用户体验

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第17页共18页

4

单用户获取动态防止因图片验证码被破解，用户一般单个用户请求短信验证码次数验证码次数限制频繁收到莫名验证码短信限制：一小时不超过3条，24小时不超过5条。

此限制只针对获取短信验证码模块生效，客户其他业务（订单通知、支付确认等）可根据实际情况选择是否限制

8、技术支持

如果您在测试、使用过程中遇到了问题，请发送邮件到：

E-Mail:****************注意：在发送邮件时一定尽量提供您的运行环境，包括JDK版本，Web容器名称、版本，您的配置信息，以及系统控制台中打印出的信息。

这样我们才能比较快的定位到问题，同时也可以节约您的测试时间。

上海大汉三通数据通信有限公司上海张江高科技园区浦东软件园20号楼5层第18页共18页