新源开放数据外部接口-企业 1.6

接口文档

变更历史

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 密钥分类

每个用户交互前需要申请分配 消息密钥、认证标识、签名密钥：

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

1.2.2 密钥产生

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

1.2.3 密钥分发

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

1.2.4 密钥使用

1.2.4.1 加解密处理

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

1.2.4.2 签名处理

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

1.3 数据加解密

1.3.1 加解密方法

数据传输加解密采用对称加解密AES-128算法，对业务数据进行加密传输。

1.3.2 加解密示例

requestMsg为请求内容体转化json之后，再进行AES加密得到的字符串，不同的aes-key加密得到的结果不一样，加密算法见 加密算法，示例：

//原始的请求内容体
{"dataIds":"2615,2202","vins":"LNBSCB3F0FD120736,LNBSCB3F1FD120728"}
// 加密后的内容体
"requestMsg": "xo6+oObvQ071Qw0U9pZn/+QOJsQYcX4YJGKH+Q1j/gdpKaDseLWzM3mOsT9LdYWKgB/8DcZSynck2s5Xi504fGWxpOM1Cvd8Ne7T6/2r0eU="

1.3.3 加密算法

 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;
    }

1.3.4 解密算法

 /**
     * 解密
     * @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 "";
    }

1.4 签名规范

1.4.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.4.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.4.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 实时数据

发起请求,应将参数的requestMsg进行加密，然后组合成完整的请求参数。

• 请求路径

  /api/v1/vehicle/realData

• 输入参数

请求内容体定义

{
    "requestMsg": "xo6+oObvQ071Qw0U9pZn/+QOJsQYcX4YJGKH+Q1j/gdpKaDseLWzM3mOsT9LdYWKgB/8DcZSynck2s5Xi504fGWxpOM1Cvd8Ne7T6/2r0eU=",  //这里的requestMsg为请求内容体转化json之后，再进行AES加密得到的字符串，不同的aes-key加密得到的结果不一样
    "sign": ""
}
//原始的请求内容体
{"dataIds":"2615,2202","vins":"LNBSCB3F0FD120736,LNBSCB3F1FD120728"}

• 输出参数

{
    "code": 0,
    "msg": "查询成功",
    "data": {
        "vin1": {
            "2502": "40.111",
            "2503": "120.0"
        },
        "vin2": {
            "2502": "40.111",
            "2503": "120.5"
        },
        "vin3": {
            "2502": "40.111",
            "2503": "120.5"
        }
    }
}

2.1.2 历史数据

• 请求路径

  /api/v1/vehicle/hisData

• 输入参数

请求内容体定义

{
    "dataIds":"2502,2503",
    "vins":"LNBSCB3F0FD120736",
    "startTime":"2016-10-10 10:22:00",
    "endTime":"2016-10-10 10:23:00",
}

• 输出参数

{
    "code": 0,
    "msg": "查询成功",
    "data": {
        "total": "3",
        "rows":[
            {"time":"2016-10-10:22:00","2502":"11.00000","2503":"22.00"},
            {"time":"2016-10-10:22:00","2502":"11.00000","2503":"22.00"},
            {"time":"2016-10-10:22:00","2502":"11.00000","2503":"22.00"},
        ]
    }
}

2.1.3 车辆静态数据

发起请求,应将参数的requestMsg进行加密，然后组合成完整的请求参数。

• 请求路径

  /api/v1/vehicle/static

• 输入参数

请求内容体定义

//原始请求内容体
{
    "size":2,
    "rows": ["LNBSCB3F0FD120736","LNBSCB3F1FD120728" ]
}

• 输出参数

{
    "code": 0,
    "msg": "OK",
    "rows": {
        "LNBSCB3F0FD120736":{
            "licensePlate":"京A12346", //车牌号 
            "vin":"LNBSCB3F0FD120736", //VIN        
            "rule": //规约 0：GB/T 32960-3 1：DB11-北京地标 
            "useUnit":"郑州客车股份有限公司", //车辆运营单位
            "storePoint":"郑州客车股份有限公司", //车辆存放地点
            "manuUnit":"郑州客车股份有限公司(汽车厂商)", //车辆制造厂商
            "vehType":"电动公交车", //车辆类别
            "vehModel":"ZK6805BEVG17A", //车辆类型
            "termUnit":"深圳科技股份有限公司", //终端厂商
            "termModel":"YT_G2_v02/S_v02", //终端类型
            "driveMode":"0", //驱动方式 0：纯电动 1：油电混合...
            "vehArea":"深圳", //车辆销售区域
            "ownerPeople":"小李", //车主姓名
            "connecterPeople":"小张", //联系人姓名 
            "simCard":"1.0", //SIM卡号    
            "factoryDate":"2017-04-11", //出厂日期
            "firstReg":"2017-04-11", //首次上线时间
            "singleMileageSum":"0" //单次行驶里程总和
            "mileageSum":"0" //累计行驶里程
        }
        "LNBSCB3F1FD120728":{
            "licensePlate":"京A12347", //车牌号 
            "vin":"LNBSCB3F1FD120728", //VIN
            ......
        }
    }
}

2.1.4 通过VIN查询报文（已过时）

• 请求路径

  /api/v1/vehicle/protocolByVin

• 输入参数

请求内容体定义

//原始的请求内容体
{
    "vin":"LNBSC123456767",
    "startTime":"2016-10-10 10:22:00",
    "endTime":"2016-10-10 10:23:00",
    "page":1,
    "pageRecorders":10,
    "type":""
    //"":全部 "1":车辆登入 "2":实时信息上报 "3":补发信息上报 "4":车辆登出 "5":平台登入 "6":平台登出 "7":心跳 "8":终端校时(国标)
}

• 输出参数

{
    "code": 0,
    "msg": "查询成功",
    "data": {
        [
             {
                "vin": "LA95T7276H1LC0031",//VIN 
                "srvrRecvTime": "2017-10-30 17:24:25",//服务器接收时间 
                "recvTime": "2017-10-30 17:24:41",//报文时间
                "type": "车辆登出",//类型
                "verify": "失败",//校验 
                "dataLength": 33,//报文长度 
                "data": "232304FE4C413935543732373648314C4330303331010008110A1E1118290003F0"//原始报文
            },
             {
                "vin": "LVVDB17B5FB063266",//VIN 
                ......
            }
        ]
    }
}

2.1.5 报文查询

@since 1.6

• 请求路径

  /api/v1/vehicle/protocol

• 输入参数

请求内容体定义

parmas为map对象

//原始的请求内容体
{
    "page":1,
    "pageSize":10,
    "params":{
        "vin":"LNBSC123456767",
        "startTime":"2016-10-10 10:22:00",
        "endTime":"2016-10-10 10:23:00",
        "type": null
    }
    //"":全部 1:车辆登入 2:实时信息上报 3:补发信息上报 4:车辆登出 5:平台登入 6:平台登出 7:心跳 8:终端校时(国标)
}

• 输出参数

{
    "code": 0,
    "msg": "查询成功",
    "data": {
        "total" : 500,
        "data"
        [
             {
                "vid": "LA95T7276H1LC0031",//VIN 
                "srvrRecvTime": "2017-10-30 17:24:25",//服务器接收时间 
                "recvTime": "2017-10-30 17:24:41",//报文时间
                "type": 1,//类型
                "verify": 0,//校验 
                "dataLength": 33,//报文长度 
                "data": "232304FE4C413935543732373648314C4330303331010008110A1E1118290003F0"//原始报文
            },
             {
                "vin": "LVVDB17B5FB063266",//VIN 
                ......
            }
        ]
    }
}

2.2 故障报警相关

2.2.1 故障推送

车网平台车辆故障开始和故障结束，会主动向订阅故障通知的第三方平台推送故障消息。

• 推送路径

由接收方提供

• 输入参数

请求内容体定义

• 输出参数

{
    "code": 0,
    "msg": "推送成功",
    "data": null
}

附录

响应码定义

数据项定义