1、案卷号日期云 MAS 平台 SDK1.0.1（HTTP 版）用 户 手 册作 者： 中国移动通信有限公司政企客户分公司 完成日期： 2015-12-7 签 收 人： 签收日期： 修改情况记录：版本号 修改内容 修改日期 修改人1.0.0 草稿 2015-12-7 汪植成1.0.1 签名错误或普通短信不允许使用模板短信的签名编码2016-04-20 汪植成1 云 MAS 平台 HTTP 开发说明1.1 简介云 MAS 平台 SDK HTTP 版接口说明文档1.2 背景系统名称：云 MAS 平台项目开发者： 中国移动通信集团政企客户分公司1.3 定义MT Message Terminal下行短信，
2、即向手机终端发送短信MO Message Original上行短信，即手机用户向特服号码发送短信1.4 环境服务器具有直连访问互联网的能力。并且提供 HTTP Server 接收比较报告，状态报告，上行短信。1.5 云 MAS 平台与 HTTP 客户端数据交互流程HTTP客 户 端 云 MAS服 务 端 云 MAS消 息 队 列 云 MAS审 核 服 务 云 MAS发 送 服 务 行 业 网 关1.HTTP客 户 端 提 交 短信 至 云 MAS2.服 务 端 提 交 消 息 至消 息 队 列2.服 务 端 提 交 消 息 至 审 核 服 务3.审 核 不 通 过4.返 回 审 核 结 果数
3、据 结 构 见 2.13.审 核 通 过 ， 消 息 队 列 提 交 客 户 封 包 至 发 送 服 务 4.提 交 短 信 至 行 业 网 关5.返 回 短 信 回 复6.返 回 短 信 回 复8.返 回 短 信 回 执9.返 回 短 信 回 执7.返 回 短 信 回 复数 据 结 构 见 2.210.返 回 短 信 回 执数 据 结 构 见 2.34.通 知 删 除 待 发 内 容4.返 回 审 核 状 态HTTP服 务 端 2:返 回 状 态 码 和 后台 生 成 的 UUID，SDK 收到的返回值说明： “1.返回提交状态” ，说明云 MAS 是否收到 HTTP 提交的数据；数据还未提
4、交行业网关； “4.返回审核结果” ，说明云 MAS 已经对提交内容进行了审核；数据还未提交行业网关； “7.返回短信回复” ，短信已经提交网关； “10.返回短信回执” ，短信已被网关下发；*因平台有流控设置，需要进行多条短信连续提交时，为保证提交速度和效率，请按照“1.返回提交状态 ”返回值判断是否提交下一条；2 数据结构说明2.1 MT 提交报告数据结构 类型（TYPE）：JSON 用途 用于内部，跟踪短信状态，不能用于判断短信是否正确送达，短信是否送达以移动公司提供的账单为准。字段名 数据类型 说明type string 消息类型：1 表示为提交报告，2 表示为状态报告 ，3 表示为用
5、户上行短信,见附录 4.1(8)report_status string 状态报告的值，见附录 4.1mobiles string 手机号码,多个手机号码英文半角逗号分隔submit_date string 发送时间（格式为 yyyy-mm-dd hi24:mi:ss）receive_date string 接收时间（格式为 yyyy-mm-dd hi24:mi:ss）error_code string 未发送成功错误编码，见附录 4.1msg_group string 消息批次号，由云 MAS 平台生成，用于验证短信提交报告和状态报告的一致性2.2 MT 状态报告数据结构 类型（TYPE）：
6、JSON 用途 保存状态报告接口函数返回的短信内容，不能用于判断短信是否正确送达，短信是否送达以移动公司提供的账单为准。字段名 数据类型 说明 type string 消息类型：1 表示为提交报告，2 表示为状态报告 ，3 表示为用户上行短信report_status string 状态报告的值，参见真实网关状态报告值mobile string 手机号码，每次返回单个号码submit_date string YYMMDDHHMM（YY 为年的后两位 00-99，MM：01-12，DD：01-31，HH：00-23，MM：00-59）receive_date string YYMMDDHHMM（
7、YY 为年的后两位 00-99，MM：01-12，DD：01-31，HH：00-23，MM：00-59）error_code string 未发送成功错误编码，参见真实网关错误码msg_group string 消息批次号，由云 MAS 平台生成，用于验证短信提交报告和状态报告的一致性2.3 MO 数据结构 类型（Type）：JSON 用途 保存上行短信接口函数返回的短信内容。字段名 数据类型 说明type string 消息类型：1 表示为提交报告，2 表示为状态报告 ，3 表示为用户上行短信mobile string 手机号码，单个号码sms_content string 上行短消息内容s
8、end_time string 发送时间（格式为 yyyy-mm-dd hi24:mi:ss）serial string 客户上行目标服务代码。3 功能介绍及使用 3.1 身份验证 功能介绍企业必须通过身份验证才能进行短信发送,身份验证用户名、密码和集团客户名称完成。 请求申明测试环境：http:/112.33.1.13:80/app/http/authorize正式环境：http:/ 参数详解参数名称 说明ec_name 集团客户名称user_name 用户名user_passwd 密码 返回值返回值 描述mas_user_id 用户登录 idaccess_token API 输入参数签名
9、密钥access_token_expire_seconds API 输入参数签名超时时间，超过此阈值后 API 输入参数签名密钥作废，需要重新申请，调用 HTTP API 时应该在超时时间到达以前申请新的签名密钥status 验证状态，错误码请参考：3.1.13.1.1错误码 描述SC:4060 登录验证请求超速Error: Invalid authorization 未通过授权Success 登录成功3.2 发送普通短信 HTTP 客户端向云 MAS 平台发送请求，带上相应的请求参数，云 MAS平台接收请求，并进行验证，验证通过后进行短信发送。 请求声明测试环境：http:/ 112.33.
10、1.13:80/app/http/sendSms正式环境：http:/ 参数详解参数名称 说明mas_user_id 用户唯一标识mobiles 手机号码数组，逗号分隔。content 发送短信内容sign 网关签名编码，必填，签名编码在中国移动集团开通帐号后分配，可以在云 MAS 网页端管理子系统-SMS接口管理功能中下载。serial 扩展码，根据向移动公司申请的通道填写，如果申请的精确匹配通道，则填写空字符串(“)，否则添加移动公司允许的扩展码mac API 输入参数签名结果，签名算法：将mas_user_id，mobiles，content ，sign ，serial, access_
11、token按照顺序拼接，然后通过 MD5+HEX 计算后得出的值 返回值 RET-CODE返回值 描述SC:4060 登录验证请求超速SC:4010 用户 TOKEN 不存在，可能已失效或未登录SC:4000 HTTP MAC 校验错误，请注意签名参数顺序SC:4140 手机号码数量超过 200SC:4141 短信内容字符数超过 5000SC:4011 用户信息缺失，可能已失效或未登录SC:5001 接口处理异常，请联系技术支持或稍候再试SC:0000 短信成功提交至云 MAS 平台SC:7002 非法号码批次SC:7003 重复号码SC:112 签名错误或普通短信不允许使用模板短信的签名编码
12、 MSG-GROUP返回短信批次号3.3 发送模板短信 功能介绍模板短信发送，HTTP 客户端向云 MAS 平台发送请求，根据指定模板ID，传入模板所需参数发送短信，云 MAS 平台接收请求，并进行验证，验证通过后进行短信发送。 函数声明测试环境：http:/112.33.1.13:80/app/http/sendSmsByTemplate 正式环境：http:/ 说明mas_user_id 用户唯一标识template_id 模版 ID，模板由用户在中国移动集团提供的客户业务平台上，由客户自己增加短信模版的信息。params 模版参数，多个用空格分割。 模板采用模板和参数合成的方式产生短信，
13、 短信内容由发送服务器自动拼接。模板参数必须和模板中定义的动态填写的参数的个数一致。mobiles 手机号码数组，逗号分隔。content 短信内容sign 网关签名编码，必填，签名编码由企业在中国移动集团开通帐号分配serial 扩展码，根据向移动公司申请的通道填写，如果申请的精确匹配通道，则填写空字符串(“)，否则添加移动公司允许的扩展码mac API 输入参数签名结果，签名算法：将mas_user_id，template_id ，params ，mobiles，content ，sign，serial，, access_token 按照顺序拼接，然后通过MD5+HEX 计算后得出的值 返
14、回值 RET-CODE返回值 描述SC:4060 登录验证请求超速SC:4010 用户 TOKEN 不存在，可能已失效或未登录SC:4000 HTTP MAC 校验错误，请注意签名参数顺序SC:4140 手机号码数量超过 200SC:4141 短信内容字符数超过 5000SC:4011 用户信息缺失，可能已失效或未登录SC:5001 接口处理异常，请联系技术支持或稍候再试SC:0000 短信成功提交至云 MAS 平台SC:7001 自定义参数为空SC:7002 非法号码批次SC:7003 重复号码 MSG-GROUP返回短信批次号3.4 获取提交报告 功能介绍云 MAS 平台将提交报告采用 P
15、OST 方式推送至开户时设定的 HTTP 地址，如果推送失败，两秒后将再次推送，连续失败三次后将丢弃数据；数据结构参考 2.1 MT 提交报告数据结构。此方法获得的数据不能用于判断短信是否正确送达，短信是否送达以移动公司提供的账单为准3.5 获取状态报告 功能介绍云 MAS 平台将状态报告采用 POST 方式推送至开户时设定的 HTTP 地址，如果推送失败，两秒后将再次推送，连续失败三次后将丢弃数据；数据结构参考 2.2 MT 状态报告数据结构。此方法获得的数据不能用于判断短信是否正确送达，短信是否送达以移动公司提供的账单为准3.6 获取上行短信 功能介绍云 MAS 平台将上行短信采用 POS
16、T 方式推送至开户时设定的 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. 文档中提到了“提交报告”和“状态报告”，请问这两个有什么不同点和相同点？提交报告：指
17、 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 表示短信已成功到达用户终端；
