Bỏ qua đến nội dung
CargoDuo logoCargoDuo
Bảng giá

Tạo xe

Lưu một xe vào đội xe của tổ chức (xe này cũng hiển thị trong ứng dụng).

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

Các trường và quy tắc truy cập giống một xe trong /v1/pack, được kiểm tra theo giới hạn kích thước và tải trọng của ứng dụng cho từng loại xe. Miễn phí: không trừ credit.

Xác thực

Khóa API dạng Bearer, phạm vi quyềnresources:writeTìm hiểu thêm

Tham số body

application/json
TênKiểuBắt buộcMô tả
typestringbắt buộc
string
Có

Loại xe. Chỉ chấp nhận các loại được liệt kê trong GET /v1/limits (allowed_vehicle_types).

trucktrailerflatbedcontainerpalletaircraftship
namestringbắt buộc
string
Có

Tên hiển thị.

≤ 255 chars
lengthnumber · cmbắt buộc
number · cm
Có

Chiều dài bên trong khoang chở hàng, theo trục x (từ vách trước về phía cửa).

widthnumber · cmbắt buộc
number · cm
Có

Chiều rộng bên trong khoang chở hàng, theo trục z.

heightnumber · cmbắt buộc
number · cm
Có

Chiều cao bên trong khoang chở hàng, theo trục y.

max_weightnumber · kgbắt buộc
number · kg
Có

Tải trọng tối đa.

floor_load_capacitynumber · kg/m²
number · kg/m²
Không

Tải trọng sàn: từ 0 trở lên (0 = không giới hạn).

aux_deckboolean
boolean
Không

Xe có sàn thứ hai (xe hai tầng).

Mặc định false
aux_deck_heightnumber · cm
number · cm
Không

Độ cao của sàn thứ hai so với sàn xe. Bắt buộc khi aux_deck là true.

aux_deck_max_weightnumber · kg
number · kg
Không

Giới hạn tải của sàn thứ hai. Bắt buộc khi aux_deck là true.

blocked_areasRect[]
Rect[]
Không

Các vùng sàn không được đặt gì lên (hốc bánh xe, chỗ hư hỏng, khoảng trống dành riêng). Mỗi vùng phải nằm trên sàn xe.

≤ 32 items
axle_positionsCần được cấp quyềnnumber[] · cm
number[] · cm
Không

Vị trí các trục (điểm đỡ) tính từ đầu khoang chở hàng; số âm = phía trước khoang. Cùng độ dài với axle_max_loads. Mỗi giá trị nằm trong khoảng từ −300 (trục ở phía trước khoang chở hàng, ví dụ trục trước nằm dưới cabin của xe tải thùng) đến chiều dài xe.

≤ 10 items
axle_max_loadsCần được cấp quyềnnumber[] · kg
number[] · kg
Không

Tải trọng hàng tối đa trên mỗi trục, theo thứ tự của axle_positions. Mỗi giá trị lớn hơn 0 và không vượt quá 100000.

≤ 10 items
cog_range_xCần được cấp quyềnnumber · cm
number · cm
Không

Độ lệch trọng tâm cho phép so với điểm giữa chiều dài: từ 0 đến length / 2.

cog_range_yCần được cấp quyềnnumber · cm
number · cm
Không

Độ lệch trọng tâm cho phép so với điểm giữa chiều rộng: từ 0 đến width / 2.

tractor_weightCần được cấp quyềnnumber · kg
number · kg
Không

Mô hình trục sơ mi rơ moóc: khối lượng đầu kéo.

empty_trailer_weightCần được cấp quyềnnumber · kg
number · kg
Không

Mô hình trục sơ mi rơ moóc: khối lượng rơ moóc không tải.

front_axle_to_middle_axleCần được cấp quyềnnumber · cm
number · cm
Không

Mô hình trục sơ mi rơ moóc: từ trục trước của đầu kéo đến trục dẫn động (trục giữa).

front_axle_to_tractor_cogCần được cấp quyềnnumber · cm
number · cm
Không

Mô hình trục sơ mi rơ moóc: từ trục trước đến trọng tâm đầu kéo.

front_axle_to_kingpinCần được cấp quyềnnumber · cm
number · cm
Không

Mô hình trục sơ mi rơ moóc: từ trục trước đến chốt kéo (mâm kéo).

kingpin_to_rear_axleCần được cấp quyềnnumber · cm
number · cm
Không

Mô hình trục sơ mi rơ moóc: từ chốt kéo đến cụm trục sau của rơ moóc.

trailer_cog_to_rear_axleCần được cấp quyềnnumber · cm
number · cm
Không

Mô hình trục sơ mi rơ moóc: từ trọng tâm rơ moóc đến cụm trục sau.

trailer_start_to_kingpinCần được cấp quyềnnumber · cm
number · cm
Không

Mô hình trục sơ mi rơ moóc: từ đầu rơ moóc đến chốt kéo.

max_middle_axle_weightCần được cấp quyềnnumber · kg
number · kg
Không

Mô hình trục sơ mi rơ moóc: giới hạn pháp lý của trục dẫn động (trục giữa).

max_rear_axle_weightCần được cấp quyềnnumber · kg
number · kg
Không

Mô hình trục sơ mi rơ moóc: giới hạn pháp lý của cụm trục sau.

Yêu cầu mẫu

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

Phản hồi mẫu

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

Phản hồi

  • 201Xe mới.
    TênKiểuBắt buộcMô tả
    idstring
    string
    Không

    ID xe thiết lập sẵn, hoặc veh_… với xe riêng của bạn.

    objectstring
    string
    Không
    vehicle
    kindstring
    string
    Không

    preset = danh mục xe định sẵn; custom = xe của tổ chức bạn.

    presetcustom
    typestring
    string
    Không

    Loại xe. Chỉ chấp nhận các loại được liệt kê trong GET /v1/limits (allowed_vehicle_types).

    trucktrailerflatbedcontainerpalletaircraftship
    namestring
    string
    Không

    Tên hiển thị.

    lengthnumber · cm
    number · cm
    Không

    Chiều dài bên trong khoang chở hàng, theo trục x (từ vách trước về phía cửa).

    widthnumber · cm
    number · cm
    Không

    Chiều rộng bên trong khoang chở hàng, theo trục z.

    heightnumber · cm
    number · cm
    Không

    Chiều cao bên trong khoang chở hàng, theo trục y.

    max_weightnumber · kg
    number · kg
    Không

    Tải trọng tối đa.

    floor_load_capacitynumber | null · kg/m²
    number | null · kg/m²
    Không

    Tải trọng sàn: từ 0 trở lên (0 = không giới hạn).

    axle_positionsnumber[] · cm
    number[] · cm
    Không

    Vị trí các trục (điểm đỡ) tính từ đầu khoang chở hàng; số âm = phía trước khoang. Cùng độ dài với axle_max_loads. Mỗi giá trị nằm trong khoảng từ −300 (trục ở phía trước khoang chở hàng, ví dụ trục trước nằm dưới cabin của xe tải thùng) đến chiều dài xe.

    axle_max_loadsnumber[] · kg
    number[] · kg
    Không

    Tải trọng hàng tối đa trên mỗi trục, theo thứ tự của axle_positions. Mỗi giá trị lớn hơn 0 và không vượt quá 100000.

    cog_range_xnumber | null · cm
    number | null · cm
    Không

    Độ lệch trọng tâm cho phép so với điểm giữa chiều dài: từ 0 đến length / 2.

    cog_range_ynumber | null · cm
    number | null · cm
    Không

    Độ lệch trọng tâm cho phép so với điểm giữa chiều rộng: từ 0 đến width / 2.

    aux_deckboolean
    boolean
    Không

    Xe có sàn thứ hai (xe hai tầng).

    aux_deck_heightnumber | null · cm
    number | null · cm
    Không

    Độ cao của sàn thứ hai so với sàn xe. Bắt buộc khi aux_deck là true.

    aux_deck_max_weightnumber | null · kg
    number | null · kg
    Không

    Giới hạn tải của sàn thứ hai. Bắt buộc khi aux_deck là true.

    tractor_weightnumber | null · kg
    number | null · kg
    Không

    Mô hình trục sơ mi rơ moóc: khối lượng đầu kéo.

    empty_trailer_weightnumber | null · kg
    number | null · kg
    Không

    Mô hình trục sơ mi rơ moóc: khối lượng rơ moóc không tải.

    front_axle_to_middle_axlenumber | null · cm
    number | null · cm
    Không

    Mô hình trục sơ mi rơ moóc: từ trục trước của đầu kéo đến trục dẫn động (trục giữa).

    front_axle_to_tractor_cognumber | null · cm
    number | null · cm
    Không

    Mô hình trục sơ mi rơ moóc: từ trục trước đến trọng tâm đầu kéo.

    front_axle_to_kingpinnumber | null · cm
    number | null · cm
    Không

    Mô hình trục sơ mi rơ moóc: từ trục trước đến chốt kéo (mâm kéo).

    kingpin_to_rear_axlenumber | null · cm
    number | null · cm
    Không

    Mô hình trục sơ mi rơ moóc: từ chốt kéo đến cụm trục sau của rơ moóc.

    trailer_cog_to_rear_axlenumber | null · cm
    number | null · cm
    Không

    Mô hình trục sơ mi rơ moóc: từ trọng tâm rơ moóc đến cụm trục sau.

    trailer_start_to_kingpinnumber | null · cm
    number | null · cm
    Không

    Mô hình trục sơ mi rơ moóc: từ đầu rơ moóc đến chốt kéo.

    max_middle_axle_weightnumber | null · kg
    number | null · kg
    Không

    Mô hình trục sơ mi rơ moóc: giới hạn pháp lý của trục dẫn động (trục giữa).

    max_rear_axle_weightnumber | null · kg
    number | null · kg
    Không

    Mô hình trục sơ mi rơ moóc: giới hạn pháp lý của cụm trục sau.

    blocked_areasRect[]
    Rect[]
    Không

    Các vùng sàn không được đặt gì lên (hốc bánh xe, chỗ hư hỏng, khoảng trống dành riêng). Mỗi vùng phải nằm trên sàn xe.

    created_byUserRef | null
    UserRef | null
    Không

    Thành viên đã tạo (với lệnh gọi API: thành viên đã tạo khóa). null nếu không xác định.

    updated_byUserRef | null
    UserRef | null
    Không

    Thành viên thay đổi gần nhất.

    created_atstring | null
    string | null
    Không

    RFC 3339; null với xe thiết lập sẵn.

  • 400Bad requestinvalid_json
    • invalid_jsonNội dung không phải JSON hợp lệ hoặc có trường sai kiểu.
    TênKiểuBắt buộcMô tả
    errorErrorBodybắt buộc
    ErrorBody
    Có
    Tất cả mã lỗi
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedThiếu khóa API, khóa sai định dạng hoặc không xác định.
    • key_revokedKhóa đã bị thu hồi.
    • key_expiredKhóa đã quá ngày hết hạn.
    TênKiểuBắt buộcMô tả
    errorErrorBodybắt buộc
    ErrorBody
    Có
    Tất cả mã lỗi
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowedIP gọi đến không nằm trong danh sách IP được phép của khóa.
    • subscription_inactiveTổ chức không có gói đăng ký đang hoạt động nào bao gồm API.
    • account_inactiveTổ chức bị tạm ngưng, hoặc không có chủ sở hữu nào có tài khoản đang hoạt động.
    • scope_missingKhóa thiếu phạm vi quyền mà endpoint này yêu cầu.
    TênKiểuBắt buộcMô tả
    errorErrorBodybắt buộc
    ErrorBody
    Có
    Tất cả mã lỗi
  • 413Payload too largepayload_too_large
    • payload_too_largeNội dung yêu cầu vượt quá 10 MB.
    TênKiểuBắt buộcMô tả
    errorErrorBodybắt buộc
    ErrorBody
    Có
    Tất cả mã lỗi
  • 422Unprocessable entityvalidation_failed
    • validation_failedYêu cầu là JSON đúng cú pháp nhưng mô tả một tác vụ không hợp lệ. details[] liệt kê mọi lỗi.
    TênKiểuBắt buộcMô tả
    errorErrorBodybắt buộc
    ErrorBody
    Có
    Tất cả mã lỗi
  • 429Too many requestsrate_limited
    • rate_limitedQuá nhiều yêu cầu trong phút, giờ hoặc ngày hiện tại (theo khóa hoặc theo tổ chức), hoặc có hơn 60 lần xác thực thất bại mỗi phút từ địa chỉ IP của bạn.
    TênKiểuBắt buộcMô tả
    errorErrorBodybắt buộc
    ErrorBody
    Có
    Tất cả mã lỗi
  • 500Internal server errorinternal_error
    • internal_errorĐã xảy ra lỗi ở phía chúng tôi.
    TênKiểuBắt buộcMô tả
    errorErrorBodybắt buộc
    ErrorBody
    Có
    Tất cả mã lỗi
  • 503Service unavailableapi_disabled
    • api_disabledAPI tạm thời bị tắt (bảo trì) hoặc đã bị tắt cho tổ chức.
    TênKiểuBắt buộcMô tả
    errorErrorBodybắt buộc
    ErrorBody
    Có
    Tất cả mã lỗi