服务支持   /   短信接口文档

1. 接入须知规范

本接口接入须知规范定义了MO信通平台(服务方)与客户系统(客户方)之间的数据传输协议及使用方法; 通过这个接口规范可以实现客户系统(通过MO信通平台)与手机终端之间的消息传送;

> 客户端接收和发送数据,编码格式:UTF-8;

> 本接口采用HTTP协议

    a) 提交方式:POST ;

    b) 消息头设置Content-Type:application/x-www-form-urlencoded;

> 客户端接收和发送数据,编码格式:UTF-8;

> 状态报告推送接口和查询接口互斥,接入时只能选择一种(推荐采用推送方式);

> IP白名单,由系统设置;为了安全设置IP白名单(IP个数不超过10个);

2. 名词术语解释

 2.1 下行消息

下行消息又称 MT 消息,是指由业务系统送到MO信通平台,再转发到运营商的互联网短信网关,并最终发送到手机终端上的文字信息。

 2.2 上行消息

上行消息又称 MO 消息,是指由手机终端发送至运营互联网短信网关,运营商互联网短信网关推送回MO信通平台,并最终送到客户系统的文字信息。

 2.3 状态报告

状态报告是一条特殊上行消息,用于报告下行消息的投递情况。即消息被送达到手机终端后返回的状态消息。

 2.4 短信签名

短信签名作为标识是加在短信的开头,由【】加上您的公司名称或项目名称的标识符,例如:【MO信通平台】。根据电信基础运营商的规定,每条短信必须附加短信签名,否则将无法正常发送。(由中英文,数字组成,不能包含其他特殊字符,如“+,@,|等”)

 2.5 计费方式

短信内容字符<=70字符,按1条计费;>70字符则按长短信67字符一条计费;汉字、数字、字母、标点符号、控制字符、特殊字符等均算 1 个字符;短信签名,包括签名符号【】均算入计费内容。)

3 短信API(HTTP)

 3.1 短信发送接口(MT)

  3.1.1 请求地址

http://IP:端口/sms/httpBatchSend

或:https://IP:端口/sms/httpBatchSend

提交方式:POST

编码格式:utf-8

Content-Type:application/x-www-form-urlencoded;charset=utf-8

注:

短信群发时,单次提交号码个数不能超过5000个(号码过多时,请求报文大小会变大,请注意设置请求和响应超时时间,建议>10s)

此地址,pwd是加密码(加密码获取方式:登录web平台、个人信息中查看)

  3.1.2 输入参数

序号 参数 是否必须 描述
1 username 必须 帐号
2 pwd 必须 加密码(从web平台、个人信息中获取,密码变更时,加密码也会变更);
ts参数为空时填加密码,ts参数不为空时填md5(账号+加密码+时间戳),对账号密码时间戳拼接的字符串进行md5加密,32小写
3 mobile 必须 合法手机号码(若多个手机号码,手机号间用英文逗号(,)分隔),群发时,号码不能超过1000个
4 content 必须 短信内容,短信发送字数不能超过300字,长短信将按分配给账号的产品的计费规则,以多条计费。
5 ts 可选 时间戳,格式yyyyMMddHHmmss

3.1.3 响应格式(JSON文本)

失败格式:

                                
                                    {
                                    "code":"105",
                                    "msg": "请求参数错误(必填、格式)"
                                    }
                                
                            

成功格式:

                                
                                    {
                                    "code":"0",
                                    "msg": "提交成功",
                                    "taskid": "11057292"
                                    }
                                
                            
重要说明: code表示响应状态码(0表示成功,其他表示失败),msg表示响应信息,taskid表示任务编号(可用于查询网关返回状态)

  3.2 余额查询接口

  3.2.1 请求地址

http://IP:端口/sms/queryBalance

或 https://IP:端口/sms/queryBalance

提交方式:POST

编码格式:utf-8

Content-Type:application/x-www-form-urlencoded

注:

1、接口请求限制1000次/天

此地址,pwd是加密码(加密码获取方式:登录web平台、个人信息中查看)

  3.2.2 输入参数

序号 参数 是否必须 描述
1 username 必须 帐号
2 pwd 必须 加密码(从web平台、个人信息中获取,密码变更时,加密码也会变更);
ts参数为空时填加密码,ts参数不为空时填md5(账号+加密码+时间戳),对账号密码时间戳拼接的字符串进行md5加密,32小写
3 ts 可选 时间戳,格式yyyyMMddHHmmss

3.2.3 响应格式(JSON文本)

失败格式:

                                
                                    {
                                    "code":"105",
                                    "msg": "请求参数错误(必填、格式)"
                                    }
                                
                            

成功格式:

                                
                                    {
                                    "code":"0",
                                    "msg": "100"
                                    }
                                
                            
重要说明: code表示响应状态码,msg表示当前账号剩余条数

  3.3 上行回复单条推送(平台推送)-推荐方式

  3.3.1 推送地址设置:

用户侧提供接收上行推送的地址服务,由平台绑定对应的地址到帐号上;

平台使用HTTP GET 方式推送信息,每次推送一条

  3.3.2 参数定义:

序号 参数 描述
1 username 帐号ID(由平台产生)
2 mobile 回复手机号码
3 replyInfo 时间戳,格式yyyyMMddHHmmss
4 replyTime 收到回复信息时间(yyMMddHHmmss 如:2019-01-22 17:04:52)

  3.3.3 响应说明:

客户接收我方推送的信息后须响应200字符串。

  3.3.4 推送参考示例:

GET http://pushUrl/?uid=xxxx&mobile=186xxxxxxx&replyInfo=test&replyTime=190220142411

 3.4 网关状态批量推送(平台推送)-暂未开发

 3.5 网关状态单条推送(平台推送)-推荐方式

  3.5.1 推送地址设置:

用户侧提供接收状态推送的地址服务,由平台绑定对应的地址到帐号上;

平台使用HTTP GET 方式推送信息,每次推送一条

  3.5.2 参数定义:

序号 参数 描述
1 smsid 提交响应流水批次编号(与发送时响应的taskid对应)
2 mobile 发送手机号码
3 gwcode 网关具体状态
4 fee 计费条数
5 receivetime 上行回执时间,格式:yyMMddHHmmss

  3.5.3 响应说明:

客户接收我方推送的信息后须响应200字符串。

  3.5.4 推送参考示例:

GET http://pushUrl/?smsid=xxxxxxxx&mobile=186xxxxxxx&gwcode=xxxx&fee=1&receivetime=190220142411

4 状态码说明

状态码 状态描述 描述
0 提交成功
105 请求参数错误 请检查必填项参数信息
101 账号或密码错误 此处密码为加密码,请登录web平台核实
110 IP鉴权失败 请求IP不在账号设置的IP白名单中
106 余额不足 帐号剩余条数不足
107 账号暂无发送权限 可联系客服申请开通
112 发送内容过长 发送内容不能超过300字
103 发送号码异常 系统过滤后的合法号码,为空或发送号码个数不能超过2000个
111 系统错误(网关异常) 受网关计费、流速、网络通信等影响
117 账号已被冻结
108 未分配通道产品 请联系客服分配产品
114 发送内容未带签名 请检查发送内容签名格式