简版HTTP协议接口文档0407.docx
《简版HTTP协议接口文档0407.docx》由会员分享，可在线阅读，更多相关《简版HTTP协议接口文档0407.docx（18页珍藏版）》请在冰豆网上搜索。
简版HTTP协议接口文档0407
短信接口规范
v1.2
2015年3月
文档变更记录
序号
变更内容说明
版本号
版本日期
执笔人
1
初稿,基本协议，、、状态报告、查询余额
下行为了兼容协议的长短信，数据短信，计费，服务代码等功能，字段设置以协议为蓝本，协议保留协议的所有功能
1.0
2014/12/21
2
简化版本修订：
1.抽取协议统一请求格式
2.
3.增加简化、
4.
5.版本修订为1.1
1.1
2015/3/1
3
极度简化版本：
1.鉴权方式改变，使用参数，
2.
3.采用
4.
5.
1.2
2015/3/16
4
修改的字段，从[]变为逗号分隔的，
但响应仍保持数组形式
1.2
2015/3/19
3
正式稿
1.1
2015/3/16
1概述
2
2.1协议说明
2.2
本短信是使用并遵循原则设计的服务接口，可以使用几乎任何客户端和任何编程语言与进行交互。
通过发送简单的请求就可以轻松接入使用。
2.3版本说明
2.4
在作为变体的协议1.0推出后，为了简化协议开发难度，对协议的下行和上行部分进行相应地修改，形成本简化协议，保留业务逻辑必要的核心字段，去掉扩展功能的若干字段（本接口不再具备发送数据短信能力）。
1.1与1.0的异同：
1.安全认证方式相同，仍然为报文头携带信息64编码，携带5
2.下行上行报文简化
3.状态报告推送方式保持不变
4.短信内容传递方式不使用[],而是使用64编码的原始8字符串进行传递。
2.5适用范围
2.6
2.7参考资料
2.8
•1.0
•
2.9缩略语
缩写
全称
说明
企业客户
短信下行
短信上行
3通信方式
4
通信支持/。
其中报文为作为请求平台
报文为平台作为客户端请求
5协议说明
6
6.1报文域属性说明
6.2
元素约束（出现次数）符号说明：
符号
说明
?
0..1，可选项
*
0，可以没有，也可以有多项
+
1，至少有1项，也可以有多项
1
必须有且只有1项
6.3请求平台（下行）统一格式
6.4
6.4.1平台
6.4.2
由平台提供
{}:
{}/{}
属性
约束
类型
描述
1
平台的地址或者域名。
0
端口号，
端口号不为80时，与用半角:
隔开
当端口号为80时，此字段可空
1
协议版本，
当前协议版本为：
12
示例：
6.4.3业务格式
6.4.4
注：
与业务相拼接为完整请求
帐号鉴权：
/{}/[]
举例：
下发短信息的为：
用户0001查询账户余额的为：
0001
属性
约束
类型
描述
1
业务功能
0
用户
6.4.5 标准包头字段
6.4.6
包头必填字段：
;
8;
;
属性
约束
类型
描述
1
客户端响应接收数据格式：
1
类型：
8
1
内容长度
6.5平台做客户端请求（上行）统一格式
6.6
适用于平台作为客户端向发送上行、状态报告时的情形
6.6.1客户提供上行
6.6.2
由提供用以接收上行消息和状态报告的
举例：
提供上行为：
6.6.3上行业务完整
6.6.4
上行各业务都有各自的，完整的业务会发送至：
${客户提供上行}/{}
举例：
提供上行为：
平台上行短信为,上行报文会发送至：
平台状态报告为
6.7编码
6.8
编码统一使用8
7协议报文定义
8
8.1消息报文定义
8.2
8.2.1下行短消息
8.2.2
8.2.2.1提交短信
方法
描述
${}
参见3.2节说明
消息体
约束
类型
描述
1
用户
1
帐号密码：
（可以明文密码或使用32位5加密）
?
（24）
客户流水号，可在响应中携带返回，最长24位，可包含数字字母
1
短信接收端手机号码集合，用半角逗号（英文逗号）分开，每批发送的手机号数量不得超过不能超过客户设置带宽。
通常以20个号码做为上限。
手机号建议不重复，不强制限制。
1
短信内容，8编码字符串，单条通常为65汉字以内（根据签名规则不同），超过限制字数会被分拆，同时计费条数会根据最终拆分条数计算，具体由平台拆分结果确定。
示例：
\
":
"\
":
8"\
'{"":
"","":
"","":
"00001","":
",","":
"您的验证码为1234【】"}'\
响应消息：
响应码
响应短语
描述
200/401
接收完成/鉴权失败
下发接收完成时（200）：
消息体
约束
类型
描述
1
[]
结果返回集合，每个提交手机号对应以下子元素
子元素
+
下行响应码
取值见附录-
子元素
+
信息标识，用于对应状态报告
用户提供流水号时：
系统流水号+“-”+用户流水号
用户未提供流水号时：
系统流水号
响应码不成功时无此内容
子元素
+
手机号
返回报文示例：
{
"":
[
{
"":
0,
"":
"",
"":
""
},
{
"":
0,
"":
"",
"":
""
}
]
}
鉴权失败时（401）：
报头
约束
描述
1
:
${}
:
取值见附录-
消息体
约束
值
描述
8.2.3查询当前预付费用户余额
8.2.4
方法
描述
${}${}
参见3.2节说明
消息体
约束
类型
描述
响应消息：
响应码
响应短语
描述
200/401
接收完成/鉴权失败
下发接收完成时（200）：
消息体
约束
类型
描述
1
查询余额响应码
取值见附录-
？
当前用户所属账户余额（响应吗为成功时存在）
反馈示例：
{
"":
"0",
"":
100
}
鉴权失败时（401）：
报头
约束
描述
1
:
${}
:
取值见附录-
消息体
约束
值
描述
8.2.5上行验证
8.2.6
方法
描述
客户提供上行
报头
约束
描述
1
1
8
消息体
约束
类型
描述
1
标识，内容固定为
响应消息：
响应码
响应短语
描述
200
接收完成
接收完成时（200）：
消息体
约束
类型
描述
1
固定返回0
8.2.7上行短信推送
8.2.8
方法
描述
${客户提供上行}
报头
约束
描述
1
1
8
消息体
约束
类型
描述
1
信息标识
1
用户上行服务号
1
用户手机号
1
短信内容，8编码字符串
报文示例：
{
"":
"",
"":
"1",
"":
"",
"":
"谢谢！
"
}
响应消息：
响应码
响应短语
描述
200
接收完成
接收完成时（200）：
消息体
约束
类型
描述
1
上行接收响应码
取值见附录-
8.2.9上行状态报告推送
8.2.10
方法
描述
${客户提供上行}
报头
约束
描述
1
1
8
消息体
约束
类型
描述
1
信息标识对应响应中的
1
服务号
1
用户手机号
1
发送短信的应答结果
取值见附录-
报文示例：
{
"":
"00002",
"":
"1",
"":
"",
"":
""
}
响应消息：
响应码
响应短语
描述
200
接收完成
接收完成时（200）：
消息体
约束
类型
描述
1
上行接收响应码
取值见附录-
9附录-码表
10
10.1认证返回码
代码
说明
1
系统忙
3
用户鉴权错误
7
鉴权错误
9
未知错误
10.2下行短信提交响应码
代码
说明
0
成功
1
手机号码在黑名单
2
手机号码不在白名单
3
短信内容中包含黑名单关键字
4
手机号码未找到相应运营商配置
5
手机号码格式错误
7
下发队列满需客户重发
8
发送超速需客户重发
9
未知错误
10
短信内容超长
11
预付费客户余额不足
12
含有未报备关键字
13
下行消息携带号码超过限制（默认为商户1s最大带宽）
10.3查询余额响应码
代码
说明
0
查询成功
1
当前用户属于后付费客户
2
当前用户未分配账户
9
未知错误
10.4上行接收响应码
代码
说明
0
成功
1
失败
10.5状态报告
代码
说明
成功
.
（.）
a
不返回响应消息时的状态报告
返回错误响应消息时的状态报告
不返回响应消息时的状态报告
返回错误响应消息时的状态报告
:
0000
人工审核错误
:
00
对应下行短信提交响应码，表示系统内部模块处理失败返回码。
客户侧处理方式同下行短信提交响应码。
升级会员 