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

Tạo mẫu hàng

Lưu một kiện hàng thành mẫu hàng (mẫu này cũng hiển thị trong ứng dụng).

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

Các trường và quy tắc kiểm tra giống một kiện hàng trong /v1/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ả
labelstringbắt buộc
string
Có

Nhãn hiển thị.

≤ 255 chars
shapestring
string
Không

Hình dạng kiện hàng. cylinder và drum dùng radius + height thay cho length + width; pallet và drum luôn đứng thẳng.

boxcylinderpalletbagdrumMặc định "box"
lengthnumber · cm
number · cm
Không

Chiều dài. Bắt buộc, trừ khi shape là cylinder hoặc drum.

widthnumber · cm
number · cm
Không

Chiều rộng. Bắt buộc, trừ khi shape là cylinder hoặc drum.

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

Chiều cao (cạnh thẳng đứng khi kiện hàng đứng như định nghĩa).

radiusnumber · cm
number · cm
Không

Bán kính. Bắt buộc khi shape là cylinder hoặc drum.

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

Trọng lượng của MỘT kiện.

stackableboolean
boolean
Không

Có thể đặt kiện hàng khác lên trên kiện này.

Mặc định true
max_stack_weightnumber · kg
number · kg
Không

Trọng lượng tối đa được đè lên một kiện. 0 = không giới hạn.

Mặc định 0
rotationstring
string
Không

all = bất kỳ hướng nào trong sáu hướng; upright = chỉ được xoay quanh trục đứng (giữ mặt trên hướng lên); fixed = không bao giờ xoay.

alluprightfixedMặc định "all"
hazardousboolean
boolean
Không

Hàng nguy hiểm: được đặt thấp và tách khỏi các hàng nguy hiểm khác.

Mặc định false
priorityinteger
integer
Không

Mức ưu tiên xếp hàng. Cao hơn = được xếp trước và được giữ lại khi hết chỗ. 0 = không ưu tiên.

Mặc định 0
colorstring
string
Không

Màu hiển thị dạng #rrggbb (chỉ dùng cho trình xem và PDF).

nesting_heightnumber · cm
number · cm
Không

Phần lồng vào nhau khi các kiện giống nhau xếp chồng (thùng, xô lồng vào nhau).

Mặc định 0

Yêu cầu mẫu

curl -X POST "https://runner.cargoduo.com/v1/templates" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Euro pallet",
    "length": 120,
    "width": 80,
    "height": 140,
    "weight": 450,
    "stackable": false,
    "color": "#3b82f6"
  }'

Phản hồi mẫu

201 · Template
{
  "id": "tpl_42",
  "object": "template",
  "label": "Euro pallet",
  "shape": "box",
  "length": 120,
  "width": 80,
  "height": 140,
  "radius": 0,
  "weight": 450,
  "stackable": false,
  "max_stack_weight": 0,
  "rotation": "all",
  "hazardous": false,
  "priority": 0,
  "color": "#3b82f6",
  "nesting_height": 0,
  "created_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "updated_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "created_at": "2026-09-28T14:05:52Z",
  "updated_at": "2026-09-28T14:05:52Z"
}

Phản hồi

  • 201Mẫu hàng mới.
    TênKiểuBắt buộcMô tả
    idstring
    string
    Không

    ID mẫu hàng (tpl_…).

    objectstring
    string
    Không
    template
    labelstring
    string
    Không

    Nhãn hiển thị.

    shapestring
    string
    Không

    Hình dạng kiện hàng. cylinder và drum dùng radius + height thay cho length + width; pallet và drum luôn đứng thẳng.

    boxcylinderpalletbagdrum
    lengthnumber · cm
    number · cm
    Không

    Chiều dài. Bắt buộc, trừ khi shape là cylinder hoặc drum.

    widthnumber · cm
    number · cm
    Không

    Chiều rộng. Bắt buộc, trừ khi shape là cylinder hoặc drum.

    heightnumber · cm
    number · cm
    Không

    Chiều cao (cạnh thẳng đứng khi kiện hàng đứng như định nghĩa).

    radiusnumber · cm
    number · cm
    Không

    Bán kính. Bắt buộc khi shape là cylinder hoặc drum.

    weightnumber · kg
    number · kg
    Không

    Trọng lượng của MỘT kiện.

    stackableboolean
    boolean
    Không

    Có thể đặt kiện hàng khác lên trên kiện này.

    max_stack_weightnumber · kg
    number · kg
    Không

    Trọng lượng tối đa được đè lên một kiện. 0 = không giới hạn.

    rotationstring
    string
    Không

    all = bất kỳ hướng nào trong sáu hướng; upright = chỉ được xoay quanh trục đứng (giữ mặt trên hướng lên); fixed = không bao giờ xoay.

    alluprightfixed
    hazardousboolean
    boolean
    Không

    Hàng nguy hiểm: được đặt thấp và tách khỏi các hàng nguy hiểm khác.

    priorityinteger
    integer
    Không

    Mức ưu tiên xếp hàng. Cao hơn = được xếp trước và được giữ lại khi hết chỗ. 0 = không ưu tiên.

    colorstring
    string
    Không

    Màu hiển thị dạng #rrggbb (chỉ dùng cho trình xem và PDF).

    nesting_heightnumber · cm
    number · cm
    Không

    Phần lồng vào nhau khi các kiện giống nhau xếp chồng (thùng, xô lồng vào nhau).

    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.

  • 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