第三方接口鉴权加密方式

接口对接规范

一、概述

本规范旨在定义所有系统的接口对接标准，以确保接口调用的正确性、安全性和可维护性。接口遵循Restful设计风格，采用HTTP请求方法（如GET、POST、PUT、DELETE等）来定义不同的操作类型。

二、接口定义

2.1 接口URL

●接口URL应简洁明了，遵循公司或项目的命名规范。
●使用HTTPS协议，确保数据传输的安全性。
●接口URL路径应反映资源的层次结构，路径规范 /{版本}/api/{业务类型}/{方法名}，例如/v1/api/store/getlist。

2.2 请求方法

●GET：用于获取资源；
●POST：用于创建资源；
●PUT：用于更新资源（完全替换）；
●DELETE：用于删除资源；
●其他HTTP方法（如PATCH）可根据需要选用，但应明确说明其用途。

2.3 请求头

字段名 是否必填 类型 说明
timestamp 是 int64 时间戳字段，东八区，精确到秒， 时间戳过期时间为60秒钟
appId 是 string 请求方应用标识，需要向DMS申请
nonce 是 string 随机字符串，用于区别是否为重复请求， 同一应用（相同appId）在1小时内此字段不能有相同
sign 是 string 签名，详见4.1 鉴权与授权

2.4 请求体

●对于POST、PUT等需要请求体的方法，应使用JSON格式作为请求体的媒体类型。
●请求体中的字段应明确说明其含义、数据类型和是否必填。
●请求体不区分大小写

2.5 响应体

响应体使用JSON格式。
响应体应包含状态码（如HTTP状态码）、状态信息（描述操作结果的简短文本）和数据体（包含具体数据的JSON对象）。
数据体中的字段应明确说明其含义、数据类型和是否为空。
{
“message”: “成功”,
“code”: 200,
“data”: {}
}

字段名称 是否必填 类型 说明
message 是 string 状态信息描述
code 是 int32 状态码
data 否 JSON对象 根据具体的业务反馈不同的对象

三、错误处理

3.1 状态码

使用标准的HTTP状态码来表示操作结果。
●2xx系列表示成功。
●4xx系列表示客户端错误（如请求参数错误、身份验证失败等）。
●5xx系列表示服务器错误（如内部服务器错误、数据库连接失败等）。
●7xx系统标识业务逻辑错误。
具体错误码
状态码 说明
200 接口响应正确，逻辑处理成功
401 权限错误， 头部缺少正确appId
402 时间戳错误， 头部时间戳字段【timestamp】时间错误，要求误差不能超过30秒，东八区
403 重复请求，头部随机数字段【nonce】重复，同一应用（相同appId）在1小时内此字段不能有相同
405 签名错误，生成的签名字符串不正确，详细签名算法见4.1
500 系统异常，系统出现没有预知到异常
700 业务逻辑错误

3.2 错误信息

在响应体中，应包含详细的错误信息，以便调用方了解错误原因。
错误信息应包含错误码（唯一标识错误类型）、错误描述（详细描述错误原因）和可能的解决方案（如有）。

四、安全性

4.1 鉴权与授权

接口使用签名算法支持鉴权和授权功能，确保只有合法的用户才能访问接口。
签名算法：
1.组织加密前的字符串：通过对头部参数timestamp、appId、nonce的key和value通过等号相连接形成一个新的数组
[timestamp=XXX,appId=XXX,nonce=XXX]，然后将此数组进行ASCII升序进行排序，然后通过&符号相连接形成一个新的字符串，最后拼接&secret=xxx，并转换为小写形成最终的字符串：appid=xxx&nonce=xxx&timestamp=xxx&secret=xxx
2.加密：使用MD5加密上诉步骤最终的字符串，生成32位小写密文
代码示例：

Java语言示例
    public static String generateSignature(long timestamp, String appId, String nonce, String secret) {  
              Map<String, String> parameters = new HashMap<>();  
        parameters.put("timestamp", String.valueOf(timestamp));  
        parameters.put("appId", appId);  
        parameters.put("nonce", nonce);  
        // 注意：AppSecret不会作为请求的一部分发送，而是在服务器端用于验证签名  
          // 由于map是无序的，这里主要是对key进行排序（字典序）
        Set<String> keySet = data.keySet();
        String[] keyArr = keySet.toArray(new String[keySet.size()]);
        Arrays.sort(keyArr);
        StringBuilder sbd = new StringBuilder();
        for (String k : keyArr) {
            if (StrUtil.isNotEmpty(data.getStr(k))) {
                sbd.append(k + "=" + data.getStr(k) + "&");
            }
        }
        // secret最后拼接
        sbd.append("secret=").append(secret);
        MD5.create().digestHex(sbd.toString());
        System.out.println(sbd);
        return DigestUtil.md5Hex(sbd.toString());
   
    }

4.2 数据加密

对于敏感数据（如用户密码、支付信息等），应进行加密处理，确保数据传输的安全性。加密算法采用AES 128位，私钥为secret，需要向DMS以及更应用系统申请。

4.3 访问控制

根据业务需求，依托接口平台设置不同的访问控制策略，如IP白名单、接口调用频率限制等。

五、接口文档

●接口文档应详细描述每个接口的URL、请求方法、请求头、请求体、响应体、错误处理和安全性要求。
●接口文档应定期更新，以反映接口的变更和新增功能。
●接口将统一在接口平台注册，并完善接口平台文档，并提供在线或离线查看方式。

六、测试与验证

在接口开发完成后，应进行单元测试、集成测试和性能测试，确保接口的正确性和性能。
在接口上线前，应进行线上验证，确保接口在实际环境中的稳定性和可靠性。