跳到主要内容
开发者文档API 参考车辆

查询车辆

一辆预设车辆或您自己的车辆。

GEThttps://runner.cargoduo.com/v1/vehicles/{id}

免费,不扣积分。

认证

Bearer API 密钥 · 所需权限范围resources:read了解更多

路径参数

名称类型必填说明
idstring必填
string
是

预设车辆 ID,或您自己车辆的 ID(veh_…)。

请求示例

curl -X GET "https://runner.cargoduo.com/v1/vehicles/veh_118" \
  -H "Authorization: Bearer $CARGODUO_API_KEY"

响应示例

200 OK · SavedVehicle
{
  "id": "veh_118",
  "object": "vehicle",
  "kind": "custom",
  "name": "Mega trailer 13.6 m",
  "type": "trailer",
  "length": 1360,
  "width": 248,
  "height": 300,
  "max_weight": 24000,
  "floor_load_capacity": null,
  "axle_positions": [],
  "axle_max_loads": [],
  "cog_range_x": null,
  "cog_range_y": null,
  "aux_deck": false,
  "aux_deck_height": null,
  "aux_deck_max_weight": null,
  "tractor_weight": null,
  "empty_trailer_weight": null,
  "front_axle_to_middle_axle": null,
  "front_axle_to_tractor_cog": null,
  "front_axle_to_kingpin": null,
  "kingpin_to_rear_axle": null,
  "trailer_cog_to_rear_axle": null,
  "trailer_start_to_kingpin": null,
  "max_middle_axle_weight": null,
  "max_rear_axle_weight": null,
  "blocked_areas": [],
  "created_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "updated_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "created_at": "2026-10-02T08:41:17Z"
}

响应

  • 200OK该车辆。
    名称类型必填说明
    idstring
    string
    否

    预设车辆 ID;您自己的车辆为 veh_…。

    objectstring
    string
    否
    vehicle
    kindstring
    string
    否

    preset = 预定义目录中的车辆;custom = 您组织自己的车辆。

    presetcustom
    typestring
    string
    否

    车辆类型。仅接受 GET /v1/limits 中列出的类型(allowed_vehicle_types)。

    trucktrailerflatbedcontainerpalletaircraftship
    namestring
    string
    否

    显示名称。

    lengthnumber · cm
    number · cm
    否

    货厢内部长度,沿 x 轴(从前壁指向车门)。

    widthnumber · cm
    number · cm
    否

    货厢内部宽度,沿 z 轴。

    heightnumber · cm
    number · cm
    否

    货厢内部高度,沿 y 轴。

    max_weightnumber · kg
    number · kg
    否

    最大载重。

    floor_load_capacitynumber | null · kg/m²
    number | null · kg/m²
    否

    地板承重:0 或更大(0 = 不限)。

    axle_positionsnumber[] · cm
    number[] · cm
    否

    车轴(支撑点)位置,从货厢前端起算;负值 = 位于货厢前方。数组长度与 axle_max_loads 相同。每个值介于 −300(位于货厢前方的车轴,例如单体卡车驾驶室下方的前轴)与车辆长度之间。

    axle_max_loadsnumber[] · kg
    number[] · kg
    否

    每根车轴的最大货物载荷,顺序与 axle_positions 一致。每个值须大于 0 且不超过 100000。

    cog_range_xnumber | null · cm
    number | null · cm
    否

    重心相对长度中点的允许偏移:0 到 length / 2。

    cog_range_ynumber | null · cm
    number | null · cm
    否

    重心相对宽度中点的允许偏移:0 到 width / 2。

    aux_deckboolean
    boolean
    否

    车辆有第二层甲板(双层车)。

    aux_deck_heightnumber | null · cm
    number | null · cm
    否

    第二层甲板距地板的高度。aux_deck 为 true 时必填。

    aux_deck_max_weightnumber | null · kg
    number | null · kg
    否

    第二层甲板的载重上限。aux_deck 为 true 时必填。

    tractor_weightnumber | null · kg
    number | null · kg
    否

    半挂车轴荷模型:牵引车质量。

    empty_trailer_weightnumber | null · kg
    number | null · kg
    否

    半挂车轴荷模型:挂车空载质量。

    front_axle_to_middle_axlenumber | null · cm
    number | null · cm
    否

    半挂车轴荷模型:牵引车前轴到驱动轴(中轴)的距离。

    front_axle_to_tractor_cognumber | null · cm
    number | null · cm
    否

    半挂车轴荷模型:前轴到牵引车重心的距离。

    front_axle_to_kingpinnumber | null · cm
    number | null · cm
    否

    半挂车轴荷模型:前轴到牵引销(鞍座)的距离。

    kingpin_to_rear_axlenumber | null · cm
    number | null · cm
    否

    半挂车轴荷模型:牵引销到挂车后轴组的距离。

    trailer_cog_to_rear_axlenumber | null · cm
    number | null · cm
    否

    半挂车轴荷模型:挂车重心到后轴组的距离。

    trailer_start_to_kingpinnumber | null · cm
    number | null · cm
    否

    半挂车轴荷模型:挂车前端到牵引销的距离。

    max_middle_axle_weightnumber | null · kg
    number | null · kg
    否

    半挂车轴荷模型:驱动轴(中轴)的法定限值。

    max_rear_axle_weightnumber | null · kg
    number | null · kg
    否

    半挂车轴荷模型:后轴组的法定限值。

    blocked_areasRect[]
    Rect[]
    否

    禁止放置货物的地板区域(轮拱、破损处、预留空间)。每个区域都必须位于车辆地板范围内。

    created_byUserRef | null
    UserRef | null
    否

    创建者(通过 API 调用时为创建该密钥的成员)。未知时为 null。

    updated_byUserRef | null
    UserRef | null
    否

    最后修改它的成员。

    created_atstring | null
    string | null
    否

    RFC 3339 格式;预设车辆为 null。

  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedAPI 密钥缺失、格式错误或无法识别。
    • key_revoked密钥已被撤销。
    • key_expired密钥已过期。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowed调用方 IP 不在该密钥的 IP 白名单中。
    • subscription_inactive组织没有包含 API 的有效订阅。
    • account_inactive组织已被暂停使用,或其所有者的账户均未处于有效状态。
    • scope_missing密钥缺少此接口所需的权限范围。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 404Not foundvehicle_not_found
    • vehicle_not_found预设车辆和您组织的车辆中都没有此 ID。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 429Too many requestsrate_limited
    • rate_limited当前分钟、小时或天内的请求过多(按密钥或按组织计),或您的 IP 地址每分钟认证失败超过 60 次。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 500Internal server errorinternal_error
    • internal_error服务端发生内部错误。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码
  • 503Service unavailableapi_disabled
    • api_disabledAPI 暂时停用(维护中),或已对该组织关闭。
    名称类型必填说明
    errorErrorBody必填
    ErrorBody
    是
    全部错误码