新源开放数据外部接口-北京现代

开放接口

变更历史

1接入指南

1.1 数据传输规范

1.1.1 数据传输接口

所有数据接口均采用HTTP(S)协议，每个接口的URL均采用以下格式：
http(s)://[地址]/接口名称

• 地址：接口服务所属域名或ip
• 接口名称：所调用接口的名称，具体接口名称见各业务接口描述文档

1.1.2 接口调用方式

1、统一采用Http Post请求，采用JSON方式；
2、传输过程中应包含请求头和消息体；
3、接口请求时，要求将TOKEN存放到请求头中，供双方验证。
4、消息体转换为JSON字符串进行传输

1.1.3 请求头规范

1.1.4 消息体规范

1.1.5 响应体

1.2 密钥的管理和使用

1.2.1 密钥分类

平台加解密支持RSA和AES加密方案，只能二选一。每个用户交互前需要申请分配 消息密钥、认证标识、签名密钥。

1.2.1.1 AES方案

• AES密钥（AES_KEY）: 用于所有接口中业务数据加密
• 认证标识（TOKEN）: 用于身份认证
• 签名密钥（SIGN_SECRET）: 用于数据签名，防止数据被截取篡改
  其中TOKEN需要在请求中传递，其他两项妥善保管不允许在请求中传递

1.2.1.2 RSA方案

• RSA公钥（RAS_PUBLIC_SECRET）: 调用方用来加解密数据
• RSA私钥（RAS_PRIVATE_SECRET）: 接口平台方用来加解密数据
• 认证标识（TOKEN）: 用于身份认证
• 签名密钥（SIGN_SECRET）: 用于数据签名，防止数据被截取篡改
  其中TOKEN需要在请求中传递，其他两项妥善保管不允许在请求中传递

1.2.2 密钥产生

密钥具备随机产生特性，弱密钥会被剔除，所有密钥均由接口管理平台生成。

1.2.3 密钥分发

密钥分发由安全方式进行，通过线下分发，邮件等方式。

1.2.4 密钥使用

1.2.4.1 AES加解密处理

• 调用方对业务数据利用消息密钥（AES_KEY）进行加密；
• 接口平台利用消息密钥（AES_KEY）对消息体中的业务数据解密，校验参数合法性等后续业务处理，具体加解密方法和示例见 AES加解密

1.2.4.2 RSA加解密处理

• 调用方对业务数据利用RSA公钥进行加密；
• 接口平台利用RSA私钥对消息体中的业务数据解密 RSA加解密
• 接口平台处理完请求后获取数据，对数据将利用RSA私钥进行加密 RSA加解密
• 调用方获取接口响应数据后，将利用RSA公钥进行解密 RSA加解密

1.2.4.2 签名处理

签名采用HMAC-MD5算法，利用MD5作为散列函数，通过签名密钥（SIGN_SECRET）对整个消息主体进行签名。
具体签名方法和示例见 签名规范

1.3 签名规范

1.3.1 签名方式

签名采用HMAC-MD5算法，签名流程：

1. 在密钥key后面添加0来创建一个长为B(64字节)的字符串（str）；
2. 将上一步生成的字符串(str) 与ipad（0x36）做异或运算，形成结果字符串（istr）
3. 将数据流data附加到第二步的结果字符串(istr)的末尾
4. 做md5运算于第三步生成的数据流(istr)
5. 将第一步生成的字符串(str) 与opad（0x5c）做异或运算，形成结果字符串（ostr）
6. 再将第四步的结果(istr) 附加到第五步的结果字符串（ostr）的末尾
7. 做md5运算于第6步生成的数据流（ostr），最终输出结果(out)

1.3.2 数据签名示例

1. requestMsg 和 timestamp 参数名和参数值拼接成一个字符串A
2. 用字符串A和签名密钥（SIGN_SECRET）调用签名算法，生成签名值，签名算法见 签名算法

示例:

// 业务参数加密后数据
"requestMsg":"xo6+oObvQ071Qw0U9pZn/+QOJsQYcX4YJGKH+Q1j/gdpKaDseLWzM3mOsT9LdYWKgB/8DcZSynck2s5Xi504fGWxpOM1Cvd8Ne7T6/2r0eU="
// 时间戳
"timestamp"=1508983789981
// 拼接后
String input = "requestMsgxo6+oObvQ071Qw0U9pZn/+QOJsQYcX4YJGKH+Q1j/gdpKaDseLWzM3mOsT9LdYWKgB/8DcZSynck2s5Xi504fGWxpOM1Cvd8Ne7T6/2r0eU=timestamp1508983789981"
// 假设SIGN_SECRET为 "test" 调用签名算法
HmacUtil.byteArrayToHexString(HmacUtil.encryptHMAC(input.getBytes(), "test"))
// 签名结果为
abc48a4267d64921a55c30b33abd18c1

1.3.3 签名算法

    private static final String KEY_MAC = "HmacMD5";
    /**
     * HMAC加密
     *
     * @param data 数据
     * @param key  秘钥
     * @return 签名结果
     */
    public static byte[] encryptHMAC(byte[] data, String key) throws Exception {
        SecretKey secretKey = new SecretKeySpec(key.getBytes(), KEY_MAC);
        Mac mac = Mac.getInstance(secretKey.getAlgorithm());
        mac.init(secretKey);
        return mac.doFinal(data);
    }
    /**
     * byte数组转换为HexString
     */
    public static String byteArrayToHexString(byte[] bytes) {
        StringBuilder sb = new StringBuilder(bytes.length * 2);
        for (byte aByte : bytes) {
            int v = aByte & 0xff;
            if (v < 16) {
                sb.append('0');
            }
            sb.append(Integer.toHexString(v));
        }
        return sb.toString();
    }
    public static void main(String[] args) throws Exception {
        String inputStr = "{\"somek\":\"somev\"}";
        byte[] inputData = inputStr.getBytes();
        String key = "somekey";
        System.out.println(HmacUtil.byteArrayToHexString(HmacUtil.encryptHMAC(inputData, key)));
    }

2. 接口列表

2.1 静态信息同步

2.1.1 单位联系人

外部系统调用此接口，可进行对车联网系统的单位联系人进行新增或修改操作，支持多单位联系人

2.1.1.1 接口地址

/open/v1/unitContactors/add

2.1.1.2 请求定义

请求数据区的类型为List<UnitContactor>，UnitContactor单位联系人定义如下

2.1.1.3 响应定义

响应数据区data类型为List<RespDetail>，RespDetail对象定义如下

2.1.2 个人车主信息

外部系统调用此接口，可进行对车联网系统的个人车主信息进行新增或修改操作，支持多个人车主信息

2.1.2.1 接口地址

/open/v1/vehOwners/add

2.1.2.2 请求定义

请求数据区的类型为List<VehOwners>，VehOwners个人车主定义如下

2.1.3 单位厂商信息

外部系统调用此接口，可进行对车联网系统的单位厂商信息进行新增或修改操作，支持多单位厂商信息

2.1.3.1 接口地址

/open/v1/units/add

2.1.3.2 请求定义

请求数据区的类型为List<Unit>，Unit单位厂商信息定义如下

2.1.3.3 响应定义

响应数据区data类型为List<RespDetail>，RespDetail对象定义如下

2.1.4 车型配置

外部系统调用此接口，可进行对车联网系统的车型配置进行新增或修改操作，支持多车型配置

2.1.4.1 接口地址

/open/v1/vehModel/add

2.1.4.2 请求定义

请求数据区的类型为List<VehModel>，VehModel车型配置定义如下

2.1.4.3 响应定义

响应数据区data类型为List<RespDetail>，RespDetail对象定义如下

2.1.5 SIM卡

外部系统调用此接口，可进行对车联网系统的SIM卡进行新增或修改操作，支持多SIM卡

2.1.5.1 接口地址

/open/v1/sims/add

2.1.5.2 请求定义

请求数据区的类型为List<Sim>，Sim定义如下

2.1.5.3 响应定义

响应数据区data类型为List<RespDetail>，RespDetail对象定义如下

2.1.6 终端型号

外部系统调用此接口，可进行对车联网系统的终端型号进行新增或修改操作，支持多终端型号

2.1.6.1 接口地址

/open/v1/termModels/add

2.1.6.2 请求定义

请求数据区的类型为List<TermModel>，TermModel定义如下

2.1.6.3 响应定义

响应数据区data类型为List<RespDetail>，RespDetail对象定义如下

2.1.7 终端个体

外部系统调用此接口，可进行对车联网系统的 终端个体进行新增或修改操作，支持多终端个体

2.1.7.1 接口地址

/open/v1/termUnits/add

2.1.7.2 请求定义

请求数据区的类型为List<TermUnit>，TermUnit定义如下

2.1.7.3 响应定义

响应数据区data类型为List<RespDetail>，RespDetail对象定义如下

2.1.8 车辆基础信息

外部系统调用此接口，可进行对车联网系统的车辆基础信息进行新增或修改操作，支持多车辆

2.1.8.1 接口地址

/open/v1/vehicleBaseInfo/add

2.1.8.2 请求定义

请求数据区的类型为List<VehicleBaseInfo>，VehicleBaseInfo定义如下

2.1.8.3 响应定义

响应数据区data类型为List<RespDetail>，RespDetail对象定义如下

2.1.9 车辆销售信息

外部系统调用此接口，可进行对车联网系统的车辆基础信息进行新增或修改操作，支持多车辆

2.1.9.1 接口地址

/open/v1/vehicleSellInfo/add

2.1.9.2 请求定义

请求数据区的类型为List<vehicleSellInfo>，vehicleSellInfo定义如下

2.1.9.3 响应定义

响应数据区data类型为List<RespDetail>，RespDetail对象定义如下

2.1.10 车辆运营信息

外部系统调用此接口，可进行对车联网系统的车辆运营信息进行新增或修改操作，支持多车辆

2.1.10.1 接口地址

/open/v1/vehicleOperInfo/add

2.1.10.2 请求定义

请求数据区的类型为List<vehicleOperInfo>，vehicleOperInfo定义如下

2.1.10.3 响应定义

响应数据区data类型为List<RespDetail>，RespDetail对象定义如下

2.1.11 车辆补贴信息

外部系统调用此接口，可进行对车联网系统的车辆补贴信息进行新增或修改操作，支持多车辆

2.1.11.1 接口地址

/open/v1/vehicleSubsidyInfo/add

2.1.11.2 请求定义

请求数据区的类型为List<vehicleSubsidyInfo>，vehicleSubsidyInfo定义如下

2.1.11.3 响应定义

响应数据区data类型为List<RespDetail>，RespDetail对象定义如下

附录

1 响应码定义

2 加解密算法

2.1 AES加解密

 /**
     * 加密
     * @param content 待加密内容
     * @return
     */
 public static String encrypt(String content) {
        try {
            if (StringUtil.isEmpty(content))
                return "";
            String password = AES_KEY;
            KeyGenerator kgen = KeyGenerator.getInstance("AES");
            SecureRandom secureRandom = SecureRandom.getInstance("SHA1PRNG");
            secureRandom.setSeed(password.getBytes());
            kgen.init(128, secureRandom);
            SecretKey secretKey = kgen.generateKey();
            byte[] enCodeFormat = secretKey.getEncoded();
            SecretKeySpec key = new SecretKeySpec(enCodeFormat, "AES");
            Cipher cipher = Cipher.getInstance("AES");// 创建密码器
            byte[] byteContent = content.getBytes("utf-8");
            cipher.init(Cipher.ENCRYPT_MODE, key);// 初始化
            byte[] result = cipher.doFinal(byteContent);
            String str = Base64.encode(result);
            return str; // 加密
        } catch (NoSuchAlgorithmException e) {
//            e.printStackTrace();
        } catch (NoSuchPaddingException e) {
//            e.printStackTrace();
        } catch (InvalidKeyException e) {
//            e.printStackTrace();
        } catch (UnsupportedEncodingException e) {
//            e.printStackTrace();
        } catch (IllegalBlockSizeException e) {
//            e.printStackTrace();
        } catch (BadPaddingException e) {
//            e.printStackTrace();
        }
        return null;
    }
 /**
     * 解密
     * @param str 待解密内容
     * @return
     */
    public static String decrypt(String str) {
        try {
            String password = AES_KEY;
            byte[] content = Base64.decode(str);
            KeyGenerator kgen = KeyGenerator.getInstance("AES");
            SecureRandom secureRandom = SecureRandom.getInstance("SHA1PRNG");
            secureRandom.setSeed(password.getBytes());
            kgen.init(128, secureRandom);
            SecretKey secretKey = kgen.generateKey();
            byte[] enCodeFormat = secretKey.getEncoded();
            SecretKeySpec key = new SecretKeySpec(enCodeFormat, "AES");
            Cipher cipher = Cipher.getInstance("AES");// 创建密码器
            cipher.init(Cipher.DECRYPT_MODE, key);// 初始化
            byte[] result = cipher.doFinal(content);
            return new String(result); // 加密
        } catch (NoSuchAlgorithmException e) {
//            e.printStackTrace();
        } catch (NoSuchPaddingException e) {
//            e.printStackTrace();
        } catch (InvalidKeyException e) {
//            e.printStackTrace();
        } catch (IllegalBlockSizeException e) {
//            e.printStackTrace();
        } catch (BadPaddingException e) {
//            e.printStackTrace();
        }catch (Exception e){
//            e.printStackTrace();
        }
        return "";
    }

2.2 RSA加解密

public class RSAUtil {
    /**
     * 加密算法RSA
     */
    public static final String KEY_ALGORITHM = "RSA";
    /**
     * 签名算法
     */
    public static final String SIGNATURE_ALGORITHM = "MD5withRSA";
    /**
     * RSA最大加密明文大小
     */
    private static final int MAX_ENCRYPT_BLOCK = 117;
    /**
     * RSA最大解密密文大小
     */
    private static final int MAX_DECRYPT_BLOCK = 128;
    /**
     * 公钥加密
     * @param msg 源数据
     * @param publicKey 公钥(BASE64编码)
     * @return
     * @throws Exception
     */
    public static String encryptByPublicKey(String msg, String publicKey) throws Exception {
        byte[] data = msg.getBytes("UTF-8");
        byte[] keyBytes = Base64.decode(publicKey);
        X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(keyBytes);
        KeyFactory keyFactory = KeyFactory.getInstance(KEY_ALGORITHM);
        Key publicK = keyFactory.generatePublic(x509KeySpec);
        // 对数据加密
        Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
        cipher.init(Cipher.ENCRYPT_MODE, publicK);
        int inputLen = data.length;
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        int offSet = 0;
        byte[] cache;
        int i = 0;
        // 对数据分段加密
        while (inputLen - offSet > 0) {
            if (inputLen - offSet > MAX_ENCRYPT_BLOCK) {
                cache = cipher.doFinal(data, offSet, MAX_ENCRYPT_BLOCK);
            } else {
                cache = cipher.doFinal(data, offSet, inputLen - offSet);
            }
            out.write(cache, 0, cache.length);
            i++;
            offSet = i * MAX_ENCRYPT_BLOCK;
        }
        byte[] encryptedData = out.toByteArray();
        out.close();
        String retStr = Base64.encodeToString(encryptedData);
        return retStr;
    }
    /**
     * 私钥解密
     * @param encryptedMsg 已加密数据
     * @param privateKey 私钥(BASE64编码)
     * @return
     * @throws Exception
     */
    public static String decryptByPrivateKey(String encryptedMsg, String privateKey)throws Exception {
        byte[] keyBytes = Base64.decode(privateKey);
        PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(keyBytes);
        KeyFactory keyFactory = KeyFactory.getInstance(KEY_ALGORITHM);
        Key privateK = keyFactory.generatePrivate(pkcs8KeySpec);
        Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
        cipher.init(Cipher.DECRYPT_MODE, privateK);
        byte[] encryptedData = Base64.decode(encryptedMsg);
        int inputLen = encryptedData.length;
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        int offSet = 0;
        byte[] cache;
        int i = 0;
        // 对数据分段解密
        while (inputLen - offSet > 0) {
            if (inputLen - offSet > MAX_DECRYPT_BLOCK) {
                cache = cipher.doFinal(encryptedData, offSet, MAX_DECRYPT_BLOCK);
            } else {
                cache = cipher.doFinal(encryptedData, offSet, inputLen - offSet);
            }
            out.write(cache, 0, cache.length);
            i++;
            offSet = i * MAX_DECRYPT_BLOCK;
        }
        byte[] decryptedData = out.toByteArray();
        out.close();
        return new String(decryptedData);
    }
    /**
     * 私钥加密
     * @param msg 源数据
     * @param privateKey 私钥(BASE64编码)
     * @return
     * @throws Exception
     */
    public static String encryptByPrivateKey(String msg, String privateKey)throws Exception {
        byte[] data = msg.getBytes("UTF-8");
        byte[] keyBytes = Base64.decode(privateKey);
        PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(keyBytes);
        KeyFactory keyFactory = KeyFactory.getInstance(KEY_ALGORITHM);
        Key privateK = keyFactory.generatePrivate(pkcs8KeySpec);
        Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
        cipher.init(Cipher.ENCRYPT_MODE, privateK);
        int inputLen = data.length;
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        int offSet = 0;
        byte[] cache;
        int i = 0;
        // 对数据分段加密
        while (inputLen - offSet > 0) {
            if (inputLen - offSet > MAX_ENCRYPT_BLOCK) {
                cache = cipher.doFinal(data, offSet, MAX_ENCRYPT_BLOCK);
            } else {
                cache = cipher.doFinal(data, offSet, inputLen - offSet);
            }
            out.write(cache, 0, cache.length);
            i++;
            offSet = i * MAX_ENCRYPT_BLOCK;
        }
        byte[] encryptedData = out.toByteArray();
        out.close();
        String retStr = Base64.encodeToString(encryptedData);
        return retStr;
    }
    /**
     * 公钥解密
     * @param encryptedMsg 已加密数据
     * @param publicKey 公钥(BASE64编码)
     * @return
     * @throws Exception
     */
    public static String decryptByPublicKey(String encryptedMsg, String publicKey)throws Exception {
        byte[] keyBytes = Base64.decode(publicKey);
        X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(keyBytes);
        KeyFactory keyFactory = KeyFactory.getInstance(KEY_ALGORITHM);
        Key publicK = keyFactory.generatePublic(x509KeySpec);
        Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
        cipher.init(Cipher.DECRYPT_MODE, publicK);
        byte[] encryptedData = Base64.decode(encryptedMsg);
        int inputLen = encryptedData.length;
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        int offSet = 0;
        byte[] cache;
        int i = 0;
        // 对数据分段解密
        while (inputLen - offSet > 0) {
            if (inputLen - offSet > MAX_DECRYPT_BLOCK) {
                cache = cipher.doFinal(encryptedData, offSet, MAX_DECRYPT_BLOCK);
            } else {
                cache = cipher.doFinal(encryptedData, offSet, inputLen - offSet);
            }
            out.write(cache, 0, cache.length);
            i++;
            offSet = i * MAX_DECRYPT_BLOCK;
        }
        byte[] decryptedData = out.toByteArray();
        out.close();
        return new String(decryptedData);
    }
}

3 数据项定义