Xem tác vụ
Trạng thái, tiến độ, tóm tắt và chi phí của một tác vụ.
Gọi định kỳ mỗi 1–2 giây cho đến khi status là succeeded, failed hoặc canceled.
Xác thực
Tham số đường dẫn
idstringbắt buộcID tác vụ (job_…).
Tham số truy vấn
includestringresult đưa sơ đồ xếp hàng vào phản hồi khi tác vụ đã thành công.
resultYêu cầu mẫu
curl -X GET "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f" \
-H "Authorization: Bearer $CARGODUO_API_KEY"const res = await fetch("https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CARGODUO_API_KEY}`,
},
});
const data = await res.json();
console.log(res.status, data);import os
import requests
response = requests.get(
"https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f",
headers={"Authorization": f"Bearer {os.environ['CARGODUO_API_KEY']}"},
)
print(response.status_code, response.json())package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, err := http.NewRequest("GET", "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("CARGODUO_API_KEY"))
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 {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f"))
.header("Authorization", "Bearer " + System.getenv("CARGODUO_API_KEY"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.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 request = new HttpRequestMessage(HttpMethod.Get, "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f");
var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");<?php
$ch = curl_init('https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('CARGODUO_API_KEY'),
],
]);
$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/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("CARGODUO_API_KEY")}"
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": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
"object": "job",
"status": "succeeded",
"reference": "order-1042",
"source": "api",
"created_at": "2026-10-19T09:12:03Z",
"started_at": "2026-10-19T09:12:03Z",
"finished_at": "2026-10-19T09:12:07Z",
"progress": {
"stage": "done",
"vehicles_done": 1,
"placed_items": 58
},
"summary": {
"items_requested": 58,
"items_placed": 58,
"items_unplaced": 0,
"vehicles_used": 1,
"total_weight": 8580,
"volume_utilization": 0.3116,
"queue_ms": 12,
"compute_ms": 4210
},
"cost": {
"credits": 0.28105,
"reserved_credits": 1.11,
"rate_card_version": 1,
"breakdown": {
"base": 0.06,
"vehicles": 0.2,
"compute": 0.02105,
"large_load": 0
}
},
"error": null,
"warnings": [],
"result_url": "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f/result",
"pdf_url": "https://app.cargoduo.com/r/Xq7Lm2Vt9KbR4cN8wZp1Hs6Yd3Fg5Jk0Ta2Ue7Wn4Ci",
"expires_at": "2026-11-02T09:12:03Z"
}Phản hồi
200OKTác vụ.
TênKiểuBắt buộcMô tảidstringbắt buộcstringCóID tác vụ (job_…).
objectstringbắt buộcstringCóLuôn là
job.jobstatusstringbắt buộcstringCóqueued→running→succeeded|failed|canceled.queuedrunningsucceededfailedcanceledreferencestringstringKhôngMã tham chiếu của bạn từ yêu cầu.
sourcestringstringKhôngNơi tạo tác vụ.
apiplaygroundproject_idstringstringKhôngDự á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ộcstringCóMốc thời gian RFC 3339.
started_atstring | nullstring | nullKhôngThời điểm bắt đầu tính toán (RFC 3339) hoặc
null.finished_atstring | nullstring | nullKhôngThời điểm tác vụ kết thúc (RFC 3339) hoặc
null.progressJobProgressJobProgressKhôngTiến độ trực tiếp khi tác vụ đang chờ/đang chạy.
stagestringstringKhôngGiai đoạn hiện tại, chẳng hạn
queued,running,finalizinghoặcdone. Chỉ để tham khảo: hãy dựa vàoJob.statusđể xử lý.vehicles_doneintegerintegerKhôngSố xe đã xếp xong đến hiện tại.
placed_itemsintegerintegerKhôngSố kiện đã xếp đến hiện tại.
summaryJobSummaryJobSummaryKhôngSố liệu và thời gian.
items_requestedintegerintegerKhôngTổng số kiện (tổng số lượng).
items_placedintegerintegerKhôngSố kiện đã xếp.
items_unplacedintegerintegerKhôngSố kiện không xếp được.
vehicles_usedintegerintegerKhôngSố xe chở ít nhất một kiện hàng.
total_weightnumber · kgnumber · kgKhôngTrọng lượng đã xếp.
volume_utilizationnumbernumberKhôngTỷ lệ sử dụng thể tích trung bình của các xe đã dùng, 0–1.
queue_msintegerintegerKhôngThời gian chờ tài nguyên tính toán (không tính phí).
compute_msintegerintegerKhôngThời gian tính toán (có tính phí).
costJobCostJobCostKhôngCredit đã 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.
creditsnumber · creditsnumber · creditsKhôngCredit đã bị trừ (0 cho đến khi tác vụ kết thúc). Tác vụ thất bại không bị tính phí, trừ time_limit_exceeded, được tính phí như tác vụ bị hủy.
reserved_creditsnumber · creditsnumber · creditsKhôngCredit bị tạm giữ khi tác vụ đang chờ/đang chạy (mức giá tối đa). Được giải phóng khi tác vụ kết thúc.
rate_card_versionintegerintegerKhôngBảng giá dùng để tính giá tác vụ.
breakdownCostBreakdownCostBreakdownKhôngGiá chi tiết theo từng khoản.
basenumber · creditsnumber · creditsKhôngPhí mỗi tác vụ.
vehiclesnumber · creditsnumber · creditsKhôngTheo mỗi xe được xếp hàng (không tính với tác vụ bị hủy hoặc time_limit_exceeded).
computenumber · creditsnumber · creditsKhôngTheo giây tính toán, tính theo tỷ lệ đến từng mili giây.
large_loadnumber · creditsnumber · creditsKhôngPhụ phí cho mỗi 100 kiện vượt ngưỡng tải lớn (phần lẻ tính tròn lên 100).
errorJobError | nullJobError | nullKhôngLý do tác vụ thất bại hoặc bị hủy; nếu không thì là
null.codestringstringKhôngMã dành cho máy (xem Lỗi).
messagestringstringKhôngGiải thích bằng tiếng Anh.
warningsWarning[]Warning[]KhôngGhi chú về yêu cầu, không chặn tác vụ (cũng được lặp lại trong kết quả).
codestringstringKhôngMã dành cho máy.
messagestringstringKhôngGiải thích bằng tiếng Anh.
result_urlstringstringKhôngGọi GET tới URL này để lấy toàn bộ kết quả khi
statuslàsucceeded.pdf_urlstringstringKhôngLiê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_atstringstringKhôngThờ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ữ.
resultResultResultKhôngToà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.
job_idstringstringKhôngTác vụ.
vehiclesResultVehicle[]ResultVehicle[]KhôngCác xe đã xếp hàng theo thứ tự xếp (bỏ qua xe trống).
indexintegerintegerKhôngVị trí trong sơ đồ, bắt đầu từ 0.
vehicle_idstringstringKhôngID định nghĩa xe của bạn (với tác vụ của dự án: ID slot, pv_…).
copyintegerintegerKhôngSố thứ tự bản sao của định nghĩa đó, bắt đầu từ 1 (quantity > 1, hoặc được thêm ở chế độ auto).
auto_addedbooleanbooleanKhôngĐược thêm bởi
packing_modeauto, ngoàiquantitybạn đã khai báo.namestringstringKhôngTên xe.
typestringstringKhôngLoại xe.
lengthnumber · cmnumber · cmKhôngChiều dài khoang chở hàng.
widthnumber · cmnumber · cmKhôngChiều rộng khoang chở hàng.
heightnumber · cmnumber · cmKhôngChiều cao khoang chở hàng.
max_weightnumber · kgnumber · kgKhôngGiới hạn tải trọng.
items_placedintegerintegerKhôngSố kiện trong xe này.
total_weightnumber · kgnumber · kgKhôngTrọng lượng hàng trong xe này.
volume_utilizationnumbernumberKhôngThể tích đã dùng / thể tích khoang chở hàng, 0–1.
weight_utilizationnumbernumberKhôngtotal_weight / max_weight, 0–1 (có thể vượt 1 khi bật allow_overweight).
center_of_gravityPointPointKhôngTrọng tâm của hàng hóa (cm).
xnumber · cmnumber · cmKhôngynumber · cmnumber · cmKhôngznumber · cmnumber · cmKhôngplacementsPlacement[]Placement[]KhôngMọi kiện trong xe này.
item_idstringstringKhôngID định nghĩa kiện hàng của bạn (với tác vụ của dự án: ID kiện hàng, item_…).
instanceintegerintegerKhôngSố thứ tự kiện trong định nghĩa kiện hàng đó, bắt đầu từ 1 (duy nhất trong toàn bộ sơ đồ).
labelstringstringKhôngNhãn kiện hàng.
xnumber · cmnumber · cmKhôngVị trí góc nhỏ nhất theo chiều dài.
ynumber · cmnumber · cmKhôngĐộ cao góc nhỏ nhất so với sàn.
znumber · cmnumber · cmKhôngVị trí góc nhỏ nhất theo chiều rộng.
lengthnumber · cmnumber · cmKhôngKích thước theo trục x khi đã đặt.
widthnumber · cmnumber · cmKhôngKích thước theo trục z khi đã đặt.
heightnumber · cmnumber · cmKhôngKích thước theo trục y khi đã đặt.
rotatedbooleanbooleanKhôngĐược đặt theo hướng khác với định nghĩa.
orientationstringstringKhôngCạnh đã định nghĩa nào nằm theo trục x, z và y:
lwh= như định nghĩa,wlh= xoay 90° quanh trục đứng,lhw,hwl,whl,hlw= lật nghiêng.stepintegerintegerKhôngBước xếp hàng trong xe, bắt đầu từ 1 (xếp theo thứ tự tăng dần).
weightnumber · kgnumber · kgKhôngTrọng lượng một kiện.
axle_loadsCần được cấp quyềnAxleLoad[]AxleLoad[]KhôngTải trọng từng trục (chỉ với xe có dữ liệu trục).
namestringstringKhôngAxle 1,Axle 2… theo thứ tự củaaxle_positions.positionnumber · cmnumber · cmKhôngVị trí trục tính từ đầu khoang chở hàng.
loadnumber · kgnumber · kgKhôngTải trọng hàng trên trục.
maxnumber · kgnumber · kgKhôngMức tối đa đã cấu hình (0 = không giới hạn).
okbooleanbooleanKhôngload≤max(luôn làtruenếu không đặt mức tối đa).unplacedUnplacedItem[]UnplacedItem[]KhôngCác kiện không xếp được, kèm lý do.
item_idstringstringKhôngID định nghĩa kiện hàng của bạn.
instanceintegerintegerKhôngSố thứ tự kiện, bắt đầu từ 1.
labelstringstringKhôngNhãn kiện hàng.
reasonstringstringKhôngLý do không xếp được.
warningsWarning[]Warning[]KhôngGhi chú về sơ đồ.
codestringstringKhôngMã dành cho máy.
messagestringstringKhôngGiải thích bằng tiếng Anh.
pdf_urlstringstringKhôngLiên kết mở trên trình duyệt để tạo PDF của sơ đồ.
expires_atstringstringKhôngThời điểm kết quả này bị xóa (RFC 3339).
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.
404Not found
job_not_foundjob_not_foundTổ chức của bạn không có tác vụ nào với ID này.
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.