31 中国移动通信有限公司政企客户分公司云MAS平台短信SDK接口1 0 1HTTP版VIP

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