简版HTTP协议接口文档20150407

HTTP短信接口规范v1.22015年3月文档变更记录序号变更内容说明版本号版本日期执笔人1初稿,基本协议，MT、MO、状态报告、查询余额下行为了兼容cmpp协议的长短信，数据短信，计费，服务代码等功能，字段设置以cmpp协议为蓝本，协议保留cmpp协议的所有功能1.02014/12/212简化版本修订：1.抽取协议统一请求格式2.增加简化MO、MT3.版本修订为HIF1.11.12015/3/13极度简化版本：1.鉴权方式改变，使用参数userid，password2.MT采用httpPOST3.1.22015/3/164修改MT的mobile字段，从String[]变为逗号分隔的String，但MT响应仍保持Rets数组形式1.22015/3/193正式稿1.12015/3/16目录1概述...........................................................................................................................................51.1协议说明.......................................................................................................................51.2适用范围.......................................................................................................................51.3参考资料.......................................................................................................................51.4缩略语...........................................................................................................................62通信方式...................................................................................................................................63协议报文定义...........................................................................................................................93.1报文域属性说明...........................................................................................................63.2消息报文定义...............................................................................................................93.2.1下行短信提交MTSMSSUBMIT....................................................................93.2.2查询当前预付费用户余额QUERYAMTF....................................................113.2.3上行URL验证MOURLVERIFY..................................................................123.2.4上行短信推送MOSMSPUSH.....................................................................133.2.5上行状态报告推送RPTPUSH.....................................................................144附录-码表...............................................................................................................................154.1认证返回码authstatus............................................................................................154.2下行短信提交响应码mtrespcode.........................................................................154.3查询余额响应码queryamtfrespcode..................................................................154.4上行接收响应码morespcode................................................................................164.5状态报告Stat............................................................................................................161概述1.1协议说明本短信API是使用HTTP并遵循REST原则设计的Web服务接口，可以使用几乎任何客户端和任何编程语言与RESTAPI进行交互。通过发送简单的HTTPPOST请求就可以轻松接入使用。1.1版本说明在作为CMPP变体的http协议chif1.0推出后，为了简化协议开发难度，对协议的下行和上行部分进行相应地修改，形成本简化协议，保留业务逻辑必要的核心字段，去掉扩展功能的若干字段（本接口不再具备发送数据短信能力）。1.1与chif1.0的异同：1.安全认证方式相同，仍然为报文头携带Authorization信息base64编码，URL携带MD5token2.下行MTSMSSubmit/上行MOSmsPush报文简化3.状态报告推送方式保持不变4.MO/MT短信内容传递方式不使用Byte[],而是使用Base64编码的原始UTF-8字符串进行传递。1.2适用范围1.3参考资料•HTTP1.01.4缩略语缩写全称说明ECEnterprisecustomer企业客户MTMobileTerminal短信下行MOMobileOriginal短信上行2通信方式HTTPRSPHTTPSREQ(GET/POST/PUT/DELETE)CLIENTSERVER通信支持HTTP/HTTPS。其中MT/QUERYAMTF报文为EC作为client请求平台MOURLVERIFY/SMSMOPUSH/SMSRPTPUSH报文为平台作为客户端请求EC3协议说明3.1报文域属性说明元素约束（出现次数）符号说明：符号说明?0..1，可选项*0..n，可以没有，也可以有多项+1..n，至少有1项，也可以有多项1必须有且只有1项3.2EC请求平台（下行）统一格式3.2.1平台BaseURL由平台提供http://{IP}:{port}/{version}属性约束类型描述IP1String平台的IP地址或者域名。port0Integer端口号，端口号不为80时，与IP用半角:隔开当端口号为80时，此字段可空version1String协议版本，当前协议版本为：HIF12BaseURL示例：://api.pro-grouop.com/HIF12/3.2.2业务URL格式注：BaseURL与业务URL相拼接为完整请求URL帐号鉴权：/{funcion}/[Userid]举例：下发短信息的url为：用户user0001查询账户余额的url为：属性约束类型描述func1String业务功能Userid0String用户ID3.2.3HTTP标准包头字段包头必填字段：Accept:application/json;Content-Type:application/json;charset=utf-8;Content-Length:length;属性约束类型描述Accept1String客户端响应接收数据格式：application/jsonContent-Type1String类型：application/json;charset=utf-8Content-Length1String内容长度3.3平台做客户端请求EC（上行）统一格式适用于平台作为客户端向EC发送上行、状态报告时的情形3.3.1客户提供上行BaseURL由EC提供用以接收上行消息和状态报告的BaseURL举例：EC提供上行BaseURL为：上行业务完整URL上行各业务都有各自的function，完整的业务URL会发送至：${客户提供上行BaseURL}/{function}举例：EC提供上行BaseURL为：平台上行短信function为smsmopush,上行报文会发送至：平台状态报告function为smsrptpush编码编码统一使用UTF-84协议报文定义4.1消息报文定义4.1.1下行短消息4.1.1.1提交短信HTTP方法URL描述POST${baseurl}/mt/参见3.2节说明消息体约束类型描述Userid1String用户IDPasswd1String帐号密码：(可以明文密码或使用32位MD5加密)Cli_Msg_Id?String(24)客户流水号，可在响应中携带返回，最长24位，可包含数字字母Mobile1String短信接收端手机号码集合，用半角逗号（英文逗号）分开，每批发送的手机号数量不得超过不能超过客户设置带宽。通常以20个号码做为上限。手机号建议不重复，不强制限制。Content1String短信内容，UTF-8编码字符串，单条通常为65汉字以内（根据签名规则不同），超过限制字数会被分拆，同时计费条数会根据最终拆分条数计算，具体由平台拆分结果确定。示例：curl-XPOST\-HAccept:application/json\-HContent-Type:application/json;charset=utf-8\-d'{Userid:test,Passwd:test,Cli_Msg_Id:msg00001,Mobile:[phone]