阅信 HTTP&HTTPS 接口协议

阅信短信平台接口协议

HTTP&HTTPS

v4.0.10

北京金楼世纪科技有限公司
2016 年 09 月
 阅信 HTTP&HTTPS 接口协议

目录
1. 概述.......................................................................................................3
1.1 名词定义.............................................................................................................................3

1.2 工作方式.............................................................................................................................3

1.3 字符编码.............................................................................................................................3

1.4 计费方式.............................................................................................................................4

2. 下行消息...............................................................................................4
2.1 提交参数说明.....................................................................................................................4

2.2 返回值说明.........................................................................................................................5

2.3 返回内容示例.....................................................................................................................5

3. 上行消息&状态报告............................................................................6
3.1 上行消息参数说明............................................................................................................6

3.2 短信状态报告参数说明....................................................................................................6

3.3 返回值.................................................................................................................................7

4. 提交返回值...........................................................................................7
5. 状态报告返回值...................................................................................7
 阅信 HTTP&HTTPS 接口协议

1. 概述

本接口规范定义了阅信短信系统（服务方）与客户系统（客户方）之间的数
据传输协议及使用方法。通过这个接口规范可以实现客户系统 (通过短信系统)
与手机终端之间的消息传送。

1.1 名词定义

1.1.1 下行消息

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

上行消息又称 MO 消息，是指由手机终端发送至短信平台并最终送到客
户系统的文字信息。
1.1.3 状态报告

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

1.2 工作方式

双方通过 HTTP/HTTPS 协议交互数据，HTTP/HTTPS 协议可以采用 GET

或 POST 方式交换，推荐使用 POST 方式。
备注：GET 是明文提交，POST 是密文提交，批量提交必须使用 POST 方
式。

1.3 字符编码

关于短消息内容，阅信短信平台服务端发送和接收数据均以 UTF-8 编码和

 阅信 HTTP&HTTPS 接口协议

解码，客户业务系统发送和接收数据也应以 UTF-8 编码和解码。

备注：如果客户业务系统不采取 UTF-8 编码和解码，则会出现中文乱码情
况。

1.4 计费方式

普通短信计费规则：短信内容为 70 字符（含）以内，按 1 条计费；大于 70

个字符则按长短信计费规则计费。
长短信计费规则：短信内容 70 字符以上，670 字符（含）以内，每 67 字
符 1 条进行计费。
汉字、数字、字母、标点符号、控制字符、特殊字符等均算 1 个字符。
以下情况均算入计费内容：
A、短信签名，签名括号“【】”
B、标点符号，空格，换行符，特殊字符等
C、“退订回复 TD”等提醒内容
D、链接，网址等内容

2. 下行消息

接口地址请咨询客服人员。
提交方式：GET｜POST（建议使用 POST，批量提交用户必须使用 POS
T）
参数格式：key-value，例：name=abc&pwd=cde&phone=134

2.1 提交参数说明

参数名称 参数说明 备注
name 帐号（必选）
pwd 密码（必选） 32 位 MD5 小写值。
需要用给定的密码拼接发送时间进行再次
 阅信 HTTP&HTTPS 接口协议

MD5 加密。MD5(pwd+mttime)
subid 扩展码（可选） 用户自定义的子用户接入号扩展码。
当有多个签名时，该字段必选。
一个扩展码必须对应一个签名。
一个签名可以对应多个扩展码。
扩展码建议不超过 7 位。
例如：106900001234 是分配给 A 客户的
短信业务代码，A 客户分配给办公室使用
10690000123401 ， 分 配 给 财 务 部
10690000123402，则 01/02 为扩展码。
phone 手机号码（必选） 国内号码：11 位的有效手机号码。
群发多个手机号，用英文半角逗号“，”
隔 开 ， 单 次 手 机 号 最 大 个 数 为 国 内 100
个。
content 短信内容（必选） GET 提交需要对内容进行 URL 编码。（不
推荐使用）
Javascript 提交需要对内容进行 2 次 URL
编码。
POST 提交不需要对内容进行 URL 编码。
短信内容最长为 670 个字符。
为避免%造成乱码问题，建议将短信内容
中英文%替换成中文％。
mttime 提交时间（必选） 时间格式：yyyyMMddhhmmss
须取当前时间，不能比当前时间早或晚太
多。
只 做 密 码拼 接加 密用 ，不 会 影 响 短 信发
送。
extend 扩展字段（可选） 客户自定义扩展字段，长度最大 32 位，例
如：推送状态报告返回时的特殊要求。
rpttype 返回数据类型（必 值为：0 返回 Xml 格式（过时）
选） 值为：1 返回 Json 格式（推荐）
 阅信 HTTP&HTTPS 接口协议

2.2 返回值说明

参数名称 参数说明 备注
ReqCode 返回值 返回值，参见 4
ReqMsg 返回值说明 返回值说明
ReqId 提交批次 ID 匹配状态报告使用

2.3 返回内容示例

Json 格式：
{
"ReqCode": "00",
"ReqMsg": "提交成功",
"ReqId": "16011514475100000001"
}
Xml 格式：
<resp><reqId>16011514475100000001</reqId><reqCode>00</
reqCode></resp>

3. 上行消息&状态报告

用户提供接收上行消息和状态报告的 URL 地址，短信平台给用户及时推送

上行消息和状态报告。上行消息和状态报告可共用 1 个 URL 地址，也可分开用
2 个 URL 地址。（暂时只支持 1 个 URL 地址）
状态报告需要用户根据下行消息时返回的 ReqId 和 phone 进行匹配。
上行示例：
http://xxx.xxxx.xxxx.xxx:xxxx/xxx?
msgtype=0&phone=13400000000&subid=1234&content=用户回复内容
&receivetime=20160101081220
 阅信 HTTP&HTTPS 接口协议

状态报告示例：
http://xxx.xxxx.xxxx.xxx:xxxx/xxx?
msgtype=2&phone=13400000000&reqid=16011514475100000001&ex
tend=&receivetime=20160101081220&sendtime=20160101081218&st
ate=0

3.1 上行消息参数说明

参数名称 参数说明
msgtype 0 为上行消息
phone 手机号
subid 扩展号
content 上行短信内容
receivetime 上行消息接收时间，格式 yyyyMMddHHmmss

3.2 短信状态报告参数说明

参数名称 参数说明
msgtype 2 为状态报告
phone 手机号
reqid ReqId 发送批次 ID
extend 客户自定义扩展字段，返回客户提交时的值。
receivetime 状态报告接收时间，格式 yyyyMMddHHmmss
sendtime 短信下发时间，格式 yyyyMMddHHmmss
state 状态报告码

3.3 返回值

客户在接收到上行消息和状态报告时，需要返回内容“ok”。
 阅信 HTTP&HTTPS 接口协议

4. 提交返回值

ReqId 返回值 返回值说明 备注

00 提交成功
01 提交参数异常 提交参数不完整，缺少必须参
数。
02 手机号参数异常
03 扩展号参数异常
04 提交时间参数异常
05 短信内容解析异常
06 提交内容超长
07 扩展参数超长 最大 32 位字符串
10 IP 认证失败
11 帐号密码认证失败
99 系统内部错误

5. 状态报告返回值

State 返回值 返回值说明 备注

0 发送成功
JL:0002 手机号异常 手机号码不正确等
JL:0012 扩展号超长
JL:0013 手机号在账号黑名单中
JL:0014 短信内容中有违禁词
JL:0015 帐号余额不足
JL:0016 帐号日发送上限
JL:0017 通道未配置 需联系客服配置通道
 阅信 HTTP&HTTPS 接口协议

JL:0018 短信提交超速 默认限制 100 次／秒

JL:0019 余额查询超速 默认限制 1 次／分钟
JL:0020 状态报告主动查询超速 默认限制 1 次／秒
JL:0021 群发限制 默认 20:00 点到第二天 7:00 点前
不允许群发短信
JL:0022 短信签名未备案
JL:0023 短信签名未设置或设置错
误
JL:0024 关键字或群发审核未通过 短信内容中有审核关键字或群发
内容不合规，被审核人员驳回，
拒绝发送。
JL:0025 单个号码日发送上限 单个手机号码每日发送上限限
制，默认每个手机号码每天只能
接收 10 条短信，如需修改或解除
请联系客服人员。
JL:0026 手机号在平台黑名单中