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).
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
Tham số body
application/jsonlabelstringbắt buộcNhãn hiển thị.
shapestringHì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 · cmChiều dài. Bắt buộc, trừ khi shape là cylinder hoặc drum.
widthnumber · cmChiều rộng. Bắt buộc, trừ khi shape là cylinder hoặc drum.
heightnumber · cmbắt buộcChiều cao (cạnh thẳng đứng khi kiện hàng đứng như định nghĩa).
radiusnumber · cmBán kính. Bắt buộc khi shape là cylinder hoặc drum.
weightnumber · kgbắt buộcTrọng lượng của MỘT kiện.
stackablebooleanCó thể đặt kiện hàng khác lên trên kiện này.
truemax_stack_weightnumber · kgTrọng lượng tối đa được đè lên một kiện. 0 = không giới hạn.
0rotationstringall = 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"hazardousbooleanHàng nguy hiểm: được đặt thấp và tách khỏi các hàng nguy hiểm khác.
falsepriorityintegerMứ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.
0colorstringMàu hiển thị dạng #rrggbb (chỉ dùng cho trình xem và PDF).
nesting_heightnumber · cmPhầ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).
0Yê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"
}'const res = await fetch("https://runner.cargoduo.com/v1/templates", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CARGODUO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"label": "Euro pallet",
"length": 120,
"width": 80,
"height": 140,
"weight": 450,
"stackable": false,
"color": "#3b82f6"
}),
});
const data = await res.json();
console.log(res.status, data);import os
import requests
response = requests.post(
"https://runner.cargoduo.com/v1/templates",
headers={"Authorization": f"Bearer {os.environ['CARGODUO_API_KEY']}"},
json={
"label": "Euro pallet",
"length": 120,
"width": 80,
"height": 140,
"weight": 450,
"stackable": False,
"color": "#3b82f6",
},
)
print(response.status_code, response.json())package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{
"label": "Euro pallet",
"length": 120,
"width": 80,
"height": 140,
"weight": 450,
"stackable": false,
"color": "#3b82f6"
}`)
req, err := http.NewRequest("POST", "https://runner.cargoduo.com/v1/templates", body)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("CARGODUO_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(out))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String body = """
{
"label": "Euro pallet",
"length": 120,
"width": 80,
"height": 140,
"weight": 450,
"stackable": false,
"color": "#3b82f6"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://runner.cargoduo.com/v1/templates"))
.header("Authorization", "Bearer " + System.getenv("CARGODUO_API_KEY"))
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());
}
}using System.Net.Http.Headers;
using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("CARGODUO_API_KEY"));
var json = """
{
"label": "Euro pallet",
"length": 120,
"width": 80,
"height": 140,
"weight": 450,
"stackable": false,
"color": "#3b82f6"
}
""";
var request = new HttpRequestMessage(HttpMethod.Post, "https://runner.cargoduo.com/v1/templates")
{
Content = new StringContent(json, Encoding.UTF8, "application/json"),
};
var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");<?php
$payload = <<<'JSON'
{
"label": "Euro pallet",
"length": 120,
"width": 80,
"height": 140,
"weight": 450,
"stackable": false,
"color": "#3b82f6"
}
JSON;
$ch = curl_init('https://runner.cargoduo.com/v1/templates');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('CARGODUO_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $payload,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;require "net/http"
require "uri"
uri = URI("https://runner.cargoduo.com/v1/templates")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("CARGODUO_API_KEY")}"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
{
"label": "Euro pallet",
"length": 120,
"width": 80,
"height": 140,
"weight": 450,
"stackable": false,
"color": "#3b82f6"
}
JSON
response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
http.request(request)
end
puts response.code, response.bodyPhản hồi mẫu
{
"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ảidstringstringKhôngID mẫu hàng (tpl_…).
objectstringstringKhôngtemplatelabelstringstringKhôngNhãn hiển thị.
shapestringstringKhôngHình dạng kiện hàng.
cylindervàdrumdùngradius+heightthay cholength+width;palletvàdrumluôn đứng thẳng.boxcylinderpalletbagdrumlengthnumber · cmnumber · cmKhôngChiều dài. Bắt buộc, trừ khi
shapelàcylinderhoặcdrum.widthnumber · cmnumber · cmKhôngChiều rộng. Bắt buộc, trừ khi
shapelàcylinderhoặcdrum.heightnumber · cmnumber · cmKhôngChiều cao (cạnh thẳng đứng khi kiện hàng đứng như định nghĩa).
radiusnumber · cmnumber · cmKhôngBán kính. Bắt buộc khi
shapelàcylinderhoặcdrum.weightnumber · kgnumber · kgKhôngTrọng lượng của MỘT kiện.
stackablebooleanbooleanKhôngCó thể đặt kiện hàng khác lên trên kiện này.
max_stack_weightnumber · kgnumber · kgKhôngTrọng lượng tối đa được đè lên một kiện. 0 = không giới hạn.
rotationstringstringKhôngall= 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.alluprightfixedhazardousbooleanbooleanKhôngHàng nguy hiểm: được đặt thấp và tách khỏi các hàng nguy hiểm khác.
priorityintegerintegerKhôngMứ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.
colorstringstringKhôngMàu hiển thị dạng #rrggbb (chỉ dùng cho trình xem và PDF).
nesting_heightnumber · cmnumber · cmKhôngPhầ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 | nullUserRef | nullKhôngThành viên đã tạo (với lệnh gọi API: thành viên đã tạo khóa).
nullnếu không xác định.idstringstringKhôngID thành viên (usr_…). Lọc danh sách bằng ?created_by=.
namestringstringKhôngupdated_byUserRef | nullUserRef | nullKhôngThành viên thay đổi gần nhất.
idstringstringKhôngID thành viên (usr_…). Lọc danh sách bằng ?created_by=.
namestringstringKhôngcreated_atstringstringKhôngRFC 3339.
updated_atstringstringKhôngRFC 3339.
400Bad request
invalid_jsoninvalid_jsonNội dung không phải JSON hợp lệ hoặc có trường sai kiểu.
Tất cả mã lỗiTênKiểuBắt buộcMô tảerrorErrorBodybắt buộcErrorBodyCócodestringbắt buộcstringCóMã dành cho máy (snake_case). Hãy dựa vào mã này để xử lý lỗi, không bao giờ dựa vào
message.messagestringbắt buộcstringCóGiải thích bằng tiếng Anh.
request_idstringbắt buộcstringCóGiống header X-Request-Id. Cung cấp mã này khi liên hệ bộ phận hỗ trợ.
detailsErrorDetail[]ErrorDetail[]KhôngLỗi theo từng trường (
validation_failed).pathstringstringKhôngĐường dẫn JSON của trường bị lỗi, ví dụ items[3].length.
codestringstringKhôngrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringKhôngGiải thích bằng tiếng Anh.
401Unauthorized
unauthorizedkey_revokedkey_expiredunauthorizedThiế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ất cả mã lỗiTênKiểuBắt buộcMô tảerrorErrorBodybắt buộcErrorBodyCócodestringbắt buộcstringCóMã dành cho máy (snake_case). Hãy dựa vào mã này để xử lý lỗi, không bao giờ dựa vào
message.messagestringbắt buộcstringCóGiải thích bằng tiếng Anh.
request_idstringbắt buộcstringCóGiống header X-Request-Id. Cung cấp mã này khi liên hệ bộ phận hỗ trợ.
detailsErrorDetail[]ErrorDetail[]KhôngLỗi theo từng trường (
validation_failed).pathstringstringKhôngĐường dẫn JSON của trường bị lỗi, ví dụ items[3].length.
codestringstringKhôngrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringKhôngGiải thích bằng tiếng Anh.
403Forbidden
ip_not_allowedsubscription_inactiveaccount_inactivescope_missingip_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ất cả mã lỗiTênKiểuBắt buộcMô tảerrorErrorBodybắt buộcErrorBodyCócodestringbắt buộcstringCóMã dành cho máy (snake_case). Hãy dựa vào mã này để xử lý lỗi, không bao giờ dựa vào
message.messagestringbắt buộcstringCóGiải thích bằng tiếng Anh.
request_idstringbắt buộcstringCóGiống header X-Request-Id. Cung cấp mã này khi liên hệ bộ phận hỗ trợ.
detailsErrorDetail[]ErrorDetail[]KhôngLỗi theo từng trường (
validation_failed).pathstringstringKhôngĐường dẫn JSON của trường bị lỗi, ví dụ items[3].length.
codestringstringKhôngrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringKhôngGiải thích bằng tiếng Anh.
413Payload too large
payload_too_largepayload_too_largeNội dung yêu cầu vượt quá 10 MB.
Tất cả mã lỗiTênKiểuBắt buộcMô tảerrorErrorBodybắt buộcErrorBodyCócodestringbắt buộcstringCóMã dành cho máy (snake_case). Hãy dựa vào mã này để xử lý lỗi, không bao giờ dựa vào
message.messagestringbắt buộcstringCóGiải thích bằng tiếng Anh.
request_idstringbắt buộcstringCóGiống header X-Request-Id. Cung cấp mã này khi liên hệ bộ phận hỗ trợ.
detailsErrorDetail[]ErrorDetail[]KhôngLỗi theo từng trường (
validation_failed).pathstringstringKhôngĐường dẫn JSON của trường bị lỗi, ví dụ items[3].length.
codestringstringKhôngrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringKhôngGiải thích bằng tiếng Anh.
422Unprocessable entity
validation_failedvalidation_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ất cả mã lỗiTênKiểuBắt buộcMô tảerrorErrorBodybắt buộcErrorBodyCócodestringbắt buộcstringCóMã dành cho máy (snake_case). Hãy dựa vào mã này để xử lý lỗi, không bao giờ dựa vào
message.messagestringbắt buộcstringCóGiải thích bằng tiếng Anh.
request_idstringbắt buộcstringCóGiống header X-Request-Id. Cung cấp mã này khi liên hệ bộ phận hỗ trợ.
detailsErrorDetail[]ErrorDetail[]KhôngLỗi theo từng trường (
validation_failed).pathstringstringKhôngĐường dẫn JSON của trường bị lỗi, ví dụ items[3].length.
codestringstringKhôngrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringKhôngGiải thích bằng tiếng Anh.
429Too many requests
rate_limitedrate_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ất cả mã lỗiTênKiểuBắt buộcMô tảerrorErrorBodybắt buộcErrorBodyCócodestringbắt buộcstringCóMã dành cho máy (snake_case). Hãy dựa vào mã này để xử lý lỗi, không bao giờ dựa vào
message.messagestringbắt buộcstringCóGiải thích bằng tiếng Anh.
request_idstringbắt buộcstringCóGiống header X-Request-Id. Cung cấp mã này khi liên hệ bộ phận hỗ trợ.
detailsErrorDetail[]ErrorDetail[]KhôngLỗi theo từng trường (
validation_failed).pathstringstringKhôngĐường dẫn JSON của trường bị lỗi, ví dụ items[3].length.
codestringstringKhôngrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringKhôngGiải thích bằng tiếng Anh.
500Internal server error
internal_errorinternal_errorĐã xảy ra lỗi ở phía chúng tôi.
Tất cả mã lỗiTênKiểuBắt buộcMô tảerrorErrorBodybắt buộcErrorBodyCócodestringbắt buộcstringCóMã dành cho máy (snake_case). Hãy dựa vào mã này để xử lý lỗi, không bao giờ dựa vào
message.messagestringbắt buộcstringCóGiải thích bằng tiếng Anh.
request_idstringbắt buộcstringCóGiống header X-Request-Id. Cung cấp mã này khi liên hệ bộ phận hỗ trợ.
detailsErrorDetail[]ErrorDetail[]KhôngLỗi theo từng trường (
validation_failed).pathstringstringKhôngĐường dẫn JSON của trường bị lỗi, ví dụ items[3].length.
codestringstringKhôngrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringKhôngGiải thích bằng tiếng Anh.
503Service unavailable
api_disabledapi_disabledAPI tạm thời bị tắt (bảo trì) hoặc đã bị tắt cho tổ chức.
Tất cả mã lỗiTênKiểuBắt buộcMô tảerrorErrorBodybắt buộcErrorBodyCócodestringbắt buộcstringCóMã dành cho máy (snake_case). Hãy dựa vào mã này để xử lý lỗi, không bao giờ dựa vào
message.messagestringbắt buộcstringCóGiải thích bằng tiếng Anh.
request_idstringbắt buộcstringCóGiống header X-Request-Id. Cung cấp mã này khi liên hệ bộ phận hỗ trợ.
detailsErrorDetail[]ErrorDetail[]KhôngLỗi theo từng trường (
validation_failed).pathstringstringKhôngĐường dẫn JSON của trường bị lỗi, ví dụ items[3].length.
codestringstringKhôngrequired,invalid_value,out_of_range,duplicate_id,unknown_vehicle,unknown_template,type_not_allowed,unknown_group,does_not_fit,too_many_items,too_many_vehicles,unknown_field,invalid_json.messagestringstringKhôngGiải thích bằng tiếng Anh.