openapi: 3.0.3 info: title: 车辆数据开放平台 API version: 1.12.2 license: name: Proprietary description: | 向授权合作方开放车辆单日用氢量、单日里程、区间日里程、指定时刻总里程、加氢站停留核验、实时位置状态及加氢站地图点位。 appKey 和逐车授权必须完整覆盖查询自然日。 servers: - url: / description: 当前服务 tags: - name: 合作方数据接口 description: 使用 appKey 查询已授权车辆的日统计数据 - name: 开放平台管理 description: 仅车辆数据平台管理员可调用的应用和车辆授权管理接口 paths: /api/v1/vehicles/operating-data/query: post: tags: [合作方数据接口] summary: 批量查询车辆综合运营数据 description: | responseMode省略或FULL保持已上线完整结构；SIMPLE固定返回9个业务字段并在内部按质量过滤。 SIMPLE的百公里氢耗字段暂固定null，不进行未经证明可比的日用氢/日里程相除；不影响summary成功计数。 SIMPLE summary按所选展示字段可用性统计；FULL按子查询执行结果统计。未选类型对应的SIMPLE字段仍返回null但不参与计数。 SIMPLE舍弃陈旧/无可信采集时间的剩余氢量、异常用氢及结转补零；原完整数据和来源状态仍在内部保留。 车牌可选，省略或空数组查询所选时间范围均有效授权的全部车辆（取交集），无车辆返回空数组；省略或空数组不受200辆上限限制，不分页、不截断。显式指定车牌最多200项，超出返回BATCH_SIZE_EXCEEDED。规范化后不允许重复。 dataTypes省略时查询实时、单日里程和单日用氢；未选块省略。含日统计时dailyDate必填且不得为未来日期。 protocolPriority仅影响DAILY_MILEAGE，未选里程时不可提供；实时保持原有选源。 appKey须当前有效，实时车辆授权覆盖requestAt，日统计授权完整覆盖查询自然日。任一越权整批403；先授权再读取。 各数据块保留源字段、质量与时间，不是共同快照；不计算百公里氢耗。同日或NORMAL不能证明统计区间可比。 FULL的queryStatus仅表示子服务可见执行结果，SUCCESS仍可能NO_DATA、DATA_ANOMALY或实时补充降级MISSING/UNKNOWN。 里程结转沿用status=NORMAL及dataQuality=CARRIED_FORWARD，不能解释为实测零；储氢陈旧和估算来源原样保留。 各块失败独立返回FAILED及错误码，不以NO_DATA或旧值掩盖。所有子查询失败仍返回200和准确summary。 所有时间戳转为带+08:00的RFC3339，未知可选字段显式null；原独立接口不受影响。 每应用每服务实例30批/60秒、最多2批并发；新端点全局每实例最多16批。429包含Retry-After，多实例配额由网关统一协调。 总预算6秒，批量子查询共享最多4.5秒预算；上层网关需给出更长预算。未承诺未经压测的P95目标。 operationId: queryVehicleOperatingData security: - AppKeyAuth: [] requestBody: required: true description: 最大64KiB；不接受未知字段或显式null。 content: application/json: schema: $ref: '#/components/schemas/OperatingDataQuery' example: responseMode: SIMPLE plateNumbers: [粤A09635F] dailyDate: '2026-10-23' dataTypes: [REALTIME, DAILY_MILEAGE, DAILY_HYDROGEN] protocolPriority: [GB32960, MQTT, JT808] responses: '200': description: 聚合处理完成；FULL逐块检查执行和质量，SIMPLE返回9字段并按所选展示字段可用性汇总。 content: application/json: schema: oneOf: - $ref: '#/components/schemas/OperatingDataResponse' - $ref: '#/components/schemas/OperatingSimpleResponse' '400': description: 参数、日期或协议不合法；显式plateNumbers超过200项时code为BATCH_SIZE_EXCEEDED content: application/json: schema: $ref: '#/components/schemas/OperatingErrorResponse' '401': description: appKey当前无效 content: application/json: schema: $ref: '#/components/schemas/OperatingErrorResponse' '403': description: 车辆或所选时段未授权 content: application/json: schema: $ref: '#/components/schemas/OperatingErrorResponse' '413': description: 请求体超过64KiB content: application/json: schema: $ref: '#/components/schemas/OperatingErrorResponse' '429': description: 应用或全局限额超限 headers: Retry-After: schema: {type: integer, minimum: 1} content: application/json: schema: $ref: '#/components/schemas/OperatingErrorResponse' '500': description: 授权依赖、身份映射或聚合内部异常 content: application/json: schema: $ref: '#/components/schemas/OperatingErrorResponse' /api/v1/vehicles/hydrogen-remaining/history/query: post: tags: [合作方数据接口] summary: 批量查询历史时刻剩余氢质量 description: | 按真实 event_time 查询不晚于指定时刻的最近氢相关帧，不跳过最新异常记录，不使用实时值或日用氢量填补。 历史支持从 2026-08-01 起；实际车辆/时间覆盖以保留的原始帧为准，日期可请求不代表每个时点均有有效氢量。 历史容量必须具有适用于历史时点的证据；不能用当前配置回套历史。当前缺少历史容量版本，只输出有证据的REPORTED质量，温压有效但无容量版本时 MISSING。 同批按规范化VIN+time+protocol去重，同一点共享一次查询/授权结果与来源版本，各requestId仍独立回显；不同点为非原子快照，不以同批证明两端可比。 200项仅为结构上限，不保证200个不同点能在9秒完成。建议先用20个不同点，ERROR超时时缩小批量并退避重试。 有效采样超容差为STALE，最新帧INVALID/MISSING优先保留原原因；分块原始帧重组失败或候选预算耗尽为ERROR，不伪装NO_DATA。 每项均返回 requestId；FORBIDDEN、ERROR 等失败不丢项，非 NORMAL 质量为 null。 appKey须当前有效，并逐项校验请求时刻与采样时刻授权（结束时间不含端点）；FORBIDDEN不返回采样元数据。 每app每服务实例30批/60秒，最多2个并发批；429包含Retry-After。整批9秒预算、最多4个工作协程，超时项ERROR，可重试。 operationId: queryHistoricalHydrogenRemaining security: - AppKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HistoricalHydrogenQuery' example: queries: - requestId: job-start vin: LA9GG68L2PBAF4773 time: '2026-08-03 16:02:43' protocol: GB32960 maxTimeDifferenceSeconds: 300 responses: '200': description: 批量处理完成；每项状态独立判断，包括 FORBIDDEN 或 ERROR content: application/json: schema: $ref: '#/components/schemas/HistoricalHydrogenQueryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': description: 超出历史查询限流；读取 Retry-After 秒数后重试 headers: Retry-After: schema: { type: integer, minimum: 1 } description: 建议等待秒数 '500': $ref: '#/components/responses/InternalError' /api/v1/vehicles/hydrogen-consumption/query: post: tags: [合作方数据接口] summary: 查询车辆单日用氢量 description: plateNumbers 省略或传空数组时，返回该应用在查询自然日有效授权的全部车辆。SUSPECT 计算结果保留用氢量并以 DATA_ANOMALY 输出，同时返回质量原因。 operationId: queryDailyHydrogenConsumption security: - AppKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VehicleDailyQuery' example: date: '2026-07-01' responses: '200': description: 查询成功；无数据车辆仍保留在结果中 content: application/json: schema: $ref: '#/components/schemas/HydrogenQueryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' /api/v1/vehicles/mileage/query: post: tags: [合作方数据接口] summary: 查询车辆单日里程 description: | plateNumbers 省略或传空数组时，返回该应用在查询自然日有效授权的全部车辆。 protocolPriority 传入时，逐车按数组顺序选择截至查询日已有有效累计读数的第一个协议；高优先级协议缺报时沿用其历史累计值，不切换累计基准，未列出的协议完全禁用且不会兜底；省略时保持平台默认选源行为。 NORMAL 结果同时包含日里程、日末累计总里程、实际来源协议、源数据时间和投影更新时间。日里程优先采用中台已选中且质量通过的终端日统计及其同来源基线，跨缺报期增量计入恢复上报日；来源切换本身不会否定已验证的日统计。无已验证日统计时按同来源累计差计算，首次基线、来源切换或累计回退无法验证时返回 DATA_ANOMALY、dailyMileageKm=null 和 dataQuality。GPS 估算不参与本接口。 当日缺报时，日里程补 0，累计总里程、来源协议、dataTime 和 updatedAt 沿用同协议历史读数，dataQuality=CARRIED_FORWARD。 operationId: queryDailyMileage security: - AppKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MileageDailyQuery' example: date: '2026-07-01' protocolPriority: [GB32960, MQTT, JT808] responses: '200': description: 查询成功；无数据车辆仍保留在结果中 content: application/json: schema: $ref: '#/components/schemas/MileageQueryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' /api/v1/vehicles/mileage/range/query: post: tags: [合作方数据接口] summary: 分页查询车辆区间日里程 description: | 最长支持 3 年（1096 天）。plateNumbers 省略或传空数组时固化应用在整个查询区间有效授权的全部车辆。 首次请求返回 snapshotId 和 nextCursor；后续请求保持原参数并传回 nextCursor。 快照仅固化授权车辆清单，逐页读取已建立索引的日统计投影，不扫描原始时序明细。 protocolPriority 对区间内每辆车、每个自然日独立生效；未列出的协议完全禁用。 某日无有效里程时，dailyMileageKm 补 0，其余里程证据沿用此前最近的有效统计。若终端累计里程回退，返回 DATA_ANOMALY 与 dataQuality=TOTAL_MILEAGE_ROLLBACK。日里程与累计值使用同一终端来源；日里程优先采用中台已验证的日统计及其同来源基线，来源切换不单独触发异常；缺少已验证日统计时才使用相邻自然日累计差。GPS 估算不参与本接口。单日、区间和分页共用相同计算规则。 operationId: queryDailyMileageRange security: - AppKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MileageRangeQuery' example: startDate: '2026-07-01' endDate: '2026-07-23' plateNumbers: [沪A00001, 沪A00002] protocolPriority: [JT808, GB32960, MQTT] cursor: null pageSize: 5000 responses: '200': description: 查询成功；每辆授权车辆每天均有一条 NORMAL 或 NO_DATA 记录 content: application/json: schema: $ref: '#/components/schemas/MileageRangeQueryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' /api/v1/vehicles/total-mileage/query: post: tags: [合作方数据接口] summary: 查询指定时刻的车辆总里程 description: | 返回不晚于请求时间的最近一条有效总里程记录、实际记录时间和时间差秒数。 protocol 不传时严格按 GB32960 > YUTONG_MQTT > JT808 选择首个有数据的协议。 GB32960 和 YUTONG_MQTT 为车辆仪表盘或车端累计里程；JT808 为定位终端/GPS侧累计里程。 operationId: queryTotalMileageAtTime security: - AppKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TotalMileageQuery' example: vin: LA9GG68L2PBAF4790 time: '2026-07-21 09:30:00' protocol: GB32960 responses: '200': description: 查询成功；没有可用记录时返回 NO_DATA content: application/json: schema: $ref: '#/components/schemas/TotalMileageQueryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' /api/v1/vehicles/stationary/query: post: tags: [合作方数据接口] summary: 加氢站车辆停留核验 description: | 用于加氢车牌核验。传入加氢站经度、纬度、坐标系、半径和北京时间区间，返回范围内速度不大于 3 km/h 的授权车辆停留区间。 coordinateSystem 支持 WGS84（默认）和 GCJ02（高德坐标）；服务端会将 GCJ02 转换为 WGS84 后进行核验。 同一车辆相邻静止点间隔超过 10 分钟会拆分为不同停留；仅返回至少 2 个定位样本且持续不少于 60 秒的停留。 最大查询区间为 24 小时。结果按 matchScore 从高到低排序；分数综合平均距离、最高速度、停留时长和采样数量，供人工核验使用，不等同于加氢交易凭证。 operationId: queryStationaryVehicles security: - AppKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StationaryVehicleQuery' example: startTime: '2026-08-06 10:00:00' endTime: '2026-08-06 12:00:00' longitude: 120.752312 latitude: 30.746281 coordinateSystem: GCJ02 radiusMeters: 5 responses: '200': description: 查询成功；无匹配车辆时 data 为空数组 content: application/json: schema: $ref: '#/components/schemas/StationaryVehicleQueryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' /api/v1/vehicles/realtime/query: post: tags: [合作方数据接口] summary: 查询授权车辆实时位置与状态 description: | plateNumbers 省略或传空数组时返回应用当前有效授权的全部车辆。 实时来源优先级为 GB32960 > YUTONG_MQTT > JT808；所有来源超过10分钟时改按最新记录选择。 任一采集协议在最近60秒内上报即视为在线；protocol、位置、速度、SOC 和记录时间仍按上述来源优先级选择。 socPercent 仅在所选来源采集到有效 SOC（0–100，单位 %）时返回；无值或无效值时该字段省略。 activeToday 表示任一采集协议在当前自然日（Asia/Shanghai）内曾上报，用于日上线车辆统计，不改变 online 的实时口径。 离线时 motionStatus=offline；在线且所选来源速度大于3km/h为 driving，否则为 idle。 满充容量采用 PressureHydrogenMassKg(35,15,VIN水容积)；35 MPa 是本次业务基准，15°C 密度比参考来自 https://unece.org/sites/default/files/2024-07/ECE_TRANS_WP.29_2023_110E.pdf，不代表车型额定压力自动认证。 储氢优先终端上报质量 REPORTED；无质量时以同帧最大氢压/最大氢温与 VIN 全车水容积估算 ESTIMATED。百分比按 35 MPa、15°C 满充参考质量计算，不以 SOC 替代。 仅 GB 最新快照有引用且精确帧氢量 MISSING 时有界回补，按采集时间优先、接收时间次序检查最近5条候选；不完整温压可取次新完整帧，不回退覆盖 INVALID，离线回补保留真实 STALE。 GPS 定位状态独立于在线与陈旧；坐标系可能 UNKNOWN，不能假定统一 GCJ02。 补充历史查询共享 3 秒预算，失败或超时降级为 MISSING/UNKNOWN 并保留旧实时字段；MISSING 不等于设备不支持。 operationId: queryRealtimeVehicles security: - AppKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RealtimeVehicleQuery' example: {} responses: '200': description: 查询成功；没有实时记录的授权车辆以 NO_DATA 返回 content: application/json: schema: $ref: '#/components/schemas/RealtimeVehicleQueryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' /api/v1/hydrogen-stations/query: post: tags: [合作方数据接口] summary: 查询加氢站地图点位 description: 只读返回资产管理数据库内具有有效经纬度的加氢站，可按省、市和合作状态筛选；无需车辆授权但要求有效 appKey。 operationId: queryHydrogenStations security: - AppKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HydrogenStationQuery' example: {} responses: '200': description: 查询成功 content: application/json: schema: $ref: '#/components/schemas/HydrogenStationQueryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' /api/v2/open-platform/apps: get: tags: [开放平台管理] summary: 查询开放平台应用 operationId: listOpenPlatformApps security: - AdminBearer: [] responses: '200': description: 应用列表 content: application/json: schema: $ref: '#/components/schemas/AdminAppListResponse' '401': description: 未登录 '403': description: 非管理员 post: tags: [开放平台管理] summary: 创建应用和 appKey description: appKey 明文仅在本次响应中返回。 operationId: createOpenPlatformApp security: - AdminBearer: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AppInput' responses: '200': description: 创建成功 content: application/json: schema: $ref: '#/components/schemas/AdminAppCreatedResponse' '400': description: 参数错误 '401': description: 未登录 '403': description: 非管理员 /api/v2/open-platform/apps/{id}: put: tags: [开放平台管理] summary: 更新应用状态和有效期 operationId: updateOpenPlatformApp security: - AdminBearer: [] parameters: - $ref: '#/components/parameters/AppId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AppInput' responses: '200': description: 更新成功 '400': description: 参数错误 '404': description: 应用不存在 /api/v2/open-platform/apps/{id}/rotate-key: post: tags: [开放平台管理] summary: 轮换 appKey description: 旧 Key 立即失效，新 Key 明文仅在本次响应中返回。 operationId: rotateOpenPlatformAppKey security: - AdminBearer: [] parameters: - $ref: '#/components/parameters/AppId' responses: '200': description: 轮换成功 content: application/json: schema: $ref: '#/components/schemas/AdminAppCreatedResponse' '404': description: 应用不存在 /api/v2/open-platform/apps/{id}/vehicles: get: tags: [开放平台管理] summary: 查询应用的车辆授权 operationId: listOpenPlatformVehicleGrants security: - AdminBearer: [] parameters: - $ref: '#/components/parameters/AppId' responses: '200': description: 授权列表 '404': description: 应用不存在 put: tags: [开放平台管理] summary: 完整替换车辆授权 operationId: replaceOpenPlatformVehicleGrants security: - AdminBearer: [] parameters: - $ref: '#/components/parameters/AppId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VehicleGrantRequest' responses: '200': description: 替换成功 '400': description: VIN 或有效期不正确 '404': description: 应用不存在 components: securitySchemes: AppKeyAuth: type: http scheme: bearer bearerFormat: 32-character appKey description: 32 位无连字符 UUID appKey AdminBearer: type: http scheme: bearer bearerFormat: Platform session token description: 车辆数据平台管理员令牌 parameters: AppId: name: id in: path required: true schema: type: integer format: int64 minimum: 1 responses: BadRequest: description: 请求参数不正确 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidDate: value: code: INVALID_DATE_FORMAT message: date格式必须为yyyy-MM-dd traceId: 4ccf63c4e51d4d4ab9107d931783a53e Unauthorized: description: appKey 不存在、停用或过期 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: Key 或车辆授权未完整覆盖查询自然日 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: 服务内部异常 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' schemas: OperatingSimpleVehicle: type: "object" additionalProperties: false required: ["plateNumber", "reportTime", "offline", "remainingHydrogenKg", "socPercent", "totalMileageKm", "dailyHydrogenConsumptionKg", "dailyMileageKm", "hydrogenConsumptionPer100KmKg"] properties: plateNumber: type: "string" description: "规范化后的请求车牌，保持请求顺序。" reportTime: type: "string" nullable: true description: "实时选中主记录的event_time，即真实源采集/上报时刻；缺失为null，不使用received_at、updated_at或请求时间替代。FULL recordTime仍保持原兼容口径。" format: "date-time" offline: type: "boolean" nullable: true description: "主实时记录可用且online已知时取反；无记录或查询失败为null，不能当成离线。" remainingHydrogenKg: type: "number" nullable: true description: "剩余氢量kg。仅kg字段NORMAL、数值有效且有可信采集时间，响应时不超过300秒并不晚于服务时点1分钟时展示；陈旧/缺失/异常为null，真实0保留。" minimum: 0 socPercent: type: "number" nullable: true description: "动力电池SOC百分比；实时主记录有效且数值在0–100内，未知为null。" minimum: 0 maximum: 100 totalMileageKm: type: "number" nullable: true description: "实时主记录累计里程km；不使用日统计累计值兜底。" minimum: 0 dailyHydrogenConsumptionKg: type: "number" nullable: true description: "queryDate用氢量kg；子查询成功、status=NORMAL、qualityStatus=OK时返回有效非负数值，否则null。日内值可为PRELIMINARY，不保证终报。" minimum: 0 dailyMileageKm: type: "number" nullable: true description: "queryDate里程km；执行成功、业务NORMAL且非CARRIED_FORWARD时返回有效非负数值；实测零保留，结转补零和异常为null。" minimum: 0 hydrogenConsumptionPer100KmKg: type: "number" nullable: true description: "kg/100km预留字段；当前缺少可比区间完整证据，固定null，不参与summary计数。禁止调用方以同日日指标直接相除。" enum: [null] OperatingSimpleSummary: type: "object" description: "按所选展示字段的可用性统计：实时5项+日里程1项+日用氢1项。全有值successCount、部分有值partialSuccessCount、全null failedCount。plateNumber和暂未支持的百公里氢耗不参与；未选类型不参与。null及failedCount并不等于查询执行失败，不作为自动重试依据。" required: ["requestedCount", "returnedCount", "successCount", "partialSuccessCount", "failedCount"] properties: requestedCount: {"$ref": "#/components/schemas/OperatingDataSummary/properties/requestedCount"} returnedCount: {"$ref": "#/components/schemas/OperatingDataSummary/properties/returnedCount"} successCount: {"$ref": "#/components/schemas/OperatingDataSummary/properties/successCount"} partialSuccessCount: {"$ref": "#/components/schemas/OperatingDataSummary/properties/partialSuccessCount"} failedCount: {"$ref": "#/components/schemas/OperatingDataSummary/properties/failedCount"} OperatingSimpleResponse: type: "object" required: ["code", "message", "traceId", "queryDate", "timezone", "requestAt", "generatedAt", "data", "summary"] properties: code: {"$ref": "#/components/schemas/OperatingDataResponse/properties/code"} message: {"$ref": "#/components/schemas/OperatingDataResponse/properties/message"} traceId: {"$ref": "#/components/schemas/OperatingDataResponse/properties/traceId"} queryDate: {"$ref": "#/components/schemas/OperatingDataResponse/properties/queryDate"} timezone: {"$ref": "#/components/schemas/OperatingDataResponse/properties/timezone"} requestAt: {"$ref": "#/components/schemas/OperatingDataResponse/properties/requestAt"} generatedAt: {"$ref": "#/components/schemas/OperatingDataResponse/properties/generatedAt"} data: type: "array" minItems: 0 items: {"$ref": "#/components/schemas/OperatingSimpleVehicle"} summary: {"$ref": "#/components/schemas/OperatingSimpleSummary"} OperatingDataQuery: type: "object" oneOf: - required: [dataTypes] properties: dataTypes: {type: array, minItems: 1, maxItems: 1, items: {type: string, enum: [REALTIME]}} - required: [dailyDate] not: required: [dataTypes] properties: dataTypes: {type: array, minItems: 1, maxItems: 1, items: {type: string, enum: [REALTIME]}} additionalProperties: false properties: responseMode: type: string enum: [FULL, SIMPLE] default: FULL description: 省略保持完整结构；显式SIMPLE返回固定9字段；不接受空字符串或null。 plateNumbers: type: "array" minItems: 0 maxItems: 200 uniqueItems: true items: type: "string" minLength: 1 maxLength: 32 description: "可选；省略或空数组查询所选时间范围内均有效授权的全部车辆，按车牌排序。省略或空数组返回全部有效授权车辆，不受200辆上限限制，不分页、不截断；显式指定最多200项，超出返回BATCH_SIZE_EXCEEDED。去首尾空白、转大写后仍必须唯一。" dailyDate: type: "string" format: "date" description: "含日统计时必填；仅实时可省略；提供时仍校验。无固定历史下界，能否取得结果取决于有效授权及保留的统计投影，不承诺历史完整性。" dataTypes: type: "array" minItems: 1 maxItems: 3 uniqueItems: true items: type: "string" enum: ["REALTIME", "DAILY_MILEAGE", "DAILY_HYDROGEN"] description: "省略默认全部；未选数据块不出现。" protocolPriority: type: "array" minItems: 1 maxItems: 3 uniqueItems: true items: type: "string" enum: ["GB32960", "MQTT", "JT808"] description: "仅选DAILY_MILEAGE时允许；未列出协议不兜底。" OperatingRealtimeVehicleResultSuccess: type: "object" required: ["queryStatus", "errorCode", "errorMessage", "gpsFixStatus", "locationRecordTime", "coordinateSystem", "protocol", "longitude", "latitude", "speedKmh", "socPercent", "totalMileageKm", "recordTime", "timeDifferenceSeconds", "online", "activeToday", "motionStatus", "locationAvailable", "status", "hydrogenPressureTemperatureSource", "remainingHydrogenPercentSource", "hydrogenFullCapacityKg", "hydrogenTankCapacityL", "hydrogenFullPressureMPa", "hydrogenReferenceTemperatureC", "hydrogenEstimatePressureMPa", "hydrogenEstimateTemperatureC", "hydrogenCalculationVersion", "hydrogenCapacitySource", "hydrogenPercentReason", "remainingHydrogenKg", "remainingHydrogenPercent", "hydrogenRecordTime", "hydrogenDataStatus", "remainingHydrogenKgStatus", "remainingHydrogenPercentStatus", "hydrogenValueSource", "hydrogenSourceProtocol", "hydrogenStaleAfterSeconds", "hydrogenExpectedIntervalSeconds"] properties: queryStatus: type: "string" enum: ["SUCCESS"] errorCode: type: "string" nullable: true enum: [null] errorMessage: type: "string" nullable: true enum: [null] gpsFixStatus: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/gpsFixStatus"} locationRecordTime: type: "string" format: "date-time" nullable: true description: "保留源时刻，输出RFC3339带+08:00；未知为null。" coordinateSystem: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/coordinateSystem"} protocol: type: "string" nullable: true description: "沿用源字段含义；原可选字段缺失时输出null。" longitude: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/longitude"} latitude: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/latitude"} speedKmh: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/speedKmh"} socPercent: type: "number" minimum: 0 maximum: 100 nullable: true description: "动力电池SOC；未知为null。" totalMileageKm: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/totalMileageKm"} recordTime: type: "string" format: "date-time" nullable: true description: "保留源时刻，输出RFC3339带+08:00；未知为null。" timeDifferenceSeconds: type: "integer" minimum: 0 nullable: true description: "源主记录年龄，不表示实际离线时长。" online: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/online"} activeToday: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/activeToday"} motionStatus: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/motionStatus"} locationAvailable: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/locationAvailable"} status: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/status"} hydrogenPressureTemperatureSource: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenPressureTemperatureSource"} remainingHydrogenPercentSource: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/remainingHydrogenPercentSource"} hydrogenFullCapacityKg: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenFullCapacityKg"} hydrogenTankCapacityL: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenTankCapacityL"} hydrogenFullPressureMPa: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenFullPressureMPa"} hydrogenReferenceTemperatureC: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenReferenceTemperatureC"} hydrogenEstimatePressureMPa: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenEstimatePressureMPa"} hydrogenEstimateTemperatureC: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenEstimateTemperatureC"} hydrogenCalculationVersion: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenCalculationVersion"} hydrogenCapacitySource: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenCapacitySource"} hydrogenPercentReason: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenPercentReason"} remainingHydrogenKg: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/remainingHydrogenKg"} remainingHydrogenPercent: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/remainingHydrogenPercent"} hydrogenRecordTime: type: "string" format: "date-time" nullable: true description: "保留源时刻，输出RFC3339带+08:00；未知为null。" hydrogenDataStatus: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenDataStatus"} remainingHydrogenKgStatus: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/remainingHydrogenKgStatus"} remainingHydrogenPercentStatus: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/remainingHydrogenPercentStatus"} hydrogenValueSource: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenValueSource"} hydrogenSourceProtocol: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenSourceProtocol"} hydrogenStaleAfterSeconds: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenStaleAfterSeconds"} hydrogenExpectedIntervalSeconds: {"$ref": "#/components/schemas/RealtimeVehicleResult/properties/hydrogenExpectedIntervalSeconds"} OperatingMileageResultSuccess: type: "object" required: ["queryStatus", "errorCode", "errorMessage", "statisticsStartTime", "statisticsEndTime", "date", "dailyMileageKm", "totalMileageKm", "dataTime", "updatedAt", "sourceProtocol", "dataQuality", "status"] properties: queryStatus: type: "string" enum: ["SUCCESS"] errorCode: type: "string" nullable: true enum: [null] errorMessage: type: "string" nullable: true enum: [null] statisticsStartTime: type: "string" format: "date-time" nullable: true description: "保留源时刻，输出RFC3339带+08:00；未知为null。" statisticsEndTime: type: "string" format: "date-time" nullable: true description: "保留源时刻，输出RFC3339带+08:00；未知为null。" date: {"$ref": "#/components/schemas/MileageResult/properties/date"} dailyMileageKm: {"$ref": "#/components/schemas/MileageResult/properties/dailyMileageKm"} totalMileageKm: {"$ref": "#/components/schemas/MileageResult/properties/totalMileageKm"} dataTime: type: "string" format: "date-time" nullable: true description: "保留源时刻，输出RFC3339带+08:00；未知为null。" updatedAt: type: "string" format: "date-time" nullable: true description: "保留源时刻，输出RFC3339带+08:00；未知为null。" sourceProtocol: {"$ref": "#/components/schemas/MileageResult/properties/sourceProtocol"} dataQuality: type: "string" nullable: true description: "沿用源字段含义；原可选字段缺失时输出null。" status: {"$ref": "#/components/schemas/MileageResult/properties/status"} OperatingHydrogenResultSuccess: type: "object" required: ["queryStatus", "errorCode", "errorMessage", "statisticsStartTime", "statisticsEndTime", "updatedAt", "date", "hydrogenConsumptionKg", "calculationPhase", "algorithmVersion", "qualityStatus", "qualityReason", "status"] properties: queryStatus: type: "string" enum: ["SUCCESS"] errorCode: type: "string" nullable: true enum: [null] errorMessage: type: "string" nullable: true enum: [null] statisticsStartTime: type: "string" format: "date-time" nullable: true description: "保留源时刻，输出RFC3339带+08:00；未知为null。" statisticsEndTime: type: "string" format: "date-time" nullable: true description: "保留源时刻，输出RFC3339带+08:00；未知为null。" updatedAt: type: "string" format: "date-time" nullable: true description: "保留源时刻，输出RFC3339带+08:00；未知为null。" date: {"$ref": "#/components/schemas/HydrogenResult/properties/date"} hydrogenConsumptionKg: {"$ref": "#/components/schemas/HydrogenResult/properties/hydrogenConsumptionKg"} calculationPhase: type: "string" nullable: true description: "沿用源字段含义；原可选字段缺失时输出null。" algorithmVersion: type: "string" nullable: true description: "沿用源字段含义；原可选字段缺失时输出null。" qualityStatus: type: "string" nullable: true description: "沿用源字段含义；原可选字段缺失时输出null。" qualityReason: type: "string" nullable: true description: "沿用源字段含义；原可选字段缺失时输出null。" status: {"$ref": "#/components/schemas/HydrogenResult/properties/status"} OperatingDataBlockFailure: type: "object" additionalProperties: false required: ["queryStatus", "status", "errorCode", "errorMessage"] properties: queryStatus: type: "string" enum: ["FAILED"] status: type: "string" nullable: true enum: [null] errorCode: type: "string" enum: ["REALTIME_QUERY_FAILED", "REALTIME_QUERY_TIMEOUT", "MILEAGE_QUERY_FAILED", "MILEAGE_QUERY_TIMEOUT", "HYDROGEN_QUERY_FAILED", "HYDROGEN_QUERY_TIMEOUT", "SOURCE_DATA_INVALID"] errorMessage: type: "string" OperatingVehicleResult: type: "object" required: ["vin", "plateNumber"] properties: vin: type: "string" plateNumber: type: "string" realtime: oneOf: [{"$ref": "#/components/schemas/OperatingRealtimeVehicleResultSuccess"}, {"$ref": "#/components/schemas/OperatingDataBlockFailure"}] dailyMileage: oneOf: [{"$ref": "#/components/schemas/OperatingMileageResultSuccess"}, {"$ref": "#/components/schemas/OperatingDataBlockFailure"}] dailyHydrogen: oneOf: [{"$ref": "#/components/schemas/OperatingHydrogenResultSuccess"}, {"$ref": "#/components/schemas/OperatingDataBlockFailure"}] OperatingDataSummary: type: "object" description: "按车辆统计所选块的queryStatus；NO_DATA/异常仍为执行成功。successCount+partialSuccessCount+failedCount=returnedCount=requestedCount。" required: ["requestedCount", "returnedCount", "successCount", "partialSuccessCount", "failedCount"] properties: requestedCount: type: "integer" minimum: 0 returnedCount: type: "integer" minimum: 0 successCount: type: "integer" minimum: 0 partialSuccessCount: type: "integer" minimum: 0 failedCount: type: "integer" minimum: 0 OperatingDataResponse: type: "object" required: ["code", "message", "traceId", "queryDate", "timezone", "requestAt", "generatedAt", "data", "summary"] properties: code: type: "string" enum: ["SUCCESS"] message: type: "string" traceId: type: "string" queryDate: type: "string" format: "date" nullable: true description: "包含日统计时为dailyDate；仅实时为null。" timezone: type: "string" enum: ["Asia/Shanghai"] requestAt: type: "string" format: "date-time" generatedAt: type: "string" format: "date-time" data: type: "array" minItems: 0 items: {"$ref": "#/components/schemas/OperatingVehicleResult"} summary: {"$ref": "#/components/schemas/OperatingDataSummary"} OperatingErrorResponse: type: "object" required: ["code", "message", "traceId"] properties: code: type: "string" enum: ["INVALID_REQUEST", "BATCH_SIZE_EXCEEDED", "INVALID_DATE_FORMAT", "INVALID_DATE_RANGE", "UNAUTHORIZED", "FORBIDDEN", "PAYLOAD_TOO_LARGE", "RATE_LIMIT_EXCEEDED", "INTERNAL_ERROR"] message: type: "string" traceId: type: "string" VehicleDailyQuery: type: object additionalProperties: false required: [date] properties: plateNumbers: type: array maxItems: 200 uniqueItems: true items: type: string minLength: 1 maxLength: 32 description: 可选；指定时查询这些已授权车牌，省略或传空数组时查询该自然日有效授权的全部车辆 date: type: string format: date description: 查询自然日，yyyy-MM-dd MileageDailyQuery: type: object additionalProperties: false required: [date] properties: plateNumbers: type: array maxItems: 200 uniqueItems: true items: type: string minLength: 1 maxLength: 32 description: 可选；指定时查询这些已授权车牌，省略或传空数组时查询该自然日有效授权的全部车辆 date: type: string format: date description: 查询自然日，yyyy-MM-dd protocolPriority: $ref: '#/components/schemas/ProtocolPriority' MileageRangeQuery: type: object additionalProperties: false required: [startDate, endDate] properties: startDate: type: string format: date description: 区间开始自然日，Asia/Shanghai endDate: type: string format: date description: 区间结束自然日，含当日；与 startDate 最多相隔 1095 天（含首尾共1096天） plateNumbers: type: array maxItems: 5000 uniqueItems: true items: type: string minLength: 1 maxLength: 32 description: 可选；省略或传空数组时查询整个区间均有效授权的全部车辆 protocolPriority: $ref: '#/components/schemas/ProtocolPriority' cursor: type: string nullable: true description: 首次查询传 null 或省略；翻页时原样传入上一页 nextCursor pageSize: type: integer minimum: 1 maximum: 5000 default: 5000 ProtocolPriority: type: array minItems: 1 maxItems: 3 uniqueItems: true items: type: string enum: [GB32960, MQTT, JT808] description: 可选；按数组顺序逐车逐日选择第一个有效协议。未列出的协议被禁用且不会作为兜底；省略字段时保持平台默认选源行为 TotalMileageQuery: type: object additionalProperties: false required: [vin, time] properties: vin: type: string pattern: '^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$' description: 已授权车辆 VIN time: type: string pattern: '^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$' description: 请求时刻，北京时间，固定格式 yyyy-MM-dd HH:mm:ss protocol: type: string enum: [GB32960, YUTONG_MQTT, JT808] description: 可选；只接受平台统一协议标识；不传时按 GB32960 > YUTONG_MQTT > JT808 StationaryVehicleQuery: type: object additionalProperties: false required: [startTime, endTime, longitude, latitude] properties: startTime: type: string pattern: '^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$' description: 开始时间，北京时间，yyyy-MM-dd HH:mm:ss endTime: type: string pattern: '^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$' description: 结束时间，北京时间；须晚于开始时间，最长 24 小时 longitude: type: number format: double minimum: -180 maximum: 180 description: 加氢站经度；坐标系由 coordinateSystem 指定 latitude: type: number format: double minimum: -90 maximum: 90 description: 加氢站纬度；坐标系由 coordinateSystem 指定 coordinateSystem: type: string enum: [WGS84, GCJ02] default: WGS84 description: 坐标系；WGS84 为默认值，GCJ02 为高德地图坐标。GCJ02 会在服务端转换为 WGS84 后核验 radiusMeters: type: number format: double minimum: 1 maximum: 100 default: 5 description: 核验半径，单位米；省略时为 5 米 plateNumbers: type: array maxItems: 2000 uniqueItems: true items: type: string minLength: 1 maxLength: 32 description: 可选；省略或传空数组时核验整个时间区间均有效授权的全部车辆 RealtimeVehicleQuery: type: object additionalProperties: false properties: plateNumbers: type: array maxItems: 2000 uniqueItems: true items: type: string minLength: 1 maxLength: 32 description: 可选；省略或传空数组时查询当前有效授权的全部车辆 HistoricalHydrogenQuery: type: object additionalProperties: false required: [queries] properties: queries: type: array minItems: 1 maxItems: 200 items: type: object additionalProperties: false required: [requestId, vin, time] properties: requestId: { type: string, minLength: 1, maxLength: 128, description: 本批唯一非空关联标识，最多128字节，原样返回 } vin: { type: string, minLength: 17, maxLength: 17, pattern: '^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$', description: 查询VIN按大写规范化，禁止I/O/Q } time: { type: string, description: '北京时间 yyyy-MM-dd HH:mm:ss；不得早于2026-08-01或晚于请求时刻' } protocol: { type: string, enum: [GB32960, YUTONG_MQTT, JT808], default: GB32960, description: 省略固定GB32960；显式协议不切换，YUTONG_MQTT/JT808当前UNSUPPORTED } maxTimeDifferenceSeconds: type: integer minimum: 0 maximum: 300 default: 300 description: 允许采样早于查询的最大秒数；0要求精确命中，不静默放宽 HistoricalHydrogenQueryResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: [data] properties: data: type: array items: { $ref: '#/components/schemas/HistoricalHydrogenResult' } HistoricalHydrogenResult: type: object required: [requestId, vin, plateNumber, queryTime, remainingHydrogenKg, hydrogenRecordTime, timeDifferenceSeconds, remainingHydrogenKgStatus, hydrogenValueSource, hydrogenSourceProtocol, sourceRecordId, sourceDataVersion, hydrogenEstimatePressureMPa, hydrogenEstimateTemperatureC, hydrogenTankCapacityL, hydrogenPressureTemperatureSource, hydrogenCalculationVersion, hydrogenCapacityVersion, updatedAt, reasonCode, message] properties: requestId: { type: string, description: 本批对应请求标识 } vin: { type: string } plateNumber: { type: string, nullable: true, description: 无可证明历史车牌时为 null，不冒用当前车牌 } queryTime: { type: string, description: 请求北京时间 } remainingHydrogenKg: { type: number, nullable: true, minimum: 0, description: '全车剩余氢质量kg，保留源/模型计算精度；仅NORMAL可用，其他状态null。不得用缺值补0' } hydrogenRecordTime: { type: string, format: date-time, nullable: true, description: 真实原始帧 event_time，RFC3339带时区 } timeDifferenceSeconds: { type: number, nullable: true, minimum: 0, description: queryTime减真实采集时间的秒数 } remainingHydrogenKgStatus: type: string enum: [NORMAL, NO_DATA, MISSING, STALE, UNSUPPORTED, INVALID, FORBIDDEN, ERROR] description: 仅NORMAL参与业务计算；ERROR明确为处理失败，可按原因重试；FORBIDDEN不泄露采样 hydrogenValueSource: { type: string, nullable: true, enum: [REPORTED, ESTIMATED], description: 终端上报不等同于直接测量；估算需历史温压/容积证据 } hydrogenSourceProtocol: { type: string, nullable: true, enum: [GB32960, YUTONG_MQTT, JT808] } sourceRecordId: { type: string, nullable: true, description: raw-sha256采样身份指纹；两端相同需识别采样分辨率不足，内容修订另看sourceDataVersion } sourceDataVersion: { type: string, nullable: true, description: 'sha256原始JSON和解析状态内容指纹；同采样被修订时变化，不是两端必须相等的口径版本' } hydrogenEstimatePressureMPa: { type: number, nullable: true, description: 有效同帧最大氢压MPa证据，缺历史容量仍可诊断返回 } hydrogenEstimateTemperatureC: { type: number, nullable: true, description: 有效同帧最大氢温摄氏度证据 } hydrogenTankCapacityL: { type: number, nullable: true, description: 当前缺历史容量版本始终null，不能回套当前容积 } hydrogenPressureTemperatureSource: { type: string, nullable: true, enum: [MAX_SENSOR_AGGREGATE], description: 最大温压聚合不保证同瓶 } hydrogenCalculationVersion: { type: string, nullable: true, description: 当前REPORTED_HYDROGEN_KG_V1，质量不额外舍入；ESTIMATED预留但当前缺历史容积版本不输出估算值 } hydrogenCapacityVersion: { type: string, nullable: true, description: 历史时点适用容积版本；估算必需，无证据不估算 } updatedAt: { type: string, format: date-time, nullable: true, description: 原始记录received_at，RFC3339带时区；不代替采集时间，同时间戳修订通过sourceDataVersion识别 } reasonCode: { type: string, nullable: true, description: 可程序识别的状态原因 } message: { type: string, nullable: true, description: 中文状态说明 } HydrogenStationQuery: type: object additionalProperties: false properties: province: type: string maxLength: 32 city: type: string maxLength: 32 cooperateOnly: type: boolean description: true仅合作站，false仅外部站，省略则返回全部 HydrogenResult: type: object required: [vin, plateNumber, date, hydrogenConsumptionKg, statisticsStartTime, statisticsEndTime, updatedAt, status] properties: vin: type: string description: 授权车辆 VIN，供跨接口身份校验 plateNumber: type: string date: type: string format: date hydrogenConsumptionKg: type: number format: double nullable: true description: 单日用氢量，kg；OK 和 SUSPECT 计算结果均返回数值，无数据时为 null statisticsStartTime: type: string format: date-time nullable: true description: FINAL 证据区间最早开始时间；PRELIMINARY 仅有结束水位故为 null；缺失或异常证据为 null。边界是证据包络，不承诺连续覆盖 statisticsEndTime: type: string format: date-time nullable: true description: FINAL 证据区间最晚结束时间，PRELIMINARY 为真实 lastEventTime 水位；缺失或异常证据为 null；不是 API 查询时间 updatedAt: type: string format: date-time nullable: true description: 同一用氢统计行的数据库更新时间，RFC 3339 带时区；无统计行时为 null calculationPhase: type: string enum: [PRELIMINARY, FINAL] description: PRELIMINARY 仅供标注为初步的日内监控；FINAL 表示批量重算已完成，补传或算法调整仍可能再次重算，不保证固定结算时刻 algorithmVersion: type: string description: 氢耗计算算法版本 qualityStatus: type: string enum: [OK, SUSPECT, NO_DATA] description: OK 对应 NORMAL；SUSPECT 对应 DATA_ANOMALY 并保留数值供审计，不得用于正常百公里氢耗；NO_DATA 对应无可用统计 qualityReason: type: string description: 质量判定原因；SUSPECT 或 NO_DATA 时供调用方解释和审计 status: $ref: '#/components/schemas/DataStatus' MileageResult: type: object required: [vin, plateNumber, date, dailyMileageKm, totalMileageKm, dataTime, updatedAt, sourceProtocol, statisticsStartTime, statisticsEndTime, status] properties: vin: type: string plateNumber: type: string date: type: string format: date dailyMileageKm: type: number format: double nullable: true description: 相邻自然日同来源累计值之差，km；跨缺报期增量计入恢复日；缺报日为 0；首次基线、来源变化和累计异常时为 null totalMileageKm: type: number format: double nullable: true description: 当日所选协议最后有效终端累计总里程，km；GPS 日里程估算不会作为累计总里程。status=NORMAL 时必定有值，NO_DATA 时为 null statisticsStartTime: type: string format: date-time nullable: true description: 日里程起点累计读数的时间；可跨越多个缺报日；历史结转补零或无数据时为 null statisticsEndTime: type: string format: date-time nullable: true description: 当日所选来源最晚 latest_event_time，等于 dataTime；历史结转补零或无数据时为 null。与用氢接口无共同快照保证 dataTime: type: string format: date-time nullable: true description: 本次统计实际采用的最后一条车辆源数据时间；status=NO_DATA 时为 null updatedAt: type: string format: date-time nullable: true description: 本行所依据统计周期的计算时间；前向填充时为上一统计周期计算时间，status=NO_DATA 时为 null sourceProtocol: type: string enum: [GB32960, MQTT, JT808] nullable: true description: 本行实际选中的来源协议；status=NO_DATA 时为 null dataQuality: type: string nullable: true enum: [TOTAL_MILEAGE_ROLLBACK, ODOMETER_SOURCE_CHANGED, NO_PREVIOUS_BASELINE, PREVIOUS_ODOMETER_ANOMALY, CARRIED_FORWARD, outside_daily_range, INVALID_DELTA] description: CARRIED_FORWARD 表示缺报结转；其他值表示无法连续对账的原因，此时 dailyMileageKm 为 null，保留累计读数及来源证据 status: $ref: '#/components/schemas/DataStatus' MileageRangeResult: type: object required: [vin, plateNumber, date, dailyMileageKm, totalMileageKm, dataTime, updatedAt, sourceProtocol, status] properties: vin: type: string plateNumber: type: string date: type: string format: date dailyMileageKm: type: number format: double nullable: true minimum: 0 description: 当日无记录但存在历史累计里程时为 0 totalMileageKm: type: number format: double nullable: true minimum: 0 description: 当日所选协议终端累计总里程；GPS 日里程估算不会作为累计总里程，缺日时沿用此前最近有效值 dataTime: type: string format: date-time nullable: true updatedAt: type: string format: date-time nullable: true description: 本行所依据统计周期的计算时间；缺日补齐时为上一统计周期计算时间 sourceProtocol: type: string enum: [GB32960, MQTT, JT808] nullable: true description: 本行实际选中的来源协议；status=NO_DATA 时为 null dataQuality: type: string nullable: true enum: [TOTAL_MILEAGE_ROLLBACK, ODOMETER_SOURCE_CHANGED, NO_PREVIOUS_BASELINE, PREVIOUS_ODOMETER_ANOMALY, CARRIED_FORWARD, outside_daily_range, INVALID_DELTA] description: CARRIED_FORWARD 表示缺报结转；其他值表示无法连续对账的原因，此时 dailyMileageKm 为 null，保留累计读数及来源证据 status: $ref: '#/components/schemas/DataStatus' DataStatus: type: string enum: [NORMAL, NO_DATA, DATA_ANOMALY] description: NORMAL=存在可用数据；NO_DATA=授权范围内无可用数据；DATA_ANOMALY=检测到数据异常，详情见 dataQuality HydrogenQueryResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/HydrogenResult' MileageQueryResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/MileageResult' MileageRangeQueryResponse: type: object required: [code, message, data, snapshotId, nextCursor, traceId] properties: code: type: string enum: [SUCCESS] message: type: string example: success data: type: array items: $ref: '#/components/schemas/MileageRangeResult' snapshotId: type: string description: 同一次分页查询保持不变的授权车辆快照标识 nextCursor: type: string nullable: true description: 下一页游标；最后一页为 null traceId: type: string TotalMileageResult: type: object required: [vin, queryTime, totalMileageKm, selectionPolicy, status] properties: vin: type: string queryTime: type: string description: 请求时刻，北京时间 totalMileageKm: type: number format: double nullable: true description: 总里程，km；无数据时为 null protocol: type: string enum: [GB32960, YUTONG_MQTT, JT808] description: 实际采用的采集协议 protocolInput: type: string description: 请求中指定的协议原值；未指定时省略 mileageMeaning: type: string description: 当前协议总里程的业务含义 recordTime: type: string description: 命中的实际采集记录时间，北京时间 timeDifferenceSeconds: type: integer format: int64 minimum: 0 description: 请求时间减实际记录时间，单位秒 selectionPolicy: type: string example: GB32960 > YUTONG_MQTT > JT808 status: $ref: '#/components/schemas/DataStatus' StationaryVehicleResult: type: object required: [vin, plateNumber, stayStartTime, stayEndTime, stayDurationSeconds, stayDurationMinutes, matchScore, averageDistanceMeters, maxDistanceMeters, averageSpeedKmh, maxSpeedKmh, matchedSamples, sourceProtocols] properties: vin: { type: string, description: 车辆唯一 VIN } plateNumber: { type: string, description: 车辆车牌号 } stayStartTime: { type: string, description: 停留开始定位时间，北京时间 } stayEndTime: { type: string, description: 停留结束定位时间，北京时间 } stayDurationSeconds: { type: integer, description: 停留长度，秒 } stayDurationMinutes: { type: number, format: double, description: 停留长度，分钟 } matchScore: { type: number, format: double, minimum: 0, maximum: 100, description: 匹配度，越高表示位置更接近、速度更低、停留更久且样本更充分 } averageDistanceMeters: { type: number, format: double } maxDistanceMeters: { type: number, format: double } averageSpeedKmh: { type: number, format: double } maxSpeedKmh: { type: number, format: double, maximum: 3 } matchedSamples: { type: integer, minimum: 2 } sourceProtocols: type: array items: { type: string, enum: [GB32960, MQTT, JT808] } TotalMileageQueryResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: [data] properties: data: $ref: '#/components/schemas/TotalMileageResult' StationaryVehicleQueryResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/StationaryVehicleResult' RealtimeVehicleResult: type: object required: [vin, plateNumber, online, motionStatus, locationAvailable, status, remainingHydrogenKg, remainingHydrogenPercent, hydrogenRecordTime, hydrogenDataStatus, remainingHydrogenKgStatus, remainingHydrogenPercentStatus, hydrogenValueSource, hydrogenSourceProtocol, hydrogenStaleAfterSeconds, hydrogenExpectedIntervalSeconds, remainingHydrogenPercentSource, hydrogenFullCapacityKg, hydrogenTankCapacityL, hydrogenFullPressureMPa, hydrogenReferenceTemperatureC, hydrogenEstimatePressureMPa, hydrogenEstimateTemperatureC, hydrogenPressureTemperatureSource, hydrogenCalculationVersion, hydrogenCapacitySource, hydrogenPercentReason, gpsFixStatus, locationRecordTime, coordinateSystem] properties: vin: { type: string } plateNumber: { type: string } remainingHydrogenKg: type: number nullable: true minimum: 0 maximum: 500 description: 全车氢质量 kg；优先 GB32960 广东扩展终端上报（0–200 kg），缺质量时以同帧最大氢压/氢温和 VIN 全车水容积作实气估算（0–500 kg）。真实零保留，缺失/异常为 null，陈旧值保留并标 STALE remainingHydrogenPercent: type: number nullable: true minimum: 0 maximum: 100 description: 剩余质量除以 VIN 水容积在 35 MPa、15°C 的实气模型满充质量乘100，属于 ESTIMATED；缺容量为 null/MISSING。超过100返回 null/INVALID，不截断为100，kg独立保留；不以动力电池SOC替代 hydrogenRecordTime: type: string format: date-time nullable: true description: 氢质量对应原始同帧实际采集时间，RFC 3339 带时区；不是请求时间或缓存更新时间 hydrogenDataStatus: type: string enum: [NORMAL, PARTIAL, STALE, MISSING, UNSUPPORTED, INVALID] description: NORMAL 两项有效（可包含估算，见来源）；PARTIAL 部分字段有效；STALE 数据陈旧；MISSING 缺少数据或容量；UNSUPPORTED 不支持；INVALID 异常。数值和字段级状态独立判断 remainingHydrogenKgStatus: type: string enum: [NORMAL, STALE, MISSING, UNSUPPORTED, INVALID] remainingHydrogenPercentStatus: type: string enum: [NORMAL, STALE, MISSING, UNSUPPORTED, INVALID] description: 独立于 kg 状态；容量缺失 MISSING，比例超100 INVALID；有值时继承 kg 的 NORMAL 或 STALE hydrogenValueSource: type: string nullable: true enum: [REPORTED, ESTIMATED] description: kg 来源；REPORTED 仅确认终端上报，无法判断终端内部测量或估算；ESTIMATED 为平台压力/温度/容积实气模型估算 remainingHydrogenPercentSource: type: string nullable: true enum: [ESTIMATED] description: 百分比始终为模型满充容量推算；与 kg 来源独立，计算前缺条件时为 null hydrogenFullCapacityKg: type: number nullable: true description: 实际用于比例分母的未舍入满充质量，kg；PressureHydrogenMassKg(35,15,VIN水容积)，不是扣除残余后的可用容量 hydrogenTankCapacityL: type: number nullable: true description: VIN 配置的全车储氢水容积，L；必须 active 且大于0、不超过10000，不根据车型臆造默认值 hydrogenFullPressureMPa: type: number nullable: true enum: [35] description: 本次业务确认的满充参考压力，MPa；不代表自动核验每辆车铭牌额定压力 hydrogenReferenceTemperatureC: type: number nullable: true enum: [15] description: 满充参考温度，摄氏度 hydrogenEstimatePressureMPa: type: number nullable: true description: 仅平台估算 kg 时使用的同帧最大氢压，MPa；支持0，不补默认值 hydrogenEstimateTemperatureC: type: number nullable: true description: 仅平台估算 kg 时使用的同帧最大氢温，摄氏度；模型输入范围−40–726.85°C，不是车辆安全温度阈值；缺失不补默认温度 hydrogenPressureTemperatureSource: type: string nullable: true enum: [MAX_SENSOR_AGGREGATE] description: 最大氢压/最大氢温聚合读数近似；两者不保证来自同一瓶，不是逐瓶质量求和或全瓶完整性证明 hydrogenCalculationVersion: type: string nullable: true enum: [REAL_GAS_35MPA_15C_V1] description: 实时储氢模型版本；不修改日用氢算法 hydrogenCapacitySource: type: string nullable: true enum: [vehicle_hydrogen_tank_capacity] description: 满充容量采用的 VIN 配置数据表 hydrogenPercentReason: type: string nullable: true enum: [MISSING_HYDROGEN_MEASUREMENT, INVALID_MASS_READING, INVALID_PRESSURE_TEMPERATURE, INCOMPLETE_PRESSURE_TEMPERATURE, MISSING_TANK_CAPACITY, MASS_CALCULATION_FAILED, EXCEEDS_NOMINAL_FULL_CAPACITY] description: 缺少或拒绝百分比的原因；超出业务满充参考仅拒绝百分比，不伪装为100，也不据此判断车辆安全状态 hydrogenSourceProtocol: type: string nullable: true enum: [GB32960, MQTT, JT808] description: 储氢数据采用的协议，独立于位置的 protocol hydrogenStaleAfterSeconds: type: integer nullable: true description: GB32960 服务时效策略为 300 秒；不是协议采样周期承诺 hydrogenExpectedIntervalSeconds: type: integer nullable: true description: 当前无已确认上报周期，固定 null gpsFixStatus: type: string enum: [FIXED, NO_FIX, UNKNOWN] description: 实际位置报文定位位；GB32960 bit0=0、JT808 bit1=1 表示 FIXED；MQTT 或缺少可信定位位为 UNKNOWN。不以在线或数据年龄推断 locationRecordTime: type: string format: date-time nullable: true description: 位置行对应实际采集时间，独立于主记录 recordTime；历史 FIXED 不因车辆离线改变 coordinateSystem: type: string enum: [WGS84, GCJ02, UNKNOWN] description: 仅 GB2025 显式坐标类型 1=WGS84、2=GCJ02，其余 UNKNOWN；GB2016/JT808/MQTT 当前无确证为 UNKNOWN，未知坐标系不得直接当高德坐标使用 protocol: type: string enum: [GB32960, MQTT, JT808] description: 本条实时位置、速度、里程及记录时间实际采用的采集协议；GB32960=车辆协议，MQTT=MQTT车端来源，JT808=定位终端来源 longitude: { type: number, format: double, nullable: true, description: 所选来源的最新有效经度；无位置时为 null } latitude: { type: number, format: double, nullable: true, description: 所选来源的最新有效纬度；无位置时为 null } speedKmh: { type: number, format: double, nullable: true, description: 所选来源瞬时速度，单位 km/h } socPercent: { type: number, format: double, minimum: 0, maximum: 100, description: 所选来源的动力电池荷电状态，单位 %；无有效采集值时字段省略 } totalMileageKm: { type: number, format: double, nullable: true, description: 所选来源累计总里程，单位 km } recordTime: { type: string, description: 所选来源实际记录时间，北京时间 } timeDifferenceSeconds: { type: integer, format: int64, minimum: 0, description: 当前查询时间减 recordTime，单位秒 } online: { type: boolean, description: 任一采集协议是否在最近60秒内上报 } activeToday: { type: boolean, description: 任一采集协议在当前自然日（Asia/Shanghai）内上报过 } motionStatus: { type: string, enum: [driving, idle, offline], description: driving=在线且速度大于3km/h；idle=在线且速度不大于3km/h；offline=当前不在线或无实时记录 } locationAvailable: { type: boolean, description: true=longitude/latitude 有效；false=当前无有效位置 } status: { $ref: '#/components/schemas/DataStatus' } RealtimeVehicleQueryResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: [data] properties: data: type: array items: { $ref: '#/components/schemas/RealtimeVehicleResult' } HydrogenStation: type: object required: [id, name, longitude, latitude, cooperative] properties: id: { type: string, description: 站点ID使用字符串避免JavaScript整数精度损失 } name: { type: string } shortName: { type: string } address: { type: string } longitude: { type: number, format: double } latitude: { type: number, format: double } province: { type: string } city: { type: string } district: { type: string } cooperative: { type: boolean } HydrogenStationQueryResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: [data] properties: data: type: array items: { $ref: '#/components/schemas/HydrogenStation' } SuccessEnvelope: type: object required: [code, message, traceId] properties: code: type: string enum: [SUCCESS] message: type: string example: success traceId: type: string example: 4ccf63c4e51d4d4ab9107d931783a53e ErrorResponse: type: object required: [code, message, traceId] properties: code: type: string enum: - INVALID_REQUEST - INVALID_DATE_FORMAT - UNAUTHORIZED - FORBIDDEN - INTERNAL_ERROR message: type: string traceId: type: string AppInput: type: object additionalProperties: false required: [name, status, validFrom] properties: name: type: string maxLength: 96 example: 示例合作方 status: type: string enum: [enabled, disabled] validFrom: type: string format: date-time example: '2026-07-01T00:00:00+08:00' validTo: type: string format: date-time nullable: true example: '2027-07-01T00:00:00+08:00' App: type: object required: [id, name, appKeyPrefix, status, validFrom] properties: id: type: integer format: int64 name: type: string appKeyPrefix: type: string minLength: 8 maxLength: 8 status: type: string enum: [enabled, disabled] validFrom: type: string format: date-time validTo: type: string format: date-time nullable: true AppCreated: allOf: - $ref: '#/components/schemas/App' - type: object required: [appKey] properties: appKey: type: string minLength: 32 maxLength: 32 pattern: '^[0-9a-f]{32}$' description: 仅本次响应返回 VehicleGrantRequest: type: object additionalProperties: false required: [vehicles] properties: vehicles: type: array maxItems: 500 items: $ref: '#/components/schemas/VehicleGrantInput' VehicleGrantInput: type: object additionalProperties: false required: [vin, validFrom] properties: vin: type: string minLength: 17 maxLength: 17 validFrom: type: string format: date-time validTo: type: string format: date-time nullable: true AdminAppListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/App' traceId: type: string AdminAppCreatedResponse: type: object properties: data: $ref: '#/components/schemas/AppCreated' traceId: type: string