中国移动通信有限公司政企客户分公司云MAS平台SDK接口1.0.1（HTTP版）

案卷号 日期

云MAS平台SDK1.0.1（HTTP版）

用户手册

作者：中国移动通信有限公司政企客户分公司 完成日期： 2015-12-7 签收人： 签收日期：

修改情况记录： 版本号 1.0.0 1.0.1 草稿 签名错误或普通短信不允许使用模板短信的签名编码 修改内容 修改日期 2015-12-7 修改人 汪植成 2016-04-20 汪植成 1 云MAS平台HTTP开发说明

1.1 简介

云MAS平台SDK HTTP版接口说明文档

1.2 背景

系统名称：云MAS平台

项目开发者：中国移动通信集团政企客户分公司

1.3 定义

MT Message Terminal——下行短信，即向手机终端发送短信 MO Message Original——上行短信，即手机用户向特服号码发送短信

1.4 环境

服务器具有直连访问互联网的能力。并且提供HTTPServer接收比较报告，状态报告，上行短信。

1.5 云MAS平台与HTTP客户端数据交互流程

HTTP客户端云MAS服务端云MAS消息队列云MAS审核服务云MAS发送服务行业网关1.HTTP客户端提交短信至云MASHTTP服务端2:返回状态码和后台生成的UUID，2.服务端提交消息至消息队列2.服务端提交消息至审核服务3.审核不通过4.通知删除待发内容3.审核通过，消息队列提交客户封包至发送服务4.返回审核结果数据结构见2.17.返回短信回复数据结构见2.210.返回短信回执数据结构见2.34.返回审核状态4.提交短信至行业网关5.返回短信回复8.返回短信回执6.返回短信回复9.返回短信回执

SDK收到的返回值说明： ? “1.返回提交状态”，说明云MAS是否收到HTTP提交的数据；数据还未提交行业

网关；

? “4.返回审核结果”，说明云MAS已经对提交内容进行了审核；数据还未提交行

业网关；

? “7.返回短信回复”，短信已经提交网关； ? “10.返回短信回执”，短信已被网关下发；

*因平台有流控设置，需要进行多条短信连续提交时，为保证提交速度和效率，请按照“1.返回提交状态”返回值判断是否提交下一条；

2 数据结构说明

2.1 MT提交报告数据结构

? 类型（TYPE）：JSON

? 用途用于内部，跟踪短信状态，不能用于判断短信是否正确送达，

短信是否送达以移动公司提供的账单为准。 字段名 type 数据类型 说明 string 消息类型：1表示为提交报告，2表示为状态报告 ，3表示为用户上行短信,见附录4.1(8) 状态报告的值，见附录4.1 手机号码,多个手机号码英文半角逗号分隔 发送时间（格式为yyyy-mm-dd hi24:mi:ss） 接收时间（格式为yyyy-mm-dd hi24:mi:ss） 未发送成功错误编码，见附录4.1 消息批次号，由云MAS平台生成，用于验证短信提交报告和状态报告的一致性 report_status string mobiles submit_date receive_date error_code msg_group string string string string string 2.2 MT状态报告数据结构

? 类型（TYPE）：JSON

? 用途保存状态报告接口函数返回的短信内容，不能用于判断短信是

否正确送达，短信是否送达以移动公司提供的账单为准。 字段名 type 数据类型 说明 string 消息类型：1表示为提交报告，2表示为状态报告 ，3表示为用户上行短信 report_status string mobile submit_date receive_date error_code msg_group string string string string string 状态报告的值，参见真实网关状态报告值 手机号码，每次返回单个号码 YYMMDDHHMM（YY为年的后两位00-99，MM：01-12，DD：01-31，HH：00-23，MM：00-59） YYMMDDHHMM（YY为年的后两位00-99，MM：01-12，DD：01-31，HH：00-23，MM：00-59） 未发送成功错误编码，参见真实网关错误码 消息批次号，由云MAS平台生成，用于验证短信提交报告和状态报告的一致性 2.3 MO数据结构

? 类型（Type）：JSON

? 用途保存上行短信接口函数返回的短信内容。 字段名 type mobile sms_content send_time serial 数据类型 说明 string string string string string 消息类型：1表示为提交报告，2表示为状态报告 ，3表示为用户上行短信 手机号码，单个号码 上行短消息内容 发送时间（格式为yyyy-mm-dd hi24:mi:ss） 客户上行目标服务代码。 3 功能介绍及使用

3.1 身份验证

? 功能介绍

企业必须通过身份验证才能进行短信发送,身份验证用户名、密码和集团客户名称完成。 ? 请求申明

测试环境：http://112.33.1.13:80/app/http/authorize

正式环境：http://mas.ecloud.10086.cn/app/http/authorize ? 参数详解 参数名称 说明

ec_name user_name user_passwd ? 返回值 返回值 mas_user_id access_token access_token_expire_seconds 集团客户名称 用户名 密码 描述 用户登录id API输入参数签名密钥 API输入参数签名超时时间，超过此阈值后API输入参数签名密钥作废，需要重新申请，调用HTTPAPI时应该在超时时间到达以前申请新的签名密钥 验证状态，错误码请参考：3.1.1 status 3.1.1 错误码 SC:4060 Error: Invalid authorization Success

描述 登录验证请求超速 未通过授权 登录成功 3.2 发送普通短信

HTTP客户端向云MAS平台发送请求，带上相应的请求参数，云MAS平台接收请求，并进行验证，验证通过后进行短信发送。 ? 请求声明

测试环境：http://112.33.1.13:80/app/http/sendSms

正式环境：http://mas.ecloud.10086.cn/app/http/sendSms ? 参数详解 参数名称 mas_user_id mobiles content sign 说明 用户唯一标识 手机号码数组，逗号分隔。 发送短信内容 网关签名编码，必填，签名编码在中国移动集团开通帐号后分配，可以在云MAS网页端管理子系统-SMS接口管理功能中下载。 扩展码，根据向移动公司申请的通道填写，如果申请的精确匹配通道，则填写空字符串(\，否则添加移动公司允许的扩展码 serial mac API输入参数签名结果，签名算法：将mas_user_id，mobiles，content，sign，serial,access_token按照顺序拼接，然后通过MD5+HEX计算后得出的值

? 返回值

? RET-CODE 返回值 SC:4060 SC:4010 SC:4000 SC:4140 SC:4141 SC:4011 SC:5001 SC:0000 SC:7002 SC:7003 SC:112 描述 登录验证请求超速 用户 TOKEN 不存在，可能已失效或未登录 HTTP MAC 校验错误，请注意签名参数顺序 手机号码数量超过200 短信内容字符数超过5000 用户信息缺失，可能已失效或未登录 接口处理异常，请联系技术支持或稍候再试 短信成功提交至云MAS平台 非法号码批次 重复号码 签名错误或普通短信不允许使用模板短信的签名编码 ? MSG-GROUP 返回短信批次号

3.3 发送模板短信

? 功能介绍

模板短信发送，HTTP客户端向云MAS平台发送请求，根据指定模板ID，传入模板所需参数发送短信，云MAS平台接收请求，并进行验证，验证通过后进行短信发送。 ? 函数声明

测试环境：http://112.33.1.13:80/app/http/sendSmsByTemplate

正式环境：http://mas.ecloud.10086.cn/app/http/sendSmsByTemplate 参数详解 参数名称 template_id params 说明 模版ID，模板由用户在中国移动集团提供的客户业务平台上，由客户自己增加短信模版的信息。 模版参数，多个用空格分割。模板采用模板和参数合成的方式产生短信，短信内容由发送服务器自动拼接。模板参数必须和模板中定义的动态填写的参数的个数一致。 mas_user_id 用户唯一标识 mobiles content sign serial 手机号码数组，逗号分隔。 短信内容 网关签名编码，必填，签名编码由企业在中国移动集团开通帐号分配 扩展码，根据向移动公司申请的通道填写，如果申请的精确匹配通道，则填写空字符串(\，否则添加移动公司允许的扩展码 API输入参数签名结果，签名算法：将mas_user_id，template_id ，params ，mobiles，content，sign，serial，,access_token按照顺序拼接，然后通过MD5+HEX计算后得出的值 mac ? 返回值

? RET-CODE 返回值 SC:4060 SC:4010 SC:4000 SC:4140 SC:4141 SC:4011 SC:5001 SC:0000 SC:7001 SC:7002 SC:7003 描述 登录验证请求超速 用户 TOKEN 不存在，可能已失效或未登录 HTTP MAC 校验错误，请注意签名参数顺序 手机号码数量超过200 短信内容字符数超过5000 用户信息缺失，可能已失效或未登录 接口处理异常，请联系技术支持或稍候再试 短信成功提交至云MAS平台 自定义参数为空 非法号码批次 重复号码 ? MSG-GROUP 返回短信批次号

3.4 获取提交报告

? 功能介绍

云MAS平台将提交报告采用POST方式推送至开户时设定的HTTP地址，如果推送失败，两秒后将再次推送，连续失败三次后将丢弃数据；数据结构参考2.1 MT提交报告数据结构。

此方法获得的数据不能用于判断短信是否正确送达，短信是否送达以移动公司提供的账单为准

3.5 获取状态报告

? 功能介绍

云MAS平台将状态报告采用POST方式推送至开户时设定的HTTP地址，如果推送失败，两秒后将再次推送，连续失败三次后将丢弃数据；数据结构参考2.2MT状态报告数据结构。

此方法获得的数据不能用于判断短信是否正确送达，短信是否送达以移动公司提供的账单为准

3.6 获取上行短信

? 功能介绍

云MAS平台将上行短信采用POST方式推送至开户时设定的HTTP地址，如果推送失败，两秒后将再次推送，连续失败三次后将丢弃数据；数据结构参考2.3 MO数据结构。

4 附录

4.1 常见问题

1. 如何判断短信已经成功提交给云MAS平台？

HTTP请求返回MSG_GROUP，RET-CODE为SC:0000则表示短信已经成功提交给云MAS平台；

2. HTTP登陆请求有时间间隔吗？

有，最大允许请求的时间间隔为2分钟；验签的超时时间为2个小时 3. HTTP请求最高速率多少？

HTTP请求最高限速10条/秒；

4. 文档中提到了“提交报告”和“状态报告”，请问这两个有什么不同点和相同点？

提交报告：指HTTP客户端提交给云MAS的报告，报告由云MAS收到HTTP客户端提交请求后发出；

状态报告：云MAS提交给行业网关，行业网关返回的报告，云MAS透传给HTTP客户端；

5. 发送长短信是否有字数上限，长短信是不是不需要客户端来拆分，而有云平台完

成？

长短信字数上限是500，最好不要超过400，长短信由云MAS完成拆分，客户端提交一条即可；

6. 发送短信签名，是不是由客户端发送短信时附带在短信内容后边发送即可？

发送短信签名由行业网关添加，客户发送时所选签名请参见页面中“SMS接口管理”中下载的对应签名编码，发送时填写在短信参数（Sign，详见接口文档3.2中；

7. 提交的号码数量有限制吗？

有，一次提交的号码数量不能超过200个； 8. 关于回执数据说明

提交报告：指短信提交到云MAS平台和短信提交至网关的回执信息； 1)短信成功提交至云MAS并审核通过将返回CM:0000 2)短信成功提交至网关将返回CM:3000

状态报告：真实网关返回的状态报告，DELIVRD表示短信已成功到达用户终端；

本文来源：https://www.bwwdw.com/article/gikw.html