车辆数据开放平台

认证

Authorization: Bearer <32位appKey>
Content-Type: application/json

appKey 由平台管理员创建并授权车辆。Key 和逐车授权都必须完整覆盖所查询的自然日。

开放接口

POST/api/v1/vehicles/hydrogen-consumption/query

查询指定车辆的单日用氢量，单位 kg。

POST/api/v1/vehicles/mileage/query

查询指定车辆的单日行驶里程、累计总里程、实际来源协议、车辆源数据时间和投影更新时间，单位 km。

以上两个按日接口的 plateNumbers 可选；省略或传空数组时，返回该应用在查询自然日有效授权的全部车辆。

POST/api/v1/vehicles/mileage/range/query

按最长 366 天区间分页查询逐车逐日里程。首次请求固化授权车辆清单，后续使用 nextCursor 翻页。

两个里程接口均可传 protocolPriority，唯一外部值为 GB32960、MQTT、JT808。逐车逐日按数组顺序选择第一个有效协议；未列出的协议完全禁用。省略字段时保持现有默认选源行为。

查询日没有有效里程但此前存在有效累计里程时，日里程补 0，累计总里程、来源协议和数据时间沿用最近有效统计；updatedAt 显示上一个统计周期的计算时间。

POST/api/v1/vehicles/total-mileage/query

按 VIN 和北京时间查询不晚于指定时刻的最近一条总里程，返回实际采集协议、记录时间和时间差秒数。

总里程协议口径

protocol 不传时严格按 GB32960 > YUTONG_MQTT > JT808 选择首个有数据的协议。接口取不晚于请求时间的最近记录，不跨协议拼接里程。

请求示例

curl -X POST 'https://your-host/api/v1/vehicles/hydrogen-consumption/query' \
  -H 'Authorization: Bearer YOUR_32_CHARACTER_APP_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "plateNumbers": ["粤A12345", "粤B67890"],
    "date": "2026-07-01"
  }'

查询全部授权车辆的单日数据

{
  "date": "2026-07-01"
}

按自定义协议优先级查询单日里程

{
  "plateNumbers": ["粤A12345"],
  "date": "2026-07-01",
  "protocolPriority": ["JT808", "GB32960", "MQTT"]
}

指定时刻总里程

curl -X POST 'https://your-host/api/v1/vehicles/total-mileage/query' \
  -H 'Authorization: Bearer YOUR_32_CHARACTER_APP_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vin": "LA9GG68L2PBAF4790",
    "time": "2026-07-21 09:30:00",
    "protocol": "GB32960"
  }'

车辆区间日里程

curl -X POST 'https://your-host/api/v1/vehicles/mileage/range/query' \
  -H 'Authorization: Bearer YOUR_32_CHARACTER_APP_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "startDate": "2026-07-01",
    "endDate": "2026-07-23",
    "protocolPriority": ["GB32960", "MQTT"],
    "pageSize": 5000
  }'

下一页保持原请求参数不变，并传入上一页 nextCursor；同一次分页查询的 snapshotId 保持不变。

响应示例

车辆单日里程

{
  "code": "SUCCESS",
  "message": "success",
  "data": [{
    "vin": "LNB00000000000001",
    "plateNumber": "粤A12345",
    "date": "2026-07-01",
    "dailyMileageKm": 182.437,
    "totalMileageKm": 12345.679,
    "dataTime": "2026-07-01T23:58:45+08:00",
    "updatedAt": "2026-07-02T05:10:00+08:00",
    "sourceProtocol": "GB32960",
    "status": "NORMAL"
  }],
  "traceId": "b7ff5582ab1a4e13bfb4f10943685599"
}

里程状态为 NORMAL 时，dailyMileageKm、totalMileageKm、dataTime 与 updatedAt 均有值；NO_DATA 时相关数据字段为 null，真实零里程仍为 NORMAL。

车辆区间日里程响应

{
  "code": "SUCCESS",
  "message": "success",
  "data": [{
    "vin": "LNB00000000000001",
    "plateNumber": "粤A12345",
    "date": "2026-07-01",
    "dailyMileageKm": 182.437,
    "dataTime": "2026-07-01T23:58:45+08:00",
    "updatedAt": "2026-07-02T05:10:00+08:00",
    "status": "NORMAL"
  }],
  "snapshotId": "9f8a74efbf9846349ae5676f3a5c0de8",
  "nextCursor": null,
  "traceId": "4ccf63c4e51d4d4ab9107d931783a53e"
}

车辆单日用氢量

{
  "code": "SUCCESS",
  "message": "success",
  "data": [{
    "plateNumber": "粤A12345",
    "date": "2026-07-01",
    "hydrogenConsumptionKg": 12.315,
    "status": "NORMAL"
  }],
  "traceId": "4ccf63c4e51d4d4ab9107d931783a53e"
}

指定时刻总里程响应

{
  "code": "SUCCESS",
  "message": "success",
  "data": {
    "vin": "LA9GG68L2PBAF4790",
    "queryTime": "2026-07-21 09:30:00",
    "totalMileageKm": 12345.678,
    "protocol": "GB32960",
    "protocolInput": "GB32960",
    "mileageMeaning": "车辆仪表盘累计总里程（GB/T 32960整车数据累计里程）",
    "recordTime": "2026-07-21 09:29:45",
    "timeDifferenceSeconds": 15,
    "selectionPolicy": "GB32960 > YUTONG_MQTT > JT808",
    "status": "NORMAL"
  },
  "traceId": "95bddca78133474fa2bf56ecdf758e22"
}

状态与错误码