554 lines
16 KiB
YAML
554 lines
16 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: 车辆数据开放平台 API
|
|
version: 1.1.0
|
|
license:
|
|
name: Proprietary
|
|
description: |
|
|
向授权合作方开放车辆单日用氢量、单日里程和指定时刻总里程。
|
|
appKey 和逐车授权必须完整覆盖查询自然日。
|
|
servers:
|
|
- url: /
|
|
description: 当前服务
|
|
tags:
|
|
- name: 合作方数据接口
|
|
description: 使用 appKey 查询已授权车辆的日统计数据
|
|
- name: 开放平台管理
|
|
description: 仅车辆数据平台管理员可调用的应用和车辆授权管理接口
|
|
paths:
|
|
/api/v1/vehicles/hydrogen-consumption/query:
|
|
post:
|
|
tags: [合作方数据接口]
|
|
summary: 查询车辆单日用氢量
|
|
operationId: queryDailyHydrogenConsumption
|
|
security:
|
|
- AppKeyAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VehicleDailyQuery'
|
|
example:
|
|
plateNumbers: [粤A12345, 粤B67890]
|
|
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: 查询车辆单日里程
|
|
operationId: queryDailyMileage
|
|
security:
|
|
- AppKeyAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VehicleDailyQuery'
|
|
example:
|
|
plateNumbers: [粤A12345]
|
|
date: '2026-07-01'
|
|
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/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: '32960'
|
|
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/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:
|
|
VehicleDailyQuery:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [plateNumbers, date]
|
|
properties:
|
|
plateNumbers:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 200
|
|
uniqueItems: true
|
|
items:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 32
|
|
description: 需要查询的车牌号
|
|
date:
|
|
type: string
|
|
format: date
|
|
description: 查询自然日，yyyy-MM-dd
|
|
TotalMileageQuery:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [vin, time]
|
|
properties:
|
|
vin:
|
|
type: string
|
|
pattern: '^[A-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: ['32960', mqtt, '808', GB32960, YUTONG_MQTT, JT808]
|
|
description: 可选；不传时按 GB32960 > YUTONG_MQTT > JT808
|
|
HydrogenResult:
|
|
type: object
|
|
required: [plateNumber, date, hydrogenConsumptionKg, status]
|
|
properties:
|
|
plateNumber:
|
|
type: string
|
|
date:
|
|
type: string
|
|
format: date
|
|
hydrogenConsumptionKg:
|
|
type: number
|
|
format: double
|
|
nullable: true
|
|
description: 单日用氢量，kg；无数据时为 null
|
|
status:
|
|
$ref: '#/components/schemas/DataStatus'
|
|
MileageResult:
|
|
type: object
|
|
required: [plateNumber, date, dailyMileageKm, status]
|
|
properties:
|
|
plateNumber:
|
|
type: string
|
|
date:
|
|
type: string
|
|
format: date
|
|
dailyMileageKm:
|
|
type: number
|
|
format: double
|
|
nullable: true
|
|
description: 单日里程，km；无数据时为 null
|
|
status:
|
|
$ref: '#/components/schemas/DataStatus'
|
|
DataStatus:
|
|
type: string
|
|
enum: [NORMAL, NO_DATA]
|
|
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'
|
|
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'
|
|
TotalMileageQueryResponse:
|
|
allOf:
|
|
- $ref: '#/components/schemas/SuccessEnvelope'
|
|
- type: object
|
|
required: [data]
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/TotalMileageResult'
|
|
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
|
|
- PLATE_NUMBERS_EMPTY
|
|
- 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
|