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

Xếp hàng cho dự án

Xếp xe và kiện hàng của dự án y hệt POST /v1/pack: cùng giá, cùng cơ chế tạm giữ credit, giới hạn, Idempotency-Key, ?wait= và tác vụ.

POSThttps://runner.cargoduo.com/v1/projects/{id}/pack

Khi tác vụ thành công, sơ đồ được lưu vào dự án; sau đó dự án mở trong ứng dụng với sơ đồ này. Nếu dự án thay đổi trong lúc tác vụ chạy, sơ đồ chỉ được giữ trên tác vụ (cảnh báo project_not_saved). ID trong kết quả là ID của dự án: vehicle_id là ID slot xe (pv_…), item_id là ID kiện hàng (item_…).

Xác thực

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

Tham số đường dẫn

TênKiểuBắt buộcMô tả
idstringbắt buộc
string
Có

ID dự án (prj_…).

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 của bạn, được trả lại trên tác vụ. Mặc định là tên dự án.

≤ 128 chars
optionsProjectPackOptions
ProjectPackOptions
Không

Tùy chọn cho lượt chạy. 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/projects/prj_3051/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042"
  }'

Phản hồi mẫu

202 Accepted · Job
{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "project_id": "prj_3051",
  "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
  • 404Not foundproject_not_found
    • project_not_foundTổ chức của bạn không có dự án nào với ID này.
    TênKiểuBắt buộcMô tả
    errorErrorBodybắt buộc
    ErrorBody
    Có
    Tất cả mã lỗi
  • 409Conflictproject_busy
    • project_busyDự án đang được xếp hàng (trong ứng dụng hoặc bởi một tác vụ khác).
    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