1、前言

为了明确服务应用层与终端用户数据交互稳定一致，以及适应不同的终端应用。此文档明确双方交互的协议、数据格式、数据结构、接口名称、参数类型、类型长度。

短信网关与ISP互为HTTP的服务器端和客户端，通过HTTP传递短信内容，分为下行(MT)短信与上行(MO)短信两种方式。

2.接口定义

2.1下行(MT)短信

当ISP系统通过短信网关向用户手机发短信（MT服务），ISP系统采用类似的方式向短信网关的CGI发短信。

1.下行短信接口说明：

接口URL	http://yxt.gausstel.com/GsmsHttp
请求方式	GET或者 POST
参数名称	类型	是否需要转码	是否必填	描 述
username	String	N(否)	Y(必填)	登录名
password	String	Y(是)	Y(必填)	ISP登陆密码(公司分配给ISP)
from	Number	N(否)	N(非必填)	为空
to	Number	Y(否)	Y(必填)	接收短信的手机号，支持多个(<=100)手机号码，中间以“,”分割。
content	String	Y(是)	Y(必填)	短信内容 必须进行GBK的URL转码
sign	String	Y(是)	N(非必填)	单独指定短信签名，不需要带上中括号 必须进行GBK的URL转码
expandPrefix	Number	N(否)	N(非必填)	用户下行短信自扩展端口，其该端口的使用需要相关机构的指定配置。（该字段单独最大长度为14位，但下行短信实际发送后会根据SP号进行相关的截取操作）
sendTime	String	N(否)	N(非必填)	此字段有值时，表明此短信为定时短信，其时间格式为：yyyy-MM-ddHH:mm:ss 注意：定时发送时间与网关服务器时间如相隔时间较短（1分钟内）则均作为普通及时短信立即发送
expandPar	String	N(否)	N(非必填)	定制化参数，指定5G短信模板中，指定别名变量的具体参数值，其内容为固定的按照JSONObject方式解析的JSON串，详细使用说明可参看3.5章节。由于该接口参数支持GET方式传输，故该字段所传的值强制要求必须URLDecoder的GBK转码

2.返回值：
例：OK:325689,3256810,3256811 表示短信发送成功 发送成功后返回所有短信ID。 ERROR:eUser 表示短信发送不成功，出错原因是因为用户名称有误

3.返回值说明：

参数	类型	描 述
OK	String	发送成功的短信的ID
ERROR	String	错误信息 举例： OK:325689 表示短信发送成功 发送成功的最后一条短信ID为325689； ERROR:eUser 表示短信发送不成功，出错原因是因为用户名称有误； ERROR:eDate 表示日期错误，出错原因是预发送时间格式不对； ERROR:eIllegalPhone 表示发送号码错误； ERROR:ePassword 表示密码错误； ERROR:eStop 表示用户已经停用； ERROR:eDenyDate 表示帐户过期； ERROR:eBalance 表示余额不足； ERROR:不明错误！表示不明错误，出错原因一般是SQL异常（内容过长或者机构ID填写英文字母等类似错误）； ERROR:eFrequent 表示请求频繁； ERROR:eContentLen 表示短信内容超长； ERROR:nContent 表示短信内容为空； ERROR:eContentWrong 表示短信模板拦截 ERROR:IPWrong 表示客户连接IP与报备IP不符 ERROR:eVoice  没有语音通道 ERROR:eVoiceVCode  没有语音验证码通道 ERROR:eContentVCode  验证码只能是10位以内的英文字母或是数字 ERROR:nFormatWrong 请求参数格式错误 ERROR:未知错误 表示未知错误。

4.示例：
HTTP请求示例1（普通短信）
HTTP应答示例
5.注意事项：
1、30秒之内如果账户登入错误次数超过5次，那么账户将会被锁定1分钟，1分钟后自动解锁。

2.2主动推送状态报告及上行发送信息（推荐使用）

推荐原因：量大的、对状态报告返回要求及时的客户，请使用主动推送的方式。
1.状态报告及上行发送信息推送接口说明
注意：由于是主动推送的方式，所以其ip和port的值为客户提供的接收信息的地址。同时，整个返回的结果集，是以字符串的方式，以UTF-8的字节编码的方式进行传输，注意解析状态报告和上行时，中文乱码的问题。

接口URL	有客户提供用于接收状态报告和上行的HTTP目的路径 例如：http://ip:port/ServerDemo/demo?dataType=XML&isZIP=true
请求方式	POST
参数	类型	是否必填	描 述
dataType	String	N	决定HTTP返回的内容是何种格式，目前支持XML和JSON两种格式。客户需要何种格式的返回内容，有此参数传值决定，默认为XML。只需要在提供的路径后加传此参数即可
isZIP	boolean	N	该参数决定其推送的内容是否需要进行gzip压缩的方式进行传输，为空的时候默认为不压缩,注意，此参数只在推送状态报告时生效

2.状态报告返回值示例
ok(注意：为小写的英文字母ok)

2.1.状态报告内容读取排版后如下：
XML格式
JSON格式
2.2状态报告返回值说明

参数	类型	描 述
当接收参数中httpVersion为1时
subid	Number	参数为空（暂时无用）
sendFlag	Number	参数标识该条状态报告是否成功:1与3代表成功，其它数字代表失败
reportTime	String	状态报告返回时间,格式: yyyy-MM-dd HH:mm:ss
userId	Number	该发送短信的客户ID
toMobile	Number	该短信状态报告涉及到的接收手机号
report	Number	运营商返回的状态报告代码
messageId	Number	该条状态报告所对应的下行短信的唯一ID号，用于匹配发送短信时返回的messageID值
linkContent	String	5G短信生成的短链
当接收参数中httpVersion为空时
sendFlag	Number	参数标识该条状态报告是否成功:7代表成功，其它数字代表失败
reportTime	String	状态报告返回时间,格式: yyyy-MM-dd HH:mm:ss
toMobile	String	该短信状态报告涉及到的接收手机号
report	String	运营商返回的状态报告代码
smsId	String	该条状态报告所对应的下行短信的唯一ID号，用于匹配发送短信时返回的messageID值
smsBatchId	String	下行提交短信时的批次号信息
linkContent	String	5G短信生成的短链

3.上行发送信息返回值示例：
3.1上行读取排版后如下：
XML格式 JSON格式
3.2上行内容返回值说明

参数	类型	描 述
当接收参数中httpVersion=1时
subid	Number	参数为空（暂时无用）
moFrom	Number	该条上行短信的源号码，一般是用户手机号
moTo	Number	该条上行短信的目标号码，一般是SP长号码
userId	Number	该上行短信涉及到的客户ID
moContent	String	该上行短信的内容
momsgId	Number	上行短信的唯一标示符
createTime	Number	该上行短信的接收时间
export	String	用户自扩展端口，定制化参数
当接收参数中httpVersion为空时
fromPhone	String	该条上行短信的源号码，一般是用户手机号
spcode	String	该条上行短信的目标号码，一般是SP长号码
moContent	String	该上行短信的内容
momsgId	Number	上行短信的唯一标示符
createTime	String	该上行短信的接收时间
export	String	用户自扩展端口，定制化参数

4.注意事项：
该接口存在新老客户兼容的问题，故出现了两种协议参数方式

2.3主动获取状态报告及上行（不推荐）

注意：量少的，对状态报告返回要求不及时的客户，可以使用获取的方式，但还是建议使用主动推送的。
1.状态报告及上行发送信息推送接口说明:

接口URL	http://yxt.gausstel.com/GeneralSMS/GSmsHttpReport?username=user&password=pass&itemNum=10&moMsgId=&dataType=XML
请求方式	GET
参数	类型	是否需要转码	是否必填	描 述
username	String	N	Y	ISP登陆名(公司分配给ISP)，如果为机构版，则应以“机构ID:登陆名”方式赋值
password	String	Y	Y	ISP登陆密码(公司分配给ISP)
itemNum	Number	N	N	每次收取的状态报告的数量,为空时默认为50,最大值不可超过100
msgType	Number	N	N	获取的信息类型，0 为状态报告 1为上行，默认为0
getType	Number	N	N	获取状态报告的方式，为0时则获取用户登陆时所属机构的下所有用户的状态报告信息或者上行信息，为1时则只获取登陆用户所属机构名下该登陆用户的状态报告信息或者上行信息,为空时默认为0.
moMsgId	Number	N	N	在查询上行短信时，如果传入上行短信ID那么将会获取大于等于该值的所有上行短信信息。
dataType	String	N	N	决定HTTP返回的内容是何种格式，目前支持XML和JSON两种格式。客户需要何种格式的返回内容，有此参数传值决定，默认为XML

2.状态报告返回值示例：
XML格式 JSON格式
3.状态报告返回值说明：

参数	类型	描 述
subid	Number	暂时无用
userId	Number	该发送短信的客户ID
toMobile	String	该短信状态报告涉及到的接收手机号
sendFlag	String	高斯通公司主动推送状态报告参数
messageId	Number	高斯通公司主动推送状态报告参数
report	String	状态报告的内容
reportTime	String	状态报告返回时间,格式:YYYY-MM-DD hh:mm:ss

4.用户上行返回值示例：
XML格式 JSON格式
5.用户上行返回值说明：

参数	类型	描 述
subid	Number	高斯通公司主动推送上行参数
userId	Number	该上行短信涉及到的客户ID
moFrom	Number	该条上行短信的源号码，一般是用户手机号
moTo	Number	该条上行短信的目标号码，一般是SP长号码
moContent	String	该上行短信的内容
momsgId	Number	上行短信的唯一标示符
createTime	String	该上行短信的接收时间

6.注意事项：
1、30秒之内如果账户登入错误次数超过5次，那么账户将会被锁定1分钟，1分钟后自动解锁。
2、考虑到该接口使用的情况，针对同类型数据的请求只允许每2秒请求一次，如果2秒内频繁请求将会被拒绝。 也就是说如果在请求状态报告时被禁止但不阻碍用户获取上行的信息，除非上行信息也因访问频繁而非禁止。

2.4下行(MT)一对一发送短信

1.接口说明：
由于此接口支持群发，传输的数据量会比较大，所以其提交数据的方式为POST方式，同时其发送数据的格式为JSON格式。整个POST方式提交的JSON串，必须以GBK的字节编码的方式进行传输，以免中文乱码。
一对一短信是指主体短信内容相同，但是因发送给不同号码对象，部分数据根据对象发生变化。如:尊敬的XXX，您当前余额为YYY。针对不同的手机号码XXX和YYY会做相应的变化。

接口地址		http://yxt.gausstel.com/PointGsmsHttp
请求方式		POST
参数	是否必填	字段类型	描述
username	Y(是)	String	登录名
password	Y(是)	String	ISP登陆密码(公司分配给ISP)
list			短信发送集合,集合中最多支持100个一对一短信内容
toMobile	Y(是)	String	目的手机号，此处不支持同时传多手机号
content	Y(是)	String	短信内容，每条内容不超过1000字
extPort	N(否)	String	扩展端口
sendTime	N(否)	String	此字段有值时，表明此短信为定时短信，其时间格式为：yyyy-MM-ddHH:mm:ss 注意：定时发送时间与网关服务器时间如相隔时间较短（1分钟内）则均作为普通及时短信立即发送

2.返回值：

参数	类型	描 述
code	String	短信提交状态，值为OK时则提交成功，如果为其他值则短信提交失败，其具体的失败原因需要根据desc进行判断。
desc	String	具体的错误信息。desc信息提交整体的错误描述，如：用户名或密码错误等,其错误信息可参考2.1接口返回的错误信息描述。
list		结果返回集合。
mobileDesc	String	具体的错误信息。是某手机号提交失败的原因。
toMobile	String	发送短信的目的手机号。
messageId	String	发送短信的短信ID，用于状态报告对应。当错误时则此字段为空。

3.返回值说明：
具体的错误返回值见2.1章节的返回值说明。

4.示例：
请求示例 返回值示例
5.注意事项：
1、30秒之内如果账户登入错误次数超过5次，那么账户将会被锁定1分钟，1分钟后自动解锁。

2.5下行5G(MT)短信

当ISP系统通过短信网关向用户手机发短信需要进行5G编写时，ISP系统将客户提交的短信采用5G编写处理后，在使用类似的方式向短信网关的CGI发5G短信。整个POST方式提交的JSON串，必须以GBK的字节编码的方式进行传输，以免中文乱码。

1.下行短信接口说明：

接口URL	http://yxt.gausstel.com/i5GsmsHttp
请求方式	POST
参数名称	类型	是否需要转码	是否必填	描 述
username	String	N(否)	Y(必填)	登录名
password	String	N(否)	Y(必填)	ISP登陆密码(公司分配给ISP)
list				短信发送集合,集合中最多支持100个一对一短信内容
toMobile	String	N(否)	Y(必填)	目的手机号，此处不支持同时传多手机号
content	String	Y(是)	Y(必填)	短信内容 必须进行GBK的URL转码
templateId	String	N(否)	Y(必填)	I5G短信模板ID，必填项，其值来源于MAAS运营平台。
title	String	N(否)	N(非必填)	指定I5G短信模板中的标题（指的是单卡片或者多卡片第一个卡片的标题内容），如不传值则以模板中的标题为准，该字段不算入短信计费长度（不可超出25字）。
abstractContent	String	N(否)	N(非必填)	指定I5G短信模板中的摘要内容（指的是单卡片或者多卡片第一个卡片的摘要内容），如不传值则以模板中的摘要为准，该字段不算入短信计费长度（不可超出1000字）。
tabContent	String	N(否)	N(非必填)	指定i5G短信模板中，指定别名变量的具体参数值，其内容为固定的按照JSONObject方式解析的JSON串，详细使用说明可参看3.5章节

2.返回值：
具体的错误返回值见2.1章节的返回值说明。

3.示例：
请求示例 返回值示例
4.注意事项：
1、30秒之内如果账户登入错误次数超过5次，那么账户将会被锁定1分钟，1分钟后自动解锁。

3.常见问题

3.1哪些ISP会采用这种开发接口？
当ISP具有以下特点时，比较愿意采用双向HTTP的方式：
具有CGI开发经验;
接受HTTP这种标准互联网协议;

3.2开发量有多大？
采用双向HTTP的方式，ISP的开发量较小，主要工作包括：
理解HTTP的各个参数;
定义短信应用数据库表结构（也可在已有的数据库上添加相关表）;
开发一个CGI;

3.3请求频繁如何处理？
请求频繁处理指的是由密码错误或其他原因导致请求失败的情况，当每次请求的时间间隔在30秒内，失败次数达到5次，系统自动锁定帐号；
对于被锁定的帐号，将于当前时间算起的1分钟后自动解封。

3.4为什么有些字段内容需要转码？
由于请求的方式为HTTP，所以在实际运用的过程中会存在一些特殊字符的问题，例如业务短信内容中必须包含有空格，& 字符或者%字符。为解决上述的问题，客户需要将请求中对应的参数进行GBK的URL编码 进行转码操作。

3.5什么是5G短信的别名变量？
在客户定制化5G卡片中，部分客户会要求，相同的5G卡片发到不同的手机用户，用户在点击收到5G短信中的短链后，看到不同的界面（点击里面的按钮也可以跳到不同链接）。为实现此功能，新增了名为别名变量的动态参数。
用户在MAAS系统中定制化设计卡片时，如下图：

如上图，客户需要达到不同的手机号打开短链时，其背景图展示的百度图片各不相同，则可由上图的配置方式，选择封面类型为动态生成，其标签名取名为：bg1。同时，同一个按钮不同的用户点击后跳转到不同的页面，则按钮处的按钮类型，选择动态生成，其标签名定义为b1。

定制好卡片，得到一个卡片ID值，则可以开始准备短信发送接口的参数组装。客户使用时，组装如下请求JSON串。
客户按照上述方式进行接口传参访问后，当短信用户真实收到短信后，点击链接打开后，2个不同的手机端用户看到的背景图片以及按钮点击的实际链接地址变为：
13855135510手机号看到的背景图地址为：
www.baidu.com?installer
点击按钮跳转的地址为
www.baidu.com?name=343&kw=asbd&sign=13855135510

13855135511手机号看到的背景图地址为：
www.baidu.com?visitor
点击按钮跳转的地址为
www.baidu.com?name=343&kw=asbd&sign=13855135511

注意：
1.图中的演示链接以及所传参数只是演样例，真实环境下并无实际意义。
2.其所传输的5G短信别名变量，不同的接口可能存在部分值传输方式的差异，例如2.1章节的接口必须将值进行URL转码，
例如：