Saltar para o conteúdo
CargoDuo logoCargoDuo
Preços
Entrar

Por enquanto, esta documentação está disponível só em inglês.

Create a vehicle

Saves a vehicle to your organization's fleet (it shows in the app too).

POSThttps://runner.cargoduo.com/v1/vehicles

Same fields and access rules as a /v1/pack vehicle, judged by the app's size and payload limits for its type. Free: no credits are charged.

Autenticação

Chave de API Bearer com a permissãoresources:writeSaber mais

Parâmetros do corpo

application/json
NomeTipoObrigatórioDescrição
typestringobrigatório
string
Sim

Vehicle type. Only the types listed in GET /v1/limits (allowed_vehicle_types) are accepted.

trucktrailerflatbedcontainerpalletaircraftship
namestringobrigatório
string
Sim

Display name.

≤ 255 chars
lengthnumber · cmobrigatório
number · cm
Sim

Internal cargo-space length, along x (from the front wall toward the door).

widthnumber · cmobrigatório
number · cm
Sim

Internal cargo-space width, along z.

heightnumber · cmobrigatório
number · cm
Sim

Internal cargo-space height, along y.

max_weightnumber · kgobrigatório
number · kg
Sim

Maximum payload.

floor_load_capacitynumber · kg/m²
number · kg/m²
Não

Floor load capacity: 0 or more (0 = no limit).

aux_deckboolean
boolean
Não

The vehicle has a second deck (double-decker).

Predefinição false
aux_deck_heightnumber · cm
number · cm
Não

Second deck height above the floor. Required when aux_deck is true.

aux_deck_max_weightnumber · kg
number · kg
Não

Load limit of the second deck. Required when aux_deck is true.

blocked_areasRect[]
Rect[]
Não

Floor zones nothing may stand on (wheel arches, damage, reserved space). Each must lie on the vehicle floor.

≤ 32 items
axle_positionsAcesso mediante pedidonumber[] · cm
number[] · cm
Não

Axle (support point) positions measured from the front of the cargo area; negative = in front of it. Same length as axle_max_loads. Each between −300 (an axle ahead of the cargo area, e.g. a rigid truck's front axle under the cab) and the vehicle length.

≤ 10 items
axle_max_loadsAcesso mediante pedidonumber[] · kg
number[] · kg
Não

Maximum cargo load per axle, in the order of axle_positions. Each greater than 0 and at most 100000.

≤ 10 items
cog_range_xAcesso mediante pedidonumber · cm
number · cm
Não

Allowed centre-of-gravity deviation from the middle of the length: 0 to length / 2.

cog_range_yAcesso mediante pedidonumber · cm
number · cm
Não

Allowed centre-of-gravity deviation from the middle of the width: 0 to width / 2.

tractor_weightAcesso mediante pedidonumber · kg
number · kg
Não

Semi-trailer axle model: tractor unit mass.

empty_trailer_weightAcesso mediante pedidonumber · kg
number · kg
Não

Semi-trailer axle model: unladen trailer mass.

front_axle_to_middle_axleAcesso mediante pedidonumber · cm
number · cm
Não

Semi-trailer axle model: tractor front axle to drive (middle) axle.

front_axle_to_tractor_cogAcesso mediante pedidonumber · cm
number · cm
Não

Semi-trailer axle model: front axle to tractor centre of gravity.

front_axle_to_kingpinAcesso mediante pedidonumber · cm
number · cm
Não

Semi-trailer axle model: front axle to kingpin (fifth wheel).

kingpin_to_rear_axleAcesso mediante pedidonumber · cm
number · cm
Não

Semi-trailer axle model: kingpin to trailer rear axle group.

trailer_cog_to_rear_axleAcesso mediante pedidonumber · cm
number · cm
Não

Semi-trailer axle model: trailer centre of gravity to rear axle group.

trailer_start_to_kingpinAcesso mediante pedidonumber · cm
number · cm
Não

Semi-trailer axle model: trailer front to kingpin.

max_middle_axle_weightAcesso mediante pedidonumber · kg
number · kg
Não

Semi-trailer axle model: legal drive (middle) axle limit.

max_rear_axle_weightAcesso mediante pedidonumber · kg
number · kg
Não

Semi-trailer axle model: legal rear axle group limit.

Exemplo de pedido

curl -X POST "https://runner.cargoduo.com/v1/vehicles" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mega trailer 13.6 m",
    "type": "trailer",
    "length": 1360,
    "width": 248,
    "height": 300,
    "max_weight": 24000
  }'

Exemplo de resposta

201 · 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"
}

Respostas

  • 201The new vehicle.
    NomeTipoObrigatórioDescrição
    idstring
    string
    Não

    Preset id, or veh_… for your own vehicles.

    objectstring
    string
    Não
    vehicle
    kindstring
    string
    Não

    preset = the predefined catalogue; custom = your organization's.

    presetcustom
    typestring
    string
    Não

    Vehicle type. Only the types listed in GET /v1/limits (allowed_vehicle_types) are accepted.

    trucktrailerflatbedcontainerpalletaircraftship
    namestring
    string
    Não

    Display name.

    lengthnumber · cm
    number · cm
    Não

    Internal cargo-space length, along x (from the front wall toward the door).

    widthnumber · cm
    number · cm
    Não

    Internal cargo-space width, along z.

    heightnumber · cm
    number · cm
    Não

    Internal cargo-space height, along y.

    max_weightnumber · kg
    number · kg
    Não

    Maximum payload.

    floor_load_capacitynumber | null · kg/m²
    number | null · kg/m²
    Não

    Floor load capacity: 0 or more (0 = no limit).

    axle_positionsnumber[] · cm
    number[] · cm
    Não

    Axle (support point) positions measured from the front of the cargo area; negative = in front of it. Same length as axle_max_loads. Each between −300 (an axle ahead of the cargo area, e.g. a rigid truck's front axle under the cab) and the vehicle length.

    axle_max_loadsnumber[] · kg
    number[] · kg
    Não

    Maximum cargo load per axle, in the order of axle_positions. Each greater than 0 and at most 100000.

    cog_range_xnumber | null · cm
    number | null · cm
    Não

    Allowed centre-of-gravity deviation from the middle of the length: 0 to length / 2.

    cog_range_ynumber | null · cm
    number | null · cm
    Não

    Allowed centre-of-gravity deviation from the middle of the width: 0 to width / 2.

    aux_deckboolean
    boolean
    Não

    The vehicle has a second deck (double-decker).

    aux_deck_heightnumber | null · cm
    number | null · cm
    Não

    Second deck height above the floor. Required when aux_deck is true.

    aux_deck_max_weightnumber | null · kg
    number | null · kg
    Não

    Load limit of the second deck. Required when aux_deck is true.

    tractor_weightnumber | null · kg
    number | null · kg
    Não

    Semi-trailer axle model: tractor unit mass.

    empty_trailer_weightnumber | null · kg
    number | null · kg
    Não

    Semi-trailer axle model: unladen trailer mass.

    front_axle_to_middle_axlenumber | null · cm
    number | null · cm
    Não

    Semi-trailer axle model: tractor front axle to drive (middle) axle.

    front_axle_to_tractor_cognumber | null · cm
    number | null · cm
    Não

    Semi-trailer axle model: front axle to tractor centre of gravity.

    front_axle_to_kingpinnumber | null · cm
    number | null · cm
    Não

    Semi-trailer axle model: front axle to kingpin (fifth wheel).

    kingpin_to_rear_axlenumber | null · cm
    number | null · cm
    Não

    Semi-trailer axle model: kingpin to trailer rear axle group.

    trailer_cog_to_rear_axlenumber | null · cm
    number | null · cm
    Não

    Semi-trailer axle model: trailer centre of gravity to rear axle group.

    trailer_start_to_kingpinnumber | null · cm
    number | null · cm
    Não

    Semi-trailer axle model: trailer front to kingpin.

    max_middle_axle_weightnumber | null · kg
    number | null · kg
    Não

    Semi-trailer axle model: legal drive (middle) axle limit.

    max_rear_axle_weightnumber | null · kg
    number | null · kg
    Não

    Semi-trailer axle model: legal rear axle group limit.

    blocked_areasRect[]
    Rect[]
    Não

    Floor zones nothing may stand on (wheel arches, damage, reserved space). Each must lie on the vehicle floor.

    created_byUserRef | null
    UserRef | null
    Não

    The member who created it (for API calls: the member who created the key). null when unknown.

    updated_byUserRef | null
    UserRef | null
    Não

    The member who last changed it.

    created_atstring | null
    string | null
    Não

    RFC 3339; null for presets.

  • 400Bad requestinvalid_json
    • invalid_jsonThe body is not valid JSON or a field has the wrong type.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedMissing, malformed or unknown API key.
    • key_revokedThe key was revoked.
    • key_expiredThe key passed its expiry date.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowedThe calling IP is not on the key's allowlist.
    • subscription_inactiveThe organization has no active subscription that includes the API.
    • account_inactiveThe organization is suspended, or has no owner whose account is active.
    • scope_missingThe key lacks a scope this endpoint needs.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 413Payload too largepayload_too_large
    • payload_too_largeThe request body exceeds 10 MB.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 422Unprocessable entityvalidation_failed
    • validation_failedThe request is well-formed JSON but describes an invalid job. details[] lists every problem.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 429Too many requestsrate_limited
    • rate_limitedToo many requests in the current minute, hour or day (per key or per organization), or more than 60 failed authentications per minute from your IP address.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 500Internal server errorinternal_error
    • internal_errorSomething failed on our side.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro
  • 503Service unavailableapi_disabled
    • api_disabledThe API is temporarily disabled (maintenance) or switched off for the organization.
    NomeTipoObrigatórioDescrição
    errorErrorBodyobrigatório
    ErrorBody
    Sim
    Todos os códigos de erro