Bỏ qua đến nội dung
CargoDuo logoCargoDuo
Bảng giá
Tài liệu cho nhà phát triểnTham chiếu APIDự án

Tạo dự án

Tạo một dự án mở được trong ứng dụng: tên, và tùy chọn thêm xe (xe đã lưu, chỉ định bằng vehicle_id), kiện hàng và nhóm theo cấu trúc của /v1/pack cùng các tùy chọn được lưu.

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

Lập sơ đồ xếp hàng cho dự án bằng POST /v1/projects/{id}/pack. 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ả
namestringbắt buộc
string
Có
≤ 255 chars
vehiclesProjectVehicle[]
ProjectVehicle[]
Không

Các slot xe.

itemsItem[]
Item[]
Không

Kiện hàng (tối đa 500 định nghĩa).

groupsGroup[]
Group[]
Không

Các nhóm, kèm thứ tự xếp hàng.

optionsProjectOptions
ProjectOptions
Không

Các tùy chọn xếp hàng mà dự án lưu.

Yêu cầu mẫu

curl -X POST "https://runner.cargoduo.com/v1/projects" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order 1042",
    "vehicles": [
      {
        "vehicle_id": "standard-trailer-13-6m"
      }
    ],
    "items": [
      {
        "template_id": "tpl_42",
        "quantity": 18
      },
      {
        "template_id": "tpl_43",
        "quantity": 40
      }
    ]
  }'

Phản hồi mẫu

201 · Project
{
  "id": "prj_3051",
  "object": "project",
  "name": "Order 1042",
  "status": "draft",
  "item_count": 58,
  "vehicle_count": 1,
  "app_url": "https://app.cargoduo.com/projects/3051",
  "created_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "updated_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "created_at": "2026-10-19T09:10:03Z",
  "updated_at": "2026-10-19T09:10:03Z",
  "options": {
    "packing_mode": "auto",
    "group_routing": "none",
    "allow_overweight": false
  },
  "vehicles": [
    {
      "id": "pv_5120",
      "vehicle_id": "standard-trailer-13-6m",
      "name": "Standard Trailer (13.6m)",
      "type": "trailer",
      "quantity": 1,
      "length": 1362,
      "width": 248,
      "height": 270,
      "max_weight": 24000
    }
  ],
  "items": [
    {
      "id": "item_88410",
      "label": "Euro pallet",
      "shape": "box",
      "length": 120,
      "width": 80,
      "height": 140,
      "weight": 450,
      "quantity": 18,
      "stackable": false,
      "rotation": "all",
      "color": "#3b82f6"
    },
    {
      "id": "item_88411",
      "label": "Carton A",
      "shape": "box",
      "length": 60,
      "width": 40,
      "height": 40,
      "weight": 12,
      "quantity": 40,
      "stackable": true,
      "rotation": "upright",
      "color": "#f59e0b"
    }
  ],
  "groups": [],
  "plan": null
}

Phản hồi

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

    ID dự án (prj_…).

    objectstring
    string
    Không
    project
    namestring
    string
    Không
    statusstring
    string
    Không

    draft = chưa từng xếp hoặc dữ liệu đầu vào đã bị thay; calculated = có sơ đồ hiện tại; stale = một cài đặt đã thay đổi sau khi lập sơ đồ.

    draftcalculatedstaleerror
    item_countinteger
    integer
    Không

    Số kiện (tổng số lượng).

    vehicle_countinteger
    integer
    Không

    Số xe (tổng số lượng).

    app_urlstring
    string
    Không

    Mở dự án trong trình chỉnh sửa 3D của ứng dụng.

    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
    string
    Không

    RFC 3339.

    updated_atstring
    string
    Không

    RFC 3339.

    optionsProjectOptions
    ProjectOptions
    Không

    Các tùy chọn xếp hàng mà dự án lưu.

    vehiclesProjectVehicle[]
    ProjectVehicle[]
    Không
    itemsItem[]
    Item[]
    Không

    Hàng hóa theo cấu trúc Item của /v1/pack; ID có dạng item_….

    groupsGroup[]
    Group[]
    Không
    planProjectPlan | null
    ProjectPlan | null
    Không

    Sơ đồ hiện tại; null khi dự án chưa có sơ đồ.

  • 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
  • 403Forbiddenplan_limit_reachedip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • plan_limit_reachedGói của tổ chức không cho phép thêm dự án hoặc kiện hàng.
    • 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