接口文档

面向合作方开放车辆用氢量、里程、实时状态及加氢车辆停留核验数据。每个接口独立说明请求参数、成功返回与异常情况。

Base URL https://open.d.lnoneos.com

认证与授权

所有接口均使用平台管理员签发的 32 位 appKey。appKey 有效期及车辆授权期必须完整覆盖查询时间。

请求头

Authorization: Bearer <YOUR_APP_KEY>
Content-Type: application/json

授权边界：车牌是否可省略以各接口参数表为准；综合运营查询车牌可选，省略或空数组返回所选时间范围内均有效授权的全部车辆，不受 200 辆限制；显式指定车牌最多 200 项。日统计授权覆盖查询自然日，实时授权覆盖请求时点，综合查询先校验全部所选范围。综合查询返回紧凑 JSON；下方示例已格式化。

请求体样例

所有接口使用 Content-Type: application/json。以下 JSON 可直接复制；未列出的可选字段可省略。

综合运营数据

/vehicles/operating-data/query

{
  "dailyDate": "2026-10-23",
  "plateNumbers": [
    "粤A09635F"
  ],
  "dataTypes": [
    "REALTIME",
    "DAILY_MILEAGE",
    "DAILY_HYDROGEN"
  ],
  "protocolPriority": [
    "GB32960",
    "MQTT",
    "JT808"
  ]
}

车辆单日用氢量

/vehicles/hydrogen-consumption/query

{
  "date": "2026-08-06",
  "plateNumbers": ["浙F06618F"]
}

车辆单日里程

/vehicles/mileage/query

{
  "date": "2026-08-06",
  "plateNumbers": ["浙F06618F"],
  "protocolPriority": ["GB32960", "MQTT", "JT808"]
}

车辆区间日里程

/vehicles/mileage/range/query

{
  "startDate": "2026-08-01",
  "endDate": "2026-08-06",
  "pageSize": 100
}

指定时刻总里程

/vehicles/total-mileage/query

{
  "vin": "LA9GG68L2PBAF4790",
  "time": "2026-08-06 10:30:00",
  "protocol": "GB32960"
}

实时位置与状态

/vehicles/realtime/query

{
  "plateNumbers": ["浙F06618F"]
}

加氢车辆停留核验

/vehicles/stationary/query

{
  "startTime": "2026-08-06 10:00:00",
  "endTime": "2026-08-06 12:00:00",
  "longitude": 120.752312,
  "latitude": 30.746281,
  "coordinateSystem": "GCJ02",
  "radiusMeters": 8
}

加氢站地图点位

/hydrogen-stations/query

{
  "province": "浙江省",
  "city": "嘉兴市",
  "cooperateOnly": true
}

历史时刻剩余氢质量 · 1.10.0

POST/api/v1/vehicles/hydrogen-remaining/history/query

仅查询2026-08-01起的真实历史 event_time，不使用未来采样、实时值或日用氢量填补。最近氢相关帧异常或字段不全时显式返回，不跳过它找旧正常值。

请求参数

字段	必填	说明
queries	是	1–200项
queries[].requestId	是	本批唯一非空，最多128字节，原样回显
queries[].vin / time	是	VIN规范化大写17位且不含I/O/Q；北京时间yyyy-MM-dd HH:mm:ss，不可未来或早于2026-08-01
queries[].protocol	否	GB32960 / YUTONG_MQTT / JT808；省略固定GB32960，后两者当前UNSUPPORTED，不跨协议回退
maxTimeDifferenceSeconds	否	整数0–300，默认300；0要求精确命中

应用与逐车授权需同时覆盖查询时刻和采样时刻（结束时间不含端点）；FORBIDDEN不泄露采样元数据。当前appKey无效/过期为401，非法结构400。

请求示例（非真实读数）

{
  "queries": [{
    "requestId": "job-start",
    "vin": "LA9GG68L2PBAF4773",
    "time": "2026-08-03 16:02:43",
    "protocol": "GB32960"
  }],
  "maxTimeDifferenceSeconds": 300
}

合法批量HTTP200/SUCCESS，逐项状态判断：NORMAL、NO_DATA、MISSING、STALE、UNSUPPORTED、INVALID、FORBIDDEN、ERROR。非NORMAL质量null，不丢项，不补零。

每app每实例30批/60秒，最多2个并发批；429读取Retry-After秒后重试。整批9秒预算、4个工作协程，超时项ERROR而不是NO_DATA。200项是结构上限，不保证200个不同点均能按时完成；建议从20个不同点开始，超时缩小批量并退避重试。

历史容量需要历史适用版本；当前表不能回套历史。当前只有REPORTED质量可用，缺历史容量版本时不估算，返回MISSING。同批按规范化VIN+time+protocol去重，同点共享单次查询/授权结果和来源版本，所有requestId独立回显；不同点仍是非原子快照，保留各项版本和原始证据。质量保留原精度，Seeker自行计算两端净减少量并在负差值时归零。

车辆综合运营数据批量查询

POST /api/v1/vehicles/operating-data/query

文档 V1.5 · OpenAPI 1.12.2 · 2026-10-26 · 随当前服务版本发布

一次请求按需返回实时、单日里程及单日用氢。SIMPLE模式固定9字段；默认FULL保留完整来源、质量及时间。两种模式共用授权和批量查询，不增加数据库查询，不表示共同快照。

精简模式 SIMPLE · 固定 9 字段

请求显式增加 responseMode: "SIMPLE"。省略或传 FULL 保留已上线完整响应。外层字段保持一致，data 每辆车仅返回下表9项，未知或未选字段显式 null。

{
  "responseMode": "SIMPLE",
  "dailyDate": "2026-10-23",
  "plateNumbers": [
    "沪A01933F"
  ]
}

字段	类型	返回规则
plateNumber	string	规范化后的请求车牌，保持请求顺序。
reportTime	string \| null	实时选中主记录的event_time，真实源采集/上报时刻；缺失为null，不使用平台接收、投影更新或请求时间替代。FULL recordTime保持原兼容口径。
offline	boolean \| null	主实时记录可用且online已知时取反；无记录或查询失败为null，不能当成离线。
remainingHydrogenKg	number \| null	剩余氢量kg。仅kg字段NORMAL、数值有效且有可信采集时间，响应时不超过300秒并不晚于服务时点1分钟时展示；陈旧/缺失/异常为null，真实0保留。
socPercent	number \| null	动力电池SOC百分比；实时主记录有效且数值在0–100内，未知为null。
totalMileageKm	number \| null	实时主记录累计里程km；不使用日统计累计值兜底。
dailyHydrogenConsumptionKg	number \| null	queryDate用氢量kg；子查询成功、status=NORMAL、qualityStatus=OK时返回有效非负数值，否则null。日内值可为PRELIMINARY，不保证终报。
dailyMileageKm	number \| null	queryDate里程km；执行成功、业务NORMAL且非CARRIED_FORWARD时返回有效非负数值；实测零保留，结转补零和异常为null。
hydrogenConsumptionPer100KmKg	number \| null	kg/100km预留字段；当前缺少可比区间完整证据，固定null，不参与summary计数。禁止调用方以同日日指标直接相除。

精简响应示例（合成数据）

{
  "code": "SUCCESS",
  "message": "success",
  "traceId": "f924a83d8a93475bac26b054305fc427",
  "queryDate": "2026-10-23",
  "timezone": "Asia/Shanghai",
  "requestAt": "2026-10-23T12:00:00+08:00",
  "generatedAt": "2026-10-23T12:00:01+08:00",
  "data": [
    {
      "plateNumber": "沪A01933F",
      "reportTime": "2026-10-23T11:59:30+08:00",
      "offline": false,
      "remainingHydrogenKg": 16,
      "socPercent": 78.8,
      "totalMileageKm": 80707,
      "dailyHydrogenConsumptionKg": 4.003,
      "dailyMileageKm": 128,
      "hydrogenConsumptionPer100KmKg": null
    }
  ],
  "summary": {
    "requestedCount": 1,
    "returnedCount": 1,
    "successCount": 1,
    "partialSuccessCount": 0,
    "failedCount": 0
  }
}

summary：仅统计所选类型的展示字段：实时5项、日里程1项、日用氢1项。全部有值计入successCount；部分有值计入partialSuccessCount；全部为空计入failedCount。车牌与预留百公里氢耗不参与；未选类型也不参与。真实0、offline=false均为有效值。null及failedCount不能直接作为自动重试依据。FULL模式原有执行统计不变。

离线不触发缓存或历史兜底；最新主记录自带reportTime，在线状态不决定SOC和总里程是否存在。剩余氢量额外执行300秒时效门槛。任何源失败只影响对应字段，不能把offline未知写成true。

当前没有可证明可比区间的正式百公里氢耗算法，因此hydrogenConsumptionPer100KmKg固定null。不能因为同一天有氢量和里程就自行相除。日内用氢可能是初步统计，正式对账继续使用FULL查询质量、阶段和来源。

请求参数

{
  "dailyDate": "2026-10-23",
  "plateNumbers": [
    "粤A09635F"
  ],
  "dataTypes": [
    "REALTIME",
    "DAILY_MILEAGE",
    "DAILY_HYDROGEN"
  ],
  "protocolPriority": [
    "GB32960",
    "MQTT",
    "JT808"
  ]
}

参数	必填	规则
responseMode	否	FULL / SIMPLE；省略默认FULL，显式空字符串或null不合法。SIMPLE返回固定9字段，未选类型字段也为null。
plateNumbers	否	省略或传空数组时查询所选时间范围内均有效授权的全部车辆，按车牌排序；无有效授权车辆返回空数组。省略或空数组不受 200 辆限制，不分页、不截断；显式指定最多 200 项，超出返回 HTTP 400 / BATCH_SIZE_EXCEEDED。指定时每项为字符串，去首尾空白、转大写后非空、最多 32 个 Unicode 字符；不允许重复。
dailyDate	条件必填	选择任一日统计时必填，严格 yyyy-MM-dd，不晚于北京时间当日。仅实时可省略；若提供仍校验，但不影响实时选源或实时授权，queryDate 仍为 null。
dataTypes	否	省略默认 REALTIME、DAILY_MILEAGE、DAILY_HYDROGEN 全部；显式数组非空、不重复、不接受未知枚举。未选数据块从响应中省略。
protocolPriority	否	仅选择 DAILY_MILEAGE 时可提供。非空、不重复，仅 GB32960、MQTT、JT808。未列出的协议不兜底；省略沿用原里程选源。对实时及用氢不生效。

请求体最大 64 KiB。拒绝未知字段、显式 null、非法类型、多个 JSON 根对象，以及规范化后重复车牌。无新增固定历史下界；可查询日期不代表保留了完整历史统计。

仅查询实时

{
  "plateNumbers": [
    "粤A09635F"
  ],
  "dataTypes": [
    "REALTIME"
  ]
}

不查询日统计，仅返回 realtime，queryDate=null。appKey 与所查车辆须在当前请求时点有效。

调用示例

curl --request POST \
  --url https://open.d.lnoneos.com/api/v1/vehicles/operating-data/query \
  --header 'Authorization: Bearer YOUR_APP_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"plateNumbers":["粤A09635F"],"dailyDate":"2026-10-23"}'

认证、授权与车辆关联

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

appKey 当前启用且在有效期内。实时查询校验 appKey 与车辆授权覆盖 requestAt；车辆授权的结束时点不包含在有效区间中。
日统计要求 appKey 和逐车授权完整覆盖 dailyDate 的北京时间自然日。授权不满一整天时，不开放半日统计。
同时选择实时和历史统计时，两套授权都须通过；历史授权不能用于取得当前实时位置，当前授权也不能替代历史授权。
先完成全部范围校验，再查询业务数据。任一车辆越权整批 403，不返回其他车辆或已成功块；授权依赖故障按 500 失败关闭。
按 VIN 关联并复用固定的车牌/VIN 映射，保持请求顺序；映射冲突按内部错误处理，不猜测匹配。
appKey 由调用方后端持有，不嵌入公开前端或小程序。日志不记录明文 appKey。

返回结构与汇总

字段	类型	含义与空值规则
code	string	固定 SUCCESS；不保证每个数据块均执行成功。
message	string	顶层处理说明。
traceId	string	服务端生成的唯一请求标识。
queryDate	date \| null	包含日统计时为dailyDate；仅实时为null。
timezone	string	枚举：Asia/Shanghai。
requestAt	date-time	固定请求基准时点，用于实时授权与记录年龄判断。
generatedAt	date-time	响应生成时点，不是任何业务数据的更新时间。
data	array	车辆数组，顺序与规范化后的请求名单一致。
summary	object	按车辆统计所选块的执行情况，详见下节。

以下完整结构和字段表适用于FULL。每辆车外层包含 vin、plateNumber，以及所选择的 realtime、dailyMileage、dailyHydrogen。成功块保留完整业务字段；源可选字段缺失统一为 null，真实 0 和 false 保留。块内不重复 vin 和 plateNumber。所有本接口时间戳输出为带 +08:00 的 RFC3339，可含小数秒。

summary 字段	定义
requestedCount	校验通过的请求车辆数。
returnedCount	data 条数；HTTP 200 时等于 requestedCount。
successCount	所有所选块 queryStatus 均为 SUCCESS 的车辆数。
partialSuccessCount	至少一个所选块 SUCCESS、至少一个 FAILED 的车辆数。
failedCount	所有所选块均 FAILED 的车辆数。

FULL模式中 successCount + partialSuccessCount + failedCount = returnedCount。NO_DATA、DATA_ANOMALY、STALE 和 CARRIED_FORWARD 不影响执行成功计数。仅选择一种数据时 partialSuccessCount 恒为 0。顶层 SUCCESS / HTTP 200 不能代替逐块检查。

完整响应示例

以下为合成示例，仅用于说明结构。单车请求对应单条 data。示例包含部分储氢字段缺失和当天初步用氢结果，并不代表已取得真实联调数据。

完整成功响应 · 200（可展开 / 收起）

{
  "code": "SUCCESS",
  "message": "success",
  "traceId": "f924a83d8a93475bac26b054305fc427",
  "queryDate": "2026-10-23",
  "timezone": "Asia/Shanghai",
  "requestAt": "2026-10-23T09:30:15+08:00",
  "generatedAt": "2026-10-23T09:30:16+08:00",
  "data": [
    {
      "vin": "LTEST000000000001",
      "plateNumber": "粤A09635F",
      "realtime": {
        "gpsFixStatus": "FIXED",
        "locationRecordTime": "2026-10-23T09:29:56+08:00",
        "coordinateSystem": "GCJ02",
        "protocol": "GB32960",
        "longitude": 113.264385,
        "latitude": 23.129112,
        "speedKmh": 35.6,
        "socPercent": 68.0,
        "totalMileageKm": 43968.2,
        "recordTime": "2026-10-23T09:29:56+08:00",
        "timeDifferenceSeconds": 19,
        "online": true,
        "activeToday": true,
        "motionStatus": "driving",
        "locationAvailable": true,
        "status": "NORMAL",
        "hydrogenPressureTemperatureSource": null,
        "remainingHydrogenPercentSource": null,
        "hydrogenFullCapacityKg": null,
        "hydrogenTankCapacityL": null,
        "hydrogenFullPressureMPa": null,
        "hydrogenReferenceTemperatureC": null,
        "hydrogenEstimatePressureMPa": null,
        "hydrogenEstimateTemperatureC": null,
        "hydrogenCalculationVersion": null,
        "hydrogenCapacitySource": null,
        "hydrogenPercentReason": "MISSING_TANK_CAPACITY",
        "remainingHydrogenKg": 16.0,
        "remainingHydrogenPercent": null,
        "hydrogenRecordTime": "2026-10-23T09:29:56+08:00",
        "hydrogenDataStatus": "PARTIAL",
        "remainingHydrogenKgStatus": "NORMAL",
        "remainingHydrogenPercentStatus": "MISSING",
        "hydrogenValueSource": "REPORTED",
        "hydrogenSourceProtocol": "GB32960",
        "hydrogenStaleAfterSeconds": 300,
        "hydrogenExpectedIntervalSeconds": null,
        "queryStatus": "SUCCESS",
        "errorCode": null,
        "errorMessage": null
      },
      "dailyMileage": {
        "queryStatus": "SUCCESS",
        "errorCode": null,
        "errorMessage": null,
        "status": "NORMAL",
        "date": "2026-10-23",
        "dailyMileageKm": 38.9,
        "totalMileageKm": 43968.2,
        "sourceProtocol": "GB32960",
        "dataQuality": null,
        "dataTime": "2026-10-23T09:29:50+08:00",
        "updatedAt": "2026-10-23T09:30:02+08:00",
        "statisticsStartTime": "2026-10-22T23:59:40+08:00",
        "statisticsEndTime": "2026-10-23T09:29:50+08:00"
      },
      "dailyHydrogen": {
        "queryStatus": "SUCCESS",
        "errorCode": null,
        "errorMessage": null,
        "status": "NORMAL",
        "date": "2026-10-23",
        "hydrogenConsumptionKg": 3.573,
        "qualityStatus": "OK",
        "qualityReason": null,
        "calculationPhase": "PRELIMINARY",
        "algorithmVersion": "PRESSURE_NIST_VALID_BOUNDARY_CHARGE_CYCLE_V3_5",
        "statisticsStartTime": null,
        "statisticsEndTime": "2026-10-23T09:29:56+08:00",
        "updatedAt": "2026-10-23T09:30:03+08:00"
      }
    }
  ],
  "summary": {
    "requestedCount": 1,
    "returnedCount": 1,
    "successCount": 1,
    "partialSuccessCount": 0,
    "failedCount": 0
  }
}

示例实时 kg 可用、百分比为 MISSING；日用氢为 PRELIMINARY，且两类日统计边界不一致。应展示各自指标，不能直接计算百公里氢耗。

完整部分失败响应 · 200

{
  "code": "SUCCESS",
  "message": "success",
  "traceId": "be2ed2362ee44c7098fd3d347c41f2f9",
  "queryDate": "2026-10-23",
  "timezone": "Asia/Shanghai",
  "requestAt": "2026-10-23T09:30:15+08:00",
  "generatedAt": "2026-10-23T09:30:16+08:00",
  "data": [
    {
      "vin": "LTEST000000000001",
      "plateNumber": "粤A09635F",
      "realtime": {
        "gpsFixStatus": "FIXED",
        "locationRecordTime": "2026-10-23T09:29:56+08:00",
        "coordinateSystem": "GCJ02",
        "protocol": "GB32960",
        "longitude": 113.264385,
        "latitude": 23.129112,
        "speedKmh": 35.6,
        "socPercent": 68.0,
        "totalMileageKm": 43968.2,
        "recordTime": "2026-10-23T09:29:56+08:00",
        "timeDifferenceSeconds": 19,
        "online": true,
        "activeToday": true,
        "motionStatus": "driving",
        "locationAvailable": true,
        "status": "NORMAL",
        "hydrogenPressureTemperatureSource": null,
        "remainingHydrogenPercentSource": null,
        "hydrogenFullCapacityKg": null,
        "hydrogenTankCapacityL": null,
        "hydrogenFullPressureMPa": null,
        "hydrogenReferenceTemperatureC": null,
        "hydrogenEstimatePressureMPa": null,
        "hydrogenEstimateTemperatureC": null,
        "hydrogenCalculationVersion": null,
        "hydrogenCapacitySource": null,
        "hydrogenPercentReason": "MISSING_TANK_CAPACITY",
        "remainingHydrogenKg": 16.0,
        "remainingHydrogenPercent": null,
        "hydrogenRecordTime": "2026-10-23T09:29:56+08:00",
        "hydrogenDataStatus": "PARTIAL",
        "remainingHydrogenKgStatus": "NORMAL",
        "remainingHydrogenPercentStatus": "MISSING",
        "hydrogenValueSource": "REPORTED",
        "hydrogenSourceProtocol": "GB32960",
        "hydrogenStaleAfterSeconds": 300,
        "hydrogenExpectedIntervalSeconds": null,
        "queryStatus": "SUCCESS",
        "errorCode": null,
        "errorMessage": null
      },
      "dailyMileage": {
        "queryStatus": "SUCCESS",
        "errorCode": null,
        "errorMessage": null,
        "status": "NORMAL",
        "date": "2026-10-23",
        "dailyMileageKm": 38.9,
        "totalMileageKm": 43968.2,
        "sourceProtocol": "GB32960",
        "dataQuality": null,
        "dataTime": "2026-10-23T09:29:50+08:00",
        "updatedAt": "2026-10-23T09:30:02+08:00",
        "statisticsStartTime": "2026-10-22T23:59:40+08:00",
        "statisticsEndTime": "2026-10-23T09:29:50+08:00"
      },
      "dailyHydrogen": {
        "queryStatus": "FAILED",
        "status": null,
        "errorCode": "HYDROGEN_QUERY_TIMEOUT",
        "errorMessage": "daily hydrogen query timeout"
      }
    }
  ],
  "summary": {
    "requestedCount": 1,
    "returnedCount": 1,
    "successCount": 0,
    "partialSuccessCount": 1,
    "failedCount": 0
  }
}

失败块只包含 queryStatus、status:null、errorCode、errorMessage；不附带旧业务数值。实时和里程成功时，用氢失败不丢弃其他结果。全部子查询失败仍可返回 200，此时 failedCount=returnedCount。

realtime 全部字段

以下为 queryStatus=SUCCESS 的完整字段集合；vin、plateNumber 取车辆外层身份。

字段	类型	含义与空值规则
queryStatus	string	SUCCESS 表示该子服务可见查询执行完成；仍需检查业务状态和逐字段质量。
errorCode	string \| null	成功块固定为 null。
errorMessage	string \| null	成功块固定为 null。
gpsFixStatus	string	实际位置报文定位位；GB32960 bit0=0、JT808 bit1=1 表示 FIXED；MQTT 或缺少可信定位位为 UNKNOWN。不以在线或数据年龄推断；枚举：FIXED, NO_FIX, UNKNOWN。
locationRecordTime	date-time \| null	位置行对应实际采集时间，独立于主记录 recordTime；历史 FIXED 不因车辆离线改变未知时为 null。
coordinateSystem	string	仅 GB2025 显式坐标类型 1=WGS84、2=GCJ02，其余 UNKNOWN；GB2016/JT808/MQTT 当前无确证为 UNKNOWN，未知坐标系不得直接当高德坐标使用；枚举：WGS84, GCJ02, UNKNOWN。
protocol	string \| null	本条实时位置、速度、里程及记录时间实际采用的采集协议；GB32960=车辆协议，MQTT=MQTT车端来源，JT808=定位终端来源未知时为 null。
longitude	number \| null	所选来源的最新有效经度；无位置时为 null
latitude	number \| null	所选来源的最新有效纬度；无位置时为 null
speedKmh	number \| null	所选来源瞬时速度，单位 km/h 未知时为 null。
socPercent	number \| null	动力电池 SOC（%）；未知为 null，不能替代储氢百分比。
totalMileageKm	number \| null	所选来源累计总里程，单位 km 未知时为 null。
recordTime	date-time \| null	实时主记录的实际采集时间，统一输出带 +08:00 的 RFC3339。未知时为 null。
timeDifferenceSeconds	integer \| null	requestAt 与主记录的时间差（秒），沿用源服务非负处理；表示记录年龄，不表示实际离线时长。未知为 null。
online	boolean	任一采集协议是否在最近60秒内上报
activeToday	boolean	任一采集协议在当前自然日（Asia/Shanghai）内上报过
motionStatus	string	driving=在线且速度大于3km/h；idle=在线且速度不大于3km/h；offline=当前不在线或无实时记录；枚举：driving, idle, offline。
locationAvailable	boolean	true=longitude/latitude 有效；false=当前无有效位置
status	string	当前实时主记录状态为 NORMAL / NO_DATA；不代表所有位置或储氢字段可用。
hydrogenPressureTemperatureSource	string \| null	最大氢压/最大氢温聚合读数近似；两者不保证来自同一瓶，不是逐瓶质量求和或全瓶完整性证明未知时为 null。；枚举：MAX_SENSOR_AGGREGATE。
remainingHydrogenPercentSource	string \| null	百分比始终为模型满充容量推算；与 kg 来源独立，计算前缺条件时为 null；枚举：ESTIMATED。
hydrogenFullCapacityKg	number \| null	实际用于比例分母的未舍入满充质量，kg；PressureHydrogenMassKg(35,15,VIN水容积)，不是扣除残余后的可用容量未知时为 null。
hydrogenTankCapacityL	number \| null	VIN 配置的全车储氢水容积，L；必须 active 且大于0、不超过10000，不根据车型臆造默认值未知时为 null。
hydrogenFullPressureMPa	number \| null	本次业务确认的满充参考压力，MPa；不代表自动核验每辆车铭牌额定压力未知时为 null。；枚举：35。
hydrogenReferenceTemperatureC	number \| null	满充参考温度，摄氏度未知时为 null。；枚举：15。
hydrogenEstimatePressureMPa	number \| null	仅平台估算 kg 时使用的同帧最大氢压，MPa；支持0，不补默认值未知时为 null。
hydrogenEstimateTemperatureC	number \| null	仅平台估算 kg 时使用的同帧最大氢温，摄氏度；模型输入范围−40–726.85°C，不是车辆安全温度阈值；缺失不补默认温度未知时为 null。
hydrogenCalculationVersion	string \| null	实时储氢模型版本；不修改日用氢算法未知时为 null。；枚举：REAL_GAS_35MPA_15C_V1。
hydrogenCapacitySource	string \| null	满充容量采用的 VIN 配置数据表未知时为 null。；枚举：vehicle_hydrogen_tank_capacity。
hydrogenPercentReason	string \| null	缺少或拒绝百分比的原因；超出业务满充参考仅拒绝百分比，不伪装为100，也不据此判断车辆安全状态未知时为 null。；枚举：MISSING_HYDROGEN_MEASUREMENT, INVALID_MASS_READING, INVALID_PRESSURE_TEMPERATURE, INCOMPLETE_PRESSURE_TEMPERATURE, MISSING_TANK_CAPACITY, MASS_CALCULATION_FAILED, EXCEEDS_NOMINAL_FULL_CAPACITY。
remainingHydrogenKg	number \| null	全车氢质量 kg；优先 GB32960 广东扩展终端上报（0–200 kg），缺质量时以同帧最大氢压/氢温和 VIN 全车水容积作实气估算（0–500 kg）。真实零保留，缺失/异常为 null，陈旧值保留并标 STALE
remainingHydrogenPercent	number \| null	剩余质量除以 VIN 水容积在 35 MPa、15°C 的实气模型满充质量乘100，属于 ESTIMATED；缺容量为 null/MISSING。超过100返回 null/INVALID，不截断为100，kg独立保留；不以动力电池SOC替代
hydrogenRecordTime	date-time \| null	氢质量对应原始同帧实际采集时间，RFC 3339 带时区；不是请求时间或缓存更新时间未知时为 null。
hydrogenDataStatus	string	NORMAL 两项有效（可包含估算，见来源）；PARTIAL 部分字段有效；STALE 数据陈旧；MISSING 缺少数据或容量；UNSUPPORTED 不支持；INVALID 异常。数值和字段级状态独立判断；枚举：NORMAL, PARTIAL, STALE, MISSING, UNSUPPORTED, INVALID。
remainingHydrogenKgStatus	string	枚举：NORMAL, STALE, MISSING, UNSUPPORTED, INVALID。
remainingHydrogenPercentStatus	string	独立于 kg 状态；容量缺失 MISSING，比例超100 INVALID；有值时继承 kg 的 NORMAL 或 STALE；枚举：NORMAL, STALE, MISSING, UNSUPPORTED, INVALID。
hydrogenValueSource	string \| null	kg 来源；REPORTED 仅确认终端上报，无法判断终端内部测量或估算；ESTIMATED 为平台压力/温度/容积实气模型估算未知时为 null。；枚举：REPORTED, ESTIMATED。
hydrogenSourceProtocol	string \| null	储氢数据采用的协议，独立于位置的 protocol 未知时为 null。；枚举：GB32960, MQTT, JT808。
hydrogenStaleAfterSeconds	integer \| null	GB32960 服务时效策略为 300 秒；不是协议采样周期承诺未知时为 null。
hydrogenExpectedIntervalSeconds	integer \| null	当前无已确认上报周期，固定 null

主 status=NORMAL 不保证位置或每个储氢字段可用，必须结合 GPS、坐标系、采集时间和逐字段储氢质量判断。实时主 protocol、储氢协议和采集时点可以不同。离线不等于 GPS 异常；UNKNOWN 坐标系不能直接按 GCJ02 上图。

聚合层不新增旧值兜底。原实时服务已有的有界原始帧回补仍保留，必须带实际 hydrogenRecordTime、来源和 STALE 状态。现有补充查询共享 3 秒预算，补充存储错误可降级为 MISSING/UNKNOWN，主查询仍 SUCCESS；queryStatus 不承诺区分所有被源服务吸收的底层失败。

dailyMileage 全部字段

字段	类型	含义与空值规则
queryStatus	string	SUCCESS 表示该子服务可见查询执行完成；仍需检查业务状态和逐字段质量。
errorCode	string \| null	成功块固定为 null。
errorMessage	string \| null	成功块固定为 null。
statisticsStartTime	date-time \| null	日里程起点累计读数的时间；可跨越多个缺报日；历史结转补零或无数据时为 null
statisticsEndTime	date-time \| null	当日所选来源最晚 latest_event_time，等于 dataTime；历史结转补零或无数据时为 null。与用氢接口无共同快照保证
date	date	查询自然日（Asia/Shanghai），与顶层 queryDate 一致，格式 yyyy-MM-dd。
dailyMileageKm	number \| null	日里程（km），复用原服务：优先已核验终端日统计，否则进行同来源累计读数对账；结转为 0，异常可为 null，GPS 估算不参与。
totalMileageKm	number \| null	当日所选协议最后有效终端累计总里程，km；GPS 日里程估算不会作为累计总里程。status=NORMAL 时必定有值，NO_DATA 时为 null
dataTime	date-time \| null	本次统计实际采用的最后一条车辆源数据时间；status=NO_DATA 时为 null
updatedAt	date-time \| null	本行所依据统计周期的计算时间；前向填充时为上一统计周期计算时间，status=NO_DATA 时为 null
sourceProtocol	string \| null	本行实际选中的来源协议；status=NO_DATA 时为 null；枚举：GB32960, MQTT, JT808。
dataQuality	string \| null	CARRIED_FORWARD 表示缺报结转；其他值表示无法连续对账的原因，此时 dailyMileageKm 为 null，保留累计读数及来源证据
status	string	NORMAL=存在可用数据；NO_DATA=授权范围内无可用数据；DATA_ANOMALY=检测到数据异常，详情见 dataQuality；枚举：NORMAL, NO_DATA, DATA_ANOMALY。

CARRIED_FORWARD 是 dataQuality 的值，status 仍为 NORMAL。日里程补 0、累计值与来源/时间沿用历史记录，不代表当日实测零里程；统计边界沿用源结果。不得隐式合并 realtime.totalMileageKm 与 dailyMileage.totalMileageKm。

dailyHydrogen 全部字段

字段	类型	含义与空值规则
queryStatus	string	SUCCESS 表示该子服务可见查询执行完成；仍需检查业务状态和逐字段质量。
errorCode	string \| null	成功块固定为 null。
errorMessage	string \| null	成功块固定为 null。
statisticsStartTime	date-time \| null	FINAL 证据区间最早开始时间；PRELIMINARY 仅有结束水位故为 null；缺失或异常证据为 null。边界是证据包络，不承诺连续覆盖
statisticsEndTime	date-time \| null	FINAL 证据区间最晚结束时间，PRELIMINARY 为真实 lastEventTime 水位；缺失或异常证据为 null；不是 API 查询时间
updatedAt	date-time \| null	同一用氢统计行的数据库更新时间，RFC 3339 带时区；无统计行时为 null
date	date	查询自然日（Asia/Shanghai），与顶层 queryDate 一致，格式 yyyy-MM-dd。
hydrogenConsumptionKg	number \| null	单日用氢量，kg；OK 和 SUSPECT 计算结果均返回数值，无数据时为 null
calculationPhase	string \| null	PRELIMINARY 仅供标注为初步的日内监控；FINAL 表示批量重算已完成，补传或算法调整仍可能再次重算，不保证固定结算时刻未知时为 null。
algorithmVersion	string \| null	氢耗计算算法版本未知时为 null。
qualityStatus	string \| null	OK 对应 NORMAL；SUSPECT 对应 DATA_ANOMALY 并保留数值供审计，不得用于正常百公里氢耗；NO_DATA 对应无可用统计未知时为 null。
qualityReason	string \| null	质量判定原因；SUSPECT 或 NO_DATA 时供调用方解释和审计未知时为 null。
status	string	NORMAL 对应有效质量 OK；DATA_ANOMALY 对应可疑质量 SUSPECT；NO_DATA 为无可用统计。

PRELIMINARY 仅用于明确标注为初步的日内监控；FINAL 表示完成相应批量重算，仍可被补传或算法修订回修。日期本身不决定阶段。DATA_ANOMALY 可保留数值供审计，不能当作正常用氢结果。没有统计行时值为 null，不填 0。

执行状态与错误码

情况	queryStatus	业务结果
子服务完成并有数据	SUCCESS	保留源 status、质量和逐字段状态。
子服务完成但无可用记录	SUCCESS	status=NO_DATA；数值按源定义为空，实时布尔/状态字段按原规则保留。
源业务数据异常	SUCCESS	status=DATA_ANOMALY；保留允许返回的审计字段。
子服务错误 / 超时	FAILED	status=null；仅返回执行错误字段。
源可选补充已降级	SUCCESS	保留 MISSING / UNKNOWN 等源状态，不能断言设备没有记录。

字段	类型	含义与空值规则
queryStatus	string	FAILED：该块查询错误、超时或结果转换失败。
status	string \| null	枚举：null。
errorCode	string	枚举：REALTIME_QUERY_FAILED, REALTIME_QUERY_TIMEOUT, MILEAGE_QUERY_FAILED, MILEAGE_QUERY_TIMEOUT, HYDROGEN_QUERY_FAILED, HYDROGEN_QUERY_TIMEOUT, SOURCE_DATA_INVALID。
errorMessage	string

HTTP	顶层 code	说明
200	SUCCESS	聚合流程完成，含部分或全部子查询失败；逐块判断。
400	INVALID_REQUEST	结构、类型、车牌、枚举、协议或批量数量不合法。
400	INVALID_DATE_FORMAT	缺少必需日期或日期格式不正确。
400	INVALID_DATE_RANGE	查询日期晚于北京时间当日。
401	UNAUTHORIZED	appKey 缺失、无效、停用或当前过期。
403	FORBIDDEN	车辆或查询时段未授权；整批拒绝。
413	PAYLOAD_TOO_LARGE	请求体超过 64 KiB。
429	RATE_LIMIT_EXCEEDED	应用或全局限额超限；读取 Retry-After 秒数后退避重试。
500	INTERNAL_ERROR	授权依赖故障、身份冲突或无法完成聚合的内部异常。

{
  "code": "FORBIDDEN",
  "message": "无数据访问权限",
  "traceId": "ee030dc62c1b4c9aa9b43cc9fa6b4b23"
}

非 200 响应不返回 data 或 summary。块错误码为 REALTIME_QUERY_FAILED/TIMEOUT、MILEAGE_QUERY_FAILED/TIMEOUT、HYDROGEN_QUERY_FAILED/TIMEOUT；这里的 TIMEOUT 表示完整代码后缀 _QUERY_TIMEOUT。源字段无法安全序列化或转换时间时为 SOURCE_DATA_INVALID。单个类型批量查询整体失败时，该类型对全部车辆均标 FAILED；单车结果转换异常可仅影响该车该块。

容量、超时与调用建议

项目	当前实现
车辆批量	显式车牌最多 200 项，超出返回 BATCH_SIZE_EXCEEDED；省略或空数组返回所选授权范围交集的全部车辆，不受 200 辆限制。按类型对 VIN 集合批量查询。
内部执行	所选三类最多三个任务并行，共享授权结果与固定映射；不逐车 HTTP 回调原接口。
总预算	6 秒，受更短的上游请求截止时间约束。
子查询预算	所选数据查询共享最多 4.5 秒；只把尚未完成的类型标记超时，保留已经完成的块。
应用限额	每应用、每服务实例 30 批/60 秒，最多 2 批并发；与历史剩余氢量接口配额独立。
端点总并发	每个服务实例最多 16 批；超限立即 429。
多实例与网关	统一配额由网关协调；网关预算须长于应用总预算并留传输余量。
响应格式	本端点返回紧凑 JSON；本文示例为便于阅读进行了格式化。
性能证据	已有本地测试与 Mock 基准，不包含线上数据库、网络或生产压测；不承诺未经验证的 P95。

只需某一类数据时显式传 dataTypes。收到部分失败后优先仅重试失败类型，遵循 Retry-After 并退避；不要把 NO_DATA 当成网络失败反复重试。当前没有新增聚合缓存、统计表或数据库迁移。

统计可比性与版本说明

FULL不返回百公里氢耗，SIMPLE预留该字段并固定null。相同 VIN、相同日期、NORMAL、相近更新时间，均不足以证明分子分母的统计区间可比。

调用方计算前至少检查：两块执行成功、业务正常，用氢质量 OK，里程为正且不是结转或异常；VIN 与日期一致。
还需有可核查的区间、证据覆盖及来源口径。statisticsStartTime/statisticsEndTime 只是证据包络；即使边界相等也不能单独证明连续覆盖。证据不足时只展示独立指标。
正式报表要求适用结果为 FINAL 并保留算法版本、查询时刻和结果快照；初步监控另标 PRELIMINARY。

版本 / 状态	说明
文档 V1.5 · 2026-10-26	按当前开发实现同步。对应 OpenAPI 1.12.2。
实现状态	已完成接口实现及测试；本文随开放平台服务发布，版本与实际状态可通过 /healthz 核对。
与 V1.1 评审稿的变化	限额与超时已明确；保留现有业务字段，失败块结构固定；补齐完整字段、示例和已知源降级边界。
旧接口	继续保留；本端点不修改其返回字段、统计或选源口径。瞬时车辆授权到期边界按结束时点不包含处理。

车辆单日用氢量

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

查询车辆单日用氢量，单位 kg。NORMAL + OK + PRELIMINARY 仅供初步监控；正式报表要求 FINAL 并核对证据与版本。两个日统计接口没有共同快照，区间缺失或不同不能直接计算百公里氢耗。

请求参数

字段	必填	说明
date	是	日期，格式 yyyy-MM-dd
plateNumbers	否	车牌数组；省略或 [] 时查询全部授权车辆

成功返回 · 200

{
  "code": "SUCCESS",
  "data": [{
    "plateNumber": "浙F06618F",
    "hydrogenConsumptionKg": 12.315,
    "status": "NORMAL"
  }]
}

400：日期或车牌格式不正确
401：appKey 无效、停用或过期
403：指定车辆未授权

车辆单日里程

POST/api/v1/vehicles/mileage/query

返回当日行驶里程、当日累计总里程和实际选用的数据协议，单位 km。

请求参数

字段	必填	说明
date	是	日期，格式 yyyy-MM-dd
plateNumbers	否	省略时查询全部授权车辆
protocolPriority	否	协议选源顺序，例如 ["GB32960","MQTT","JT808"]

缺数规则：日里程优先采用中台已选中且质量通过的终端日统计及其同来源基线，来源切换不单独触发异常；缺报日沿用累计值、日里程补 0（CARRIED_FORWARD），跨缺报期增量计入恢复日。没有已验证日统计时才按相邻日累计差计算；无法验证的首次基线、来源切换或累计回退返回 DATA_ANOMALY，日里程为 null。GPS 估算不参与本接口。

成功返回 · 200

{
  "code": "SUCCESS",
  "data": [{
    "dailyMileageKm": 182.437,
    "totalMileageKm": 12345.679,
    "sourceProtocol": "GB32960",
    "status": "NORMAL"
  }]
}

400：日期、车牌或协议参数错误
403：授权期未覆盖查询日
无统计：单车以 NO_DATA 返回

车辆区间日里程

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

按车辆、日期分页返回区间日里程，最长查询区间为 3 年（1096 天）。

请求参数

字段	必填	说明
startDate / endDate	是	日期区间，yyyy-MM-dd
plateNumbers	否	车牌数组，最多 5000 辆
protocolPriority	否	协议选源顺序
pageSize / cursor	否	分页大小及下一页游标

成功返回 · 200

{
  "code": "SUCCESS",
  "data": [{
    "date": "2026-08-06",
    "dailyMileageKm": 182.437,
    "totalMileageKm": 12345.679
  }],
  "nextCursor": null
}

400：区间超限或游标与原参数不一致
403：授权未完整覆盖查询区间

指定时刻总里程

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

按 VIN 返回不晚于指定时刻的最近一条总里程及实际采集协议。

请求参数

字段	必填	说明
vin	是	17 位已授权 VIN
time	是	北京时间 yyyy-MM-dd HH:mm:ss
protocol	否	GB32960、MQTT 或 JT808；省略时按默认顺序选取

成功返回 · 200

{
  "code": "SUCCESS",
  "data": {
    "totalMileageKm": 12345.678,
    "protocol": "GB32960",
    "recordTime": "2026-08-06 10:29:45",
    "timeDifferenceSeconds": 15
  }
}

400：VIN、时间或协议不合法
403：VIN 未授权
无记录：返回 NO_DATA

车辆实时位置与状态

POST/api/v1/vehicles/realtime/query

返回位置、在线状态、速度、总里程、储氢及独立 GPS 状态。储氢优先终端上报质量，缺质量可按同帧温压和 VIN 容积估算；百分比采用35 MPa、15°C满充参考，来源和质量分别说明。

比例 = 剩余质量 / PressureHydrogenMassKg(35,15,VIN容积) × 100。参考温度与密度比定义见 UNECE 定义文件；35 MPa 为本次业务参数，非所有车型额定压力的自动认证。

请求参数

字段	必填	说明
plateNumbers	否	省略或 [] 时返回全部当前有效授权车辆

成功返回 · 200

{
  "data": [{
    "vin": "LA9GG68L2PBAF4790",
    "plateNumber": "浙F06618F",
    "protocol": "GB32960",
    "longitude": 120.75,
    "latitude": 30.74,
    "speedKmh": 0,
    "totalMileageKm": 12345.678,
    "recordTime": "2026-08-17 17:40:12",
    "timeDifferenceSeconds": 8,
    "online": true,
    "activeToday": true,
    "motionStatus": "idle",
    "locationAvailable": true,
    "status": "NORMAL"
  }]
}

400：车牌格式错误
403：指定车牌未授权
无实时记录：返回 NO_DATA

加氢车辆停留核验

POST/api/v1/vehicles/stationary/query

按站点坐标、坐标系、时间段和半径，核验速度接近 0 的车辆停留记录，并按匹配度降序返回。

请求参数

字段	必填	说明
startTime / endTime	是	北京时间；查询区间最长 24 小时
longitude / latitude	是	加氢站经纬度；由 coordinateSystem 说明坐标系
coordinateSystem	否	WGS84（默认）或 GCJ02（高德）；GCJ02 自动转换后核验
radiusMeters	否	核验半径，单位 m；1–100，默认 5
plateNumbers	否	省略时核验全部有效授权车辆

匹配规则：速度 ≤ 3 km/h，至少 2 个样本且停留 ≥ 60 秒；相邻定位点间隔超过 10 分钟时拆分停留区间。

成功返回 · 200

{
  "data": [{
    "plateNumber": "浙F06618F",
    "stayStartTime": "2026-08-06 10:16:02",
    "stayEndTime": "2026-08-06 10:42:18",
    "stayDurationSeconds": 1576,
    "matchScore": 93.842
  }]
}

400：时间、坐标、坐标系或半径不合法
403：授权期未覆盖整个时间段
无匹配：data 为空数组

加氢站地图点位

POST/api/v1/hydrogen-stations/query

只读查询有有效坐标的加氢站，可按行政区划和合作属性筛选。

请求参数

字段	必填	说明
province / city	否	行政区划筛选
cooperateOnly	否	true 仅合作站；false 仅外部站

成功返回 · 200

{
  "data": [{
    "id": "1",
    "name": "示例加氢站",
    "longitude": 120.752312,
    "latitude": 30.746281,
    "cooperative": true
  }]
}

400：行政区划参数过长
401：appKey 无效
无符合站点：data 为空数组

返回字段与枚举说明

所有成功响应外层固定包含 code、message、data 和 traceId；以下为 data 内的字段。无数据时按对应接口返回 null、NO_DATA 或空数组。

通用响应与状态

字段／枚举	说明
code = SUCCESS	请求已成功处理。业务数据是否存在由每条数据的 status 判断。
message	成功时固定为 success。
traceId	本次请求唯一追踪标识；异常排查时请完整提供。
status = NORMAL	存在可用数据，相关数值、协议和时间字段有效。
status = NO_DATA	在授权范围内未找到可用数据；可选数值、位置、时间字段为 null 或省略。
status = DATA_ANOMALY	检测到数据异常，里程异常不返回可能错误的里程；用氢 SUSPECT 保留审计数值。原因分别见 dataQuality / qualityReason。
dataQuality = TOTAL_MILEAGE_ROLLBACK	终端累计里程明显回退，已阻止其作为正常累计里程返回。

车辆单日用氢量

字段	说明
vin / plateNumber / date	授权车辆 VIN、车牌与查询自然日（Asia/Shanghai）。
hydrogenConsumptionKg	当日用氢量，单位 kg；无有效数据时为 null。
status / qualityStatus	NORMAL / OK 为可用；DATA_ANOMALY / SUSPECT 保留数值供审计，不参与正常百公里氢耗；NO_DATA 不可用。
calculationPhase / algorithmVersion	PRELIMINARY 为初步监控结果，FINAL 为批量重算结果；历史结果仍可能再重算，保留实际版本。
statisticsStartTime / statisticsEndTime / updatedAt	证据包络起止和统计行更新时间；PRELIMINARY 开始时间为 null，结束为数据水位。与里程无共同快照保证。

车辆单日里程与区间日里程

字段	说明
vin / plateNumber / date	车辆唯一 VIN、车牌和统计自然日。
dailyMileageKm	当日行驶里程，单位 km。缺少当日记录且可前向补齐时为 0。
totalMileageKm	所选协议的日末累计总里程，单位 km；不会用 GPS 日里程估算值替代。
sourceProtocol	实际采用的协议：GB32960、MQTT 或 JT808。
dataTime	实际采用的最后一条车辆源数据时间。
updatedAt	该统计周期的计算时间；前向补齐时保持上一有效统计周期时间。
snapshotId / nextCursor	仅区间接口返回；snapshotId 固定本次分页车辆范围，nextCursor 为下一页游标，最后一页为 null。

指定时刻总里程

字段	说明
vin / queryTime	查询车辆 VIN 与请求的北京时间。
totalMileageKm	不晚于请求时间的最近一条累计总里程，单位 km。
protocol / protocolInput	protocol 为实际命中协议；protocolInput 为请求显式传入的协议，未传则省略。
recordTime / timeDifferenceSeconds	实际命中记录时间，以及请求时间与记录时间的差值，单位秒。
mileageMeaning	该协议累计里程的业务口径；JT808 为定位终端/GPS侧累计值。

车辆实时位置与状态

字段／枚举	说明
protocol	本条位置、速度、累计里程和记录时间实际采用的协议：GB32960、MQTT 或 JT808。
remainingHydrogenKg / remainingHydrogenPercent	全车储氢 kg / %，真实零保留。质量优先终端上报，缺值可用同帧温压和 VIN 容积估算；百分比按35 MPa、15°C满充质量计算，缺条件独立返回 null。
hydrogenRecordTime / hydrogenDataStatus	同帧采集时间和聚合状态 NORMAL / PARTIAL / STALE / MISSING / UNSUPPORTED / INVALID；必须同时检查两个字段级状态。
gpsFixStatus / locationRecordTime / coordinateSystem	真实定位位、位置采集时间和 WGS84 / GCJ02 / UNKNOWN。离线不清除历史 FIXED，陈旧不证明无定位。
longitude / latitude	无有效位置或 NO_FIX 时为 null，locationAvailable 为 false；UNKNOWN 坐标系需由调用方确认后上图。
speedKmh / totalMileageKm	所选来源的瞬时速度（km/h）和累计总里程（km）。
recordTime / timeDifferenceSeconds	所选来源的记录时间，以及与当前查询时间的差值，单位秒。
online	true：任一协议最近 60 秒内上报；false：没有任一协议满足该实时阈值。
activeToday	true：任一协议在当前自然日曾上报；不等同于实时 online。
motionStatus = driving	在线且所选来源速度大于 3 km/h。
motionStatus = idle	在线且所选来源速度不大于 3 km/h。
motionStatus = offline	当前不在线，或没有实时记录。

加氢车辆停留核验

字段	说明
stayStartTime / stayEndTime	满足核验条件的连续停留开始、结束时间。
stayDurationSeconds / stayDurationMinutes	停留时长，分别以秒、分钟表示。
matchScore	0–100；位置越接近、速度越低、停留越久、样本越充分，分数越高。
averageDistanceMeters / maxDistanceMeters	定位点相对输入站点坐标的平均/最大距离，单位 m。
averageSpeedKmh / maxSpeedKmh / matchedSamples	核验区间内速度统计与匹配定位样本数。
sourceProtocols	本停留片段采用过的协议数组，枚举值为 GB32960、MQTT、JT808。

加氢站地图点位

字段	说明
id / name / shortName	站点唯一标识、标准名称和简称；id 为字符串以避免 JavaScript 精度丢失。
address / province / city / district	站点地址及行政区划。
longitude / latitude	站点坐标。
cooperative	true：合作站（内部站或已导入合作名录）；false：外部站。

总里程协议口径

未指定 protocol 时，按 GB32960 > MQTT > JT808 选择第一个有数据的协议；不会跨协议拼接里程。

规范值	总里程含义
GB32960	车辆仪表盘累计总里程，对应 GB/T 32960 整车数据累计里程。
MQTT	车辆仪表盘或车端控制器累计总里程，由 MQTT 平台上报。
JT808	定位终端累计里程，由 GPS／终端侧计算，不等同于车辆仪表盘里程。

异常与状态码

所有响应均包含 code、message 和 traceId；请在工单中提供 traceId 以便排查。

HTTP	code	说明
200	SUCCESS	查询成功；无统计数据时，数据行的 status 为 NO_DATA。
400	INVALID_REQUEST	请求格式、数量、日期、时间、坐标或协议不正确。
401	UNAUTHORIZED	appKey 不存在、停用或已过期。
403	FORBIDDEN	车辆或 appKey 授权期未覆盖请求时间。
500	INTERNAL_ERROR	服务内部异常；请提供 traceId。