短信 HTTP 接口对接总览
HTTP 接口概述
- HTTP接口规范定义了秒信云平台（服务方，这里指秒信技术服务平台）与客户系统（客户方）之间的数据传输协议及使用方式；
- 通过接口规范可以实现客户系统(通过秒信)与手机终端之间的短信消息传送；
- 秒信平台的短信发送接口协议使用HTTP协议，秒信云平台提供访问的URL，客户使用HTTP POST方法发送请求并得到应答内容,客户作为短信平台的HTTP客户端，秒信云平台作为用户的HTTP服务器。
- 秒信云平台为客户提供短信发送、状态报告及短信上行的获取服务。
HTTP 接口安全
对于短信发送、状态查询接口，秒信平台会验证发送方的有效性，我们有两重策略。
HTTP 接口协议签名
| 字段 |
必填 |
类型 |
描述 |
| account |
√ |
string |
客户子账号App_ID |
| token |
√ |
string |
访问令牌：令牌把账号、时间戳、私钥组合通过算法加密，加密方式可选SHA1、SHA256或SM3，post参数传递给秒信平台，秒信平台做解密认证。详细算法公式为：
token = sha1( “account=” + account + “&ts=” + ts+ “&secret=” + secret )
或
token = sha256( “account=” + account + “&ts=” + ts+ “&secret=” + secret )
或
token = sm3( “account=” + account + “&ts=” + ts+ “&secret=” + secret )
注：
1、secret为客户从秒信平台获取的子账号App_SECRET；
2、ts 为系统当前的时间戳 格式为“yyyyMMddHHmmss”，比如“20161220202020”；
3、默认加密方式为SHA1，如需使用SHA256或SM3请联系客服。 |
| ts |
√ |
string |
ts是timestamp的简写，是token参与运算的timestamp参数，式为“yyyyMMddHHmmss”,如“20161220202020”
为了保证服务安全，超过10秒钟的请求会直接返回错误。 |
| requestId |
× |
string |
请求ID，需要每次请求不重复。 |
注释：秒信平台对客户的每次请求都会做协议安全检查，如果不合法直接忽略请求，返回相关的错误代码。
IP地址验证
- 非必须验证选项。如果开启了IP地址验证，非在IP白名单内的请求会直接拒绝。
- 可以在秒信平台后台设置，也可以把需要验证的服务器地址给到秒信平台商务人员。
- 备注：IP白名单可以设置多个。
手机号加密
- 当账号开启了加密提交后，发送接口、回执接口，手机号都通过加密传输。
- 加密方式1 ：AES
- AES密匙，与token计算用的secret相同。
- 加密算法AES/ECB/PKCS5Padding，加密后的2进制转为16进制字符。
- 加密方式2：RSA
- HTTP提交用{提交私匙}加密，平台接收后用{提交公匙}解密；
- 平台用{回执密匙}加密后台推送回执，接收方用{回执公匙}解密。
- 加密方式3 ：SM2
- HTTP提交用{提交私匙}加密，平台接收后用{提交公匙}解密；
- 平台用{回执密匙} 加密后台推送回执，接收方用{回执公匙} 解密;
- 密匙选择未压缩格式，密匙长度为512位。
- 加密方式4 ：SM4
- HTTP提交和平台接收后均使用{提交密匙}加密；
- 加密算法SM4/CBC/PKCS5PADDING, 加密后的2进制转为16进制字符;
- SM4密匙长度为128位。
手机号+内容加密
- 当账号开启了手机号+内容加密提交后，发送接口手机号、短信内容都要通过加密方式传输；回执接口、上行接口，手机号都通过加密传输。
- 单条短信内容提交方式如下：
- content =URLEncoder.encode(URLEncoder.encode(
RSA加密( URLEncoder.encode(content1, "UTF-8")))
+"|||"+
URLEncoder.encode(RSA加密(URLEncoder.encode(content2, "UTF-8"))));
- 多条短信内容提交方式如下：
- 例如：content =URLEncoder.encode(
URLEncoder.encode(RSA加密( URLEncoder.encode(content1, "UTF-8")))
+"|||"+
URLEncoder.encode(RSA加密(URLEncoder.encode(content2, "UTF-8"))));
接口幂等
- 非必须验证选项。如果请求参数中传入了requestId字段，则会进行接口幂等判断，不传不做判断。
- 幂等判断逻辑：秒信平台会在每次接收到请求时，将传入的requestId与客户账号绑定并进行缓存，24小时后过期。若请求中的requsetId已经存在于秒信平台的缓存中，则会直接返回相关错误码。
