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

Tạo tác vụ xếp hàng

Kiểm tra yêu cầu, tạm giữ mức giá tối đa từ credit của bạn và đưa tác vụ vào hàng đợi.

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

Trả về 202 kèm tác vụ; gọi GET /v1/jobs/{id} định kỳ, hoặc truyền ?wait= để giữ phản hồi đến khi tác vụ kết thúc. Yêu cầu không hợp lệ (422) được miễn phí và không tạo tác vụ.

Xác thực

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

Tham số truy vấn

TênKiểuBắt buộcMô tả
waitinteger
integer
Không

Số giây giữ phản hồi để chờ tác vụ hoàn tất. Xong kịp: 200, kèm kết quả trong phản hồi. Nếu không: 202.

Mặc định 00–60

Tham số header

TênKiểuBắt buộcMô tả
Idempotency-Keystring
string
Không

Chuỗi duy nhất bất kỳ, chẳng hạn UUID hoặc mã đơn hàng của bạn. Cùng một khóa trong vòng 24 giờ sẽ trả về tác vụ ban đầu thay vì tạo và tính phí một tác vụ mới.

≤ 128 chars

Tham số body

application/json
TênKiểuBắt buộcMô tả
referencestring
string
Không

Mã tham chiếu riêng của bạn (số đơn hàng, mã lô hàng…). Được trả lại trên tác vụ.

≤ 128 chars
vehiclesVehicle[]bắt buộc
Vehicle[]
Có

Định nghĩa xe. Mỗi định nghĩa có thể có quantity > 1. Ít nhất một.

itemsItem[]bắt buộc
Item[]
Có

Định nghĩa kiện hàng. Mỗi định nghĩa có thể có quantity > 1. Ít nhất một.

groupsGroup[]
Group[]
Không

Nhóm (không bắt buộc): khách hàng, điểm dừng, đơn hàng. Phải khai báo mọi nhóm mà kiện hàng tham chiếu khi options.group_routing khác "none"; nếu không, nhóm được tạo từ tên nhóm của các kiện hàng theo thứ tự xuất hiện.

optionsOptions
Options
Không

Tùy chọn xếp hàng. Mọi trường đều không bắt buộc.

Yêu cầu mẫu

curl -X POST "https://runner.cargoduo.com/v1/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042",
    "vehicles": [
      {
        "id": "trailer",
        "type": "trailer",
        "name": "13.6 m trailer",
        "length": 1360,
        "width": 245,
        "height": 270,
        "max_weight": 24000
      }
    ],
    "items": [
      {
        "id": "pallet-eu",
        "label": "Euro pallet",
        "length": 120,
        "width": 80,
        "height": 140,
        "weight": 450,
        "quantity": 18,
        "stackable": false
      },
      {
        "id": "carton-a",
        "label": "Carton A",
        "length": 60,
        "width": 40,
        "height": 40,
        "weight": 12,
        "quantity": 40,
        "rotation": "upright"
      }
    ],
    "options": {
      "packing_mode": "auto"
    }
  }'

Phản hồi mẫu

202 Accepted · Job
{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "created_at": "2026-10-19T09:12:03Z",
  "started_at": null,
  "finished_at": null,
  "progress": {
    "stage": "queued",
    "vehicles_done": 0,
    "placed_items": 0
  },
  "summary": {
    "items_requested": 58,
    "items_placed": 0,
    "items_unplaced": 0,
    "vehicles_used": 0,
    "total_weight": 0,
    "volume_utilization": 0,
    "queue_ms": 0,
    "compute_ms": 0
  },
  "cost": {
    "credits": 0,
    "reserved_credits": 1.11,
    "rate_card_version": 1,
    "breakdown": {
      "base": 0,
      "vehicles": 0,
      "compute": 0,
      "large_load": 0
    }
  },
  "error": null,
  "warnings": [],
  "result_url": "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f/result",
  "pdf_url": "",
  "expires_at": "2026-11-02T09:12:03Z"
}

Phản hồi

  • 200OKTác vụ xong trong thời gian ?wait, kết quả nằm trong phản hồi. Cũng là phản hồi khi phát lại (idempotent) một tác vụ đã kết thúc.
    TênKiểuBắt buộcMô tả
    idstringbắt buộc
    string
    Có

    ID tác vụ (job_…).

    objectstringbắt buộc
    string
    Có

    Luôn là job.

    job
    statusstringbắt buộc
    string
    Có

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Không

    Mã tham chiếu của bạn từ yêu cầu.

    sourcestring
    string
    Không

    Nơi tạo tác vụ.

    apiplayground
    project_idstring
    string
    Không

    Dự án (prj_…) mà tác vụ POST /v1/projects/{id}/pack lưu sơ đồ vào. Không có ở các tác vụ khác.

    created_atstringbắt buộc
    string
    Có

    Mốc thời gian RFC 3339.

    started_atstring | null
    string | null
    Không

    Thời điểm bắt đầu tính toán (RFC 3339) hoặc null.

    finished_atstring | null
    string | null
    Không

    Thời điểm tác vụ kết thúc (RFC 3339) hoặc null.

    progressJobProgress
    JobProgress
    Không

    Tiến độ trực tiếp khi tác vụ đang chờ/đang chạy.

    summaryJobSummary
    JobSummary
    Không

    Số liệu và thời gian.

    costJobCost
    JobCost
    Không

    Credit đã bị trừ (chốt khi tác vụ kết thúc) và khoản tạm giữ trong lúc tác vụ chạy.

    errorJobError | null
    JobError | null
    Không

    Lý do tác vụ thất bại hoặc bị hủy; nếu không thì là null.

    warningsWarning[]
    Warning[]
    Không

    Ghi chú về yêu cầu, không chặn tác vụ (cũng được lặp lại trong kết quả).

    result_urlstring
    string
    Không

    Gọi GET tới URL này để lấy toàn bộ kết quả khi status là succeeded.

    pdf_urlstring
    string
    Không

    Liên kết mở trên trình duyệt để tạo PDF sơ đồ xếp hàng (góc nhìn 3D + các bước xếp hàng). Có hiệu lực đến expires_at. Rỗng sau khi hết hạn.

    expires_atstring
    string
    Không

    Thời điểm nội dung yêu cầu/kết quả và liên kết PDF bị xóa (RFC 3339). Siêu dữ liệu và khoản phí của tác vụ vẫn được giữ.

    resultResult
    Result
    Không

    Toàn bộ kết quả, chỉ được đưa vào khi được yêu cầu (?include=result) hoặc khi POST /v1/pack?wait= xong kịp thời gian.

  • 202AcceptedĐã nhận tác vụ (đang chờ hoặc đang chạy).
    TênKiểuBắt buộcMô tả
    idstringbắt buộc
    string
    Có

    ID tác vụ (job_…).

    objectstringbắt buộc
    string
    Có

    Luôn là job.

    job
    statusstringbắt buộc
    string
    Có

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Không

    Mã tham chiếu của bạn từ yêu cầu.

    sourcestring
    string
    Không

    Nơi tạo tác vụ.

    apiplayground
    project_idstring
    string
    Không

    Dự án (prj_…) mà tác vụ POST /v1/projects/{id}/pack lưu sơ đồ vào. Không có ở các tác vụ khác.

    created_atstringbắt buộc
    string
    Có

    Mốc thời gian RFC 3339.

    started_atstring | null
    string | null
    Không

    Thời điểm bắt đầu tính toán (RFC 3339) hoặc null.

    finished_atstring | null
    string | null
    Không

    Thời điểm tác vụ kết thúc (RFC 3339) hoặc null.

    progressJobProgress
    JobProgress
    Không

    Tiến độ trực tiếp khi tác vụ đang chờ/đang chạy.

    summaryJobSummary
    JobSummary
    Không

    Số liệu và thời gian.

    costJobCost
    JobCost
    Không

    Credit đã bị trừ (chốt khi tác vụ kết thúc) và khoản tạm giữ trong lúc tác vụ chạy.

    errorJobError | null
    JobError | null
    Không

    Lý do tác vụ thất bại hoặc bị hủy; nếu không thì là null.

    warningsWarning[]
    Warning[]
    Không

    Ghi chú về yêu cầu, không chặn tác vụ (cũng được lặp lại trong kết quả).

    result_urlstring
    string
    Không

    Gọi GET tới URL này để lấy toàn bộ kết quả khi status là succeeded.

    pdf_urlstring
    string
    Không

    Liên kết mở trên trình duyệt để tạo PDF sơ đồ xếp hàng (góc nhìn 3D + các bước xếp hàng). Có hiệu lực đến expires_at. Rỗng sau khi hết hạn.

    expires_atstring
    string
    Không

    Thời điểm nội dung yêu cầu/kết quả và liên kết PDF bị xóa (RFC 3339). Siêu dữ liệu và khoản phí của tác vụ vẫn được giữ.

    resultResult
    Result
    Không

    Toàn bộ kết quả, chỉ được đưa vào khi được yêu cầu (?include=result) hoặc khi POST /v1/pack?wait= xong kịp thời gian.

  • 400Bad requestinvalid_jsonidempotency_key_invalid
    • invalid_jsonNội dung không phải JSON hợp lệ hoặc có trường sai kiểu.
    • idempotency_key_invalidHeader Idempotency-Key dài hơn 128 ký tự.
    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
  • 402Payment requiredinsufficient_credits
    • insufficient_creditsCredit khả dụng không đủ cho lần chạy rẻ nhất có thể của tác vụ này.
    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 requeststoo_many_jobsrate_limited
    • too_many_jobsTổ chức đã đạt số tác vụ tối đa đang chờ + đang chạy.
    • 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