187 lines
8.4 KiB
HTML
187 lines
8.4 KiB
HTML
<!doctype html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
<title>车辆数据开放平台</title>
|
||
<style>
|
||
:root{color-scheme:light;--ink:#13213c;--muted:#60708c;--line:#dce3ed;--blue:#1768e5;--soft:#f4f7fb}
|
||
*{box-sizing:border-box}body{margin:0;font:15px/1.65 system-ui,-apple-system,"PingFang SC","Microsoft YaHei",sans-serif;color:var(--ink);background:#fff}
|
||
main{max-width:980px;margin:auto;padding:48px 24px 80px}header{padding:34px;border:1px solid var(--line);border-radius:18px;background:linear-gradient(135deg,#f5f9ff,#eef4ff)}
|
||
h1{margin:0 0 10px;font-size:34px}h2{margin:42px 0 14px;font-size:22px}h3{margin:24px 0 10px;font-size:17px}
|
||
p{margin:8px 0;color:var(--muted)}a{color:var(--blue)}nav{display:flex;gap:12px;flex-wrap:wrap;margin-top:20px}
|
||
nav a{padding:8px 13px;border:1px solid #b9cef0;border-radius:9px;text-decoration:none;background:#fff}
|
||
code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}pre{overflow:auto;padding:18px;border-radius:12px;background:#101827;color:#e9f1ff;font-size:13px}
|
||
table{width:100%;border-collapse:collapse}th,td{text-align:left;padding:11px;border-bottom:1px solid var(--line);vertical-align:top}th{background:var(--soft)}
|
||
.method{display:inline-block;margin-right:8px;padding:2px 8px;border-radius:6px;background:#dff3e5;color:#136b35;font-weight:700}
|
||
.note{padding:14px 16px;border-left:4px solid var(--blue);background:var(--soft);color:var(--muted)}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<main>
|
||
<header>
|
||
<h1>车辆数据开放平台</h1>
|
||
<p>面向合作方开放车辆单日用氢量、单日里程、区间日里程和指定时刻总里程。接口使用独立的 32 位 appKey 认证。</p>
|
||
<nav>
|
||
<a href="/open-api/swagger/">Swagger 在线调试</a>
|
||
<a href="/open-api/openapi.yaml">下载 OpenAPI 3.0</a>
|
||
</nav>
|
||
</header>
|
||
|
||
<h2>认证</h2>
|
||
<pre>Authorization: Bearer <32位appKey>
|
||
Content-Type: application/json</pre>
|
||
<p class="note">appKey 由平台管理员创建并授权车辆。Key 和逐车授权都必须完整覆盖所查询的自然日。</p>
|
||
|
||
<h2>开放接口</h2>
|
||
<h3><span class="method">POST</span>/api/v1/vehicles/hydrogen-consumption/query</h3>
|
||
<p>查询指定车辆的单日用氢量，单位 kg。</p>
|
||
<h3><span class="method">POST</span>/api/v1/vehicles/mileage/query</h3>
|
||
<p>查询指定车辆的单日行驶里程、累计总里程、实际来源协议、车辆源数据时间和投影更新时间，单位 km。</p>
|
||
<p class="note">以上两个按日接口的 plateNumbers 可选；省略或传空数组时，返回该应用在查询自然日有效授权的全部车辆。</p>
|
||
<h3><span class="method">POST</span>/api/v1/vehicles/mileage/range/query</h3>
|
||
<p>按最长 366 天区间分页查询逐车逐日里程。首次请求固化授权车辆清单，后续使用 nextCursor 翻页。</p>
|
||
<p class="note">两个里程接口均可传 protocolPriority，唯一外部值为 GB32960、MQTT、JT808。逐车逐日按数组顺序选择第一个有效协议；未列出的协议完全禁用。省略字段时保持现有默认选源行为。</p>
|
||
<p class="note">查询日没有有效里程但此前存在有效累计里程时，日里程补 0，累计总里程、来源协议和数据时间沿用最近有效统计；updatedAt 显示上一个统计周期的计算时间。</p>
|
||
<h3><span class="method">POST</span>/api/v1/vehicles/total-mileage/query</h3>
|
||
<p>按 VIN 和北京时间查询不晚于指定时刻的最近一条总里程，返回实际采集协议、记录时间和时间差秒数。</p>
|
||
|
||
<h2>总里程协议口径</h2>
|
||
<table>
|
||
<thead><tr><th>protocol 唯一规范值</th><th>总里程含义</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>GB32960</td><td>车辆仪表盘累计总里程，对应 GB/T 32960 整车数据累计里程</td></tr>
|
||
<tr><td>YUTONG_MQTT</td><td>车辆仪表盘或车端控制器累计总里程，由 MQTT 平台上报</td></tr>
|
||
<tr><td>JT808</td><td>定位终端累计里程，由 GPS/终端侧计算，不等同于车辆仪表盘里程</td></tr>
|
||
</tbody>
|
||
</table>
|
||
<p class="note">protocol 不传时严格按 GB32960 > YUTONG_MQTT > JT808 选择首个有数据的协议。接口取不晚于请求时间的最近记录，不跨协议拼接里程。</p>
|
||
|
||
<h2>请求示例</h2>
|
||
<pre>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"
|
||
}'</pre>
|
||
|
||
<h3>查询全部授权车辆的单日数据</h3>
|
||
<pre>{
|
||
"date": "2026-07-01"
|
||
}</pre>
|
||
|
||
<h3>按自定义协议优先级查询单日里程</h3>
|
||
<pre>{
|
||
"plateNumbers": ["粤A12345"],
|
||
"date": "2026-07-01",
|
||
"protocolPriority": ["JT808", "GB32960", "MQTT"]
|
||
}</pre>
|
||
|
||
<h3>指定时刻总里程</h3>
|
||
<pre>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"
|
||
}'</pre>
|
||
|
||
<h3>车辆区间日里程</h3>
|
||
<pre>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
|
||
}'</pre>
|
||
<p class="note">下一页保持原请求参数不变，并传入上一页 nextCursor；同一次分页查询的 snapshotId 保持不变。</p>
|
||
|
||
<h2>响应示例</h2>
|
||
<h3>车辆单日里程</h3>
|
||
<pre>{
|
||
"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"
|
||
}</pre>
|
||
<p class="note">里程状态为 NORMAL 时，dailyMileageKm、totalMileageKm、dataTime 与 updatedAt 均有值；NO_DATA 时相关数据字段为 null，真实零里程仍为 NORMAL。</p>
|
||
<h3>车辆区间日里程响应</h3>
|
||
<pre>{
|
||
"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"
|
||
}</pre>
|
||
<h3>车辆单日用氢量</h3>
|
||
<pre>{
|
||
"code": "SUCCESS",
|
||
"message": "success",
|
||
"data": [{
|
||
"plateNumber": "粤A12345",
|
||
"date": "2026-07-01",
|
||
"hydrogenConsumptionKg": 12.315,
|
||
"status": "NORMAL"
|
||
}],
|
||
"traceId": "4ccf63c4e51d4d4ab9107d931783a53e"
|
||
}</pre>
|
||
|
||
<h3>指定时刻总里程响应</h3>
|
||
<pre>{
|
||
"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"
|
||
}</pre>
|
||
|
||
<h2>状态与错误码</h2>
|
||
<table>
|
||
<thead><tr><th>HTTP</th><th>code</th><th>说明</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>200</td><td>SUCCESS</td><td>查询成功；无统计数据的车辆以 NO_DATA 返回</td></tr>
|
||
<tr><td>400</td><td>INVALID_REQUEST</td><td>请求格式、车牌或数量不正确</td></tr>
|
||
<tr><td>400</td><td>INVALID_DATE_FORMAT</td><td>日期不是 yyyy-MM-dd</td></tr>
|
||
<tr><td>400</td><td>INVALID_DATETIME_FORMAT</td><td>时间不是 yyyy-MM-dd HH:mm:ss</td></tr>
|
||
<tr><td>401</td><td>UNAUTHORIZED</td><td>appKey 不存在、停用或过期</td></tr>
|
||
<tr><td>403</td><td>FORBIDDEN</td><td>Key 或车辆授权未覆盖查询自然日</td></tr>
|
||
<tr><td>500</td><td>INTERNAL_ERROR</td><td>服务内部异常</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</main>
|
||
</body>
|
||
</html>
|