Saltar al contenido
Documentación para desarrolladoresReferencia de la APIVehículos

Crear un vehículo

Guarda un vehículo en la flota de tu organización (también aparece en la aplicación).

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

Mismos campos y reglas de acceso que un vehículo de /v1/pack; se valida con los límites de tamaño y carga útil que la aplicación aplica a su tipo. Gratis: no se cobran créditos.

Autenticación

Clave de API Bearer con el permisoresources:writeMás información

Parámetros del cuerpo

application/json
NombreTipoObligatorioDescripción
typestringobligatorio
string
Sí

Tipo de vehículo. Solo se aceptan los tipos indicados en GET /v1/limits (allowed_vehicle_types).

trucktrailerflatbedcontainerpalletaircraftship
namestringobligatorio
string
Sí

Nombre visible.

≤ 255 chars
lengthnumber · cmobligatorio
number · cm
Sí

Largo interior del espacio de carga, a lo largo de x (desde la pared frontal hacia la puerta).

widthnumber · cmobligatorio
number · cm
Sí

Ancho interior del espacio de carga, a lo largo de z.

heightnumber · cmobligatorio
number · cm
Sí

Alto interior del espacio de carga, a lo largo de y.

max_weightnumber · kgobligatorio
number · kg
Sí

Carga útil máxima.

floor_load_capacitynumber · kg/m²
number · kg/m²
No

Capacidad de carga del suelo: 0 o más (0 = sin límite).

aux_deckboolean
boolean
No

El vehículo tiene un segundo piso (doble piso).

Predeterminado false
aux_deck_heightnumber · cm
number · cm
No

Altura del segundo piso sobre el suelo. Obligatorio cuando aux_deck es true.

aux_deck_max_weightnumber · kg
number · kg
No

Límite de carga del segundo piso. Obligatorio cuando aux_deck es true.

blocked_areasRect[]
Rect[]
No

Zonas del suelo en las que no se puede colocar nada (pasos de rueda, daños, espacio reservado). Cada una debe estar dentro del suelo del vehículo.

≤ 32 items
axle_positionsRequiere accesonumber[] · cm
number[] · cm
No

Posiciones de los ejes (puntos de apoyo) medidas desde la parte delantera de la zona de carga; negativo = por delante de ella. Mismo número de elementos que axle_max_loads. Cada una entre −300 (un eje por delante de la zona de carga, p. ej., el eje delantero de un camión rígido, bajo la cabina) y el largo del vehículo.

≤ 10 items
axle_max_loadsRequiere accesonumber[] · kg
number[] · kg
No

Carga máxima por eje, en el orden de axle_positions. Cada valor debe ser mayor que 0 y no superar 100000.

≤ 10 items
cog_range_xRequiere accesonumber · cm
number · cm
No

Desviación permitida del centro de gravedad respecto a la mitad del largo: de 0 a length / 2.

cog_range_yRequiere accesonumber · cm
number · cm
No

Desviación permitida del centro de gravedad respecto a la mitad del ancho: de 0 a width / 2.

tractor_weightRequiere accesonumber · kg
number · kg
No

Modelo de ejes de semirremolque: masa de la tractora.

empty_trailer_weightRequiere accesonumber · kg
number · kg
No

Modelo de ejes de semirremolque: masa en vacío del remolque.

front_axle_to_middle_axleRequiere accesonumber · cm
number · cm
No

Modelo de ejes de semirremolque: del eje delantero de la tractora al eje motriz (central).

front_axle_to_tractor_cogRequiere accesonumber · cm
number · cm
No

Modelo de ejes de semirremolque: del eje delantero al centro de gravedad de la tractora.

front_axle_to_kingpinRequiere accesonumber · cm
number · cm
No

Modelo de ejes de semirremolque: del eje delantero al pivote de enganche (quinta rueda).

kingpin_to_rear_axleRequiere accesonumber · cm
number · cm
No

Modelo de ejes de semirremolque: del pivote de enganche al grupo de ejes traseros del remolque.

trailer_cog_to_rear_axleRequiere accesonumber · cm
number · cm
No

Modelo de ejes de semirremolque: del centro de gravedad del remolque al grupo de ejes traseros.

trailer_start_to_kingpinRequiere accesonumber · cm
number · cm
No

Modelo de ejes de semirremolque: de la parte delantera del remolque al pivote de enganche.

max_middle_axle_weightRequiere accesonumber · kg
number · kg
No

Modelo de ejes de semirremolque: límite legal del eje motriz (central).

max_rear_axle_weightRequiere accesonumber · kg
number · kg
No

Modelo de ejes de semirremolque: límite legal del grupo de ejes traseros.

Ejemplo de solicitud

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
  }'

Ejemplo de respuesta

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

Respuestas

  • 201El vehículo nuevo.
    NombreTipoObligatorioDescripción
    idstring
    string
    No

    ID del vehículo predefinido, o veh_… en tus propios vehículos.

    objectstring
    string
    No
    vehicle
    kindstring
    string
    No

    preset = el catálogo predefinido; custom = los de tu organización.

    presetcustom
    typestring
    string
    No

    Tipo de vehículo. Solo se aceptan los tipos indicados en GET /v1/limits (allowed_vehicle_types).

    trucktrailerflatbedcontainerpalletaircraftship
    namestring
    string
    No

    Nombre visible.

    lengthnumber · cm
    number · cm
    No

    Largo interior del espacio de carga, a lo largo de x (desde la pared frontal hacia la puerta).

    widthnumber · cm
    number · cm
    No

    Ancho interior del espacio de carga, a lo largo de z.

    heightnumber · cm
    number · cm
    No

    Alto interior del espacio de carga, a lo largo de y.

    max_weightnumber · kg
    number · kg
    No

    Carga útil máxima.

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

    Capacidad de carga del suelo: 0 o más (0 = sin límite).

    axle_positionsnumber[] · cm
    number[] · cm
    No

    Posiciones de los ejes (puntos de apoyo) medidas desde la parte delantera de la zona de carga; negativo = por delante de ella. Mismo número de elementos que axle_max_loads. Cada una entre −300 (un eje por delante de la zona de carga, p. ej., el eje delantero de un camión rígido, bajo la cabina) y el largo del vehículo.

    axle_max_loadsnumber[] · kg
    number[] · kg
    No

    Carga máxima por eje, en el orden de axle_positions. Cada valor debe ser mayor que 0 y no superar 100000.

    cog_range_xnumber | null · cm
    number | null · cm
    No

    Desviación permitida del centro de gravedad respecto a la mitad del largo: de 0 a length / 2.

    cog_range_ynumber | null · cm
    number | null · cm
    No

    Desviación permitida del centro de gravedad respecto a la mitad del ancho: de 0 a width / 2.

    aux_deckboolean
    boolean
    No

    El vehículo tiene un segundo piso (doble piso).

    aux_deck_heightnumber | null · cm
    number | null · cm
    No

    Altura del segundo piso sobre el suelo. Obligatorio cuando aux_deck es true.

    aux_deck_max_weightnumber | null · kg
    number | null · kg
    No

    Límite de carga del segundo piso. Obligatorio cuando aux_deck es true.

    tractor_weightnumber | null · kg
    number | null · kg
    No

    Modelo de ejes de semirremolque: masa de la tractora.

    empty_trailer_weightnumber | null · kg
    number | null · kg
    No

    Modelo de ejes de semirremolque: masa en vacío del remolque.

    front_axle_to_middle_axlenumber | null · cm
    number | null · cm
    No

    Modelo de ejes de semirremolque: del eje delantero de la tractora al eje motriz (central).

    front_axle_to_tractor_cognumber | null · cm
    number | null · cm
    No

    Modelo de ejes de semirremolque: del eje delantero al centro de gravedad de la tractora.

    front_axle_to_kingpinnumber | null · cm
    number | null · cm
    No

    Modelo de ejes de semirremolque: del eje delantero al pivote de enganche (quinta rueda).

    kingpin_to_rear_axlenumber | null · cm
    number | null · cm
    No

    Modelo de ejes de semirremolque: del pivote de enganche al grupo de ejes traseros del remolque.

    trailer_cog_to_rear_axlenumber | null · cm
    number | null · cm
    No

    Modelo de ejes de semirremolque: del centro de gravedad del remolque al grupo de ejes traseros.

    trailer_start_to_kingpinnumber | null · cm
    number | null · cm
    No

    Modelo de ejes de semirremolque: de la parte delantera del remolque al pivote de enganche.

    max_middle_axle_weightnumber | null · kg
    number | null · kg
    No

    Modelo de ejes de semirremolque: límite legal del eje motriz (central).

    max_rear_axle_weightnumber | null · kg
    number | null · kg
    No

    Modelo de ejes de semirremolque: límite legal del grupo de ejes traseros.

    blocked_areasRect[]
    Rect[]
    No

    Zonas del suelo en las que no se puede colocar nada (pasos de rueda, daños, espacio reservado). Cada una debe estar dentro del suelo del vehículo.

    created_byUserRef | null
    UserRef | null
    No

    El miembro que lo creó (en las llamadas a la API: el miembro que creó la clave). null si se desconoce.

    updated_byUserRef | null
    UserRef | null
    No

    El último miembro que lo modificó.

    created_atstring | null
    string | null
    No

    RFC 3339; null en los predefinidos.

  • 400Bad requestinvalid_json
    • invalid_jsonEl cuerpo no es JSON válido o un campo tiene un tipo incorrecto.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedClave de API ausente, mal formada o desconocida.
    • key_revokedLa clave se ha revocado.
    • key_expiredLa clave ha superado su fecha de caducidad.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowedLa IP de origen no está en la lista de IP permitidas de la clave.
    • subscription_inactiveLa organización no tiene ninguna suscripción activa que incluya la API.
    • account_inactiveLa organización está suspendida o no tiene ningún propietario con la cuenta activa.
    • scope_missingA la clave le falta un permiso que requiere este endpoint.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 413Payload too largepayload_too_large
    • payload_too_largeEl cuerpo de la solicitud supera los 10 MB.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 422Unprocessable entityvalidation_failed
    • validation_failedLa solicitud es JSON bien formado, pero describe un trabajo no válido. details[] enumera todos los problemas.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 429Too many requestsrate_limited
    • rate_limitedDemasiadas solicitudes en el minuto, la hora o el día en curso (por clave o por organización), o más de 60 autenticaciones fallidas por minuto desde tu dirección IP.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 500Internal server errorinternal_error
    • internal_errorAlgo ha fallado por nuestra parte.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 503Service unavailableapi_disabled
    • api_disabledLa API está desactivada temporalmente (mantenimiento) o deshabilitada para la organización.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error