Пакетное отслеживание
Создайте задачу для нескольких номеров и получите результаты её выполнения
Пакетное отслеживание позволяет отправить несколько номеров одним запросом, а затем получить результаты по всем этим номерам отдельным запросом. Передайте от 1 до 500 номеров в POST /v2/tracking/batch. API вернёт task_id, не дожидаясь результатов отслеживания. Используйте этот идентификатор, чтобы получить результаты отдельным запросом.
Через некоторое время вызовите GET /v2/tracking/batch?task_id=... с тем же API-ключом. Поле data.status показывает состояние задачи:
| Статус | Значение |
|---|---|
CREATED | Задача создана и ожидает обработки. |
HANDLING | Номера обрабатываются. Повторите запрос результатов позже. |
PROCESSED | Задача завершена. Результаты находятся в data.results. |
После перехода в PROCESSED задача завершена. Дальнейшие запросы её состояния можно прекратить. Для последующих изменений перевозки используйте запросы на отслеживание или вебхуки. Результаты хранятся в кэше до 6 часов. Сохраните их после завершения задачи.
У каждого номера свой результат: OK, INFO_NOT_FOUND, LINE_IS_UNDER_MAINTENANCE, LINE_NO_RESPONSE или UNEXPECTED_ERROR. Отсутствие данных или ошибка по одному номеру не отменяет обработку остальных.
company=AUTO доступно только для type=container. Для коносамента или букинга укажите SCAC-код перевозчика из списка компаний.
Пример запроса
Пример создаёт задачу для двух номеров, запрашивает её состояние с интервалом и выводит результат каждого номера. Число повторов ограничено, чтобы программа не ожидала завершения бесконечно.
// Создаём задачу, дожидаемся завершения и выводим результат каждого номера.
// Задаём адрес API и параметры запроса.
const API_BASE = "https://tracking.cargotime.ru/v2";
// 1. Отправляем номера и получаем task_id.
const created = await fetch(`${API_BASE}/tracking/batch?api_key=YOUR_TOKEN`, {
method: "POST",
headers: { Accept: "application/json", "Content-Type": "application/json" },
body: JSON.stringify({
tracked_items: [
{ company: "AUTO", track_number: { value: "MSDU8368827", type: "container" } },
{ company: "AUTO", track_number: { value: "CSNU6184414", type: "container" } },
],
}),
});
if (!created.ok) throw new Error(`HTTP ${created.status}`);
const createdBody = await created.json();
if (createdBody.status !== "OK") throw new Error(createdBody.status_description ?? createdBody.status);
let task;
// 2. Повторяем запрос состояния с паузой, пока задача не завершится.
for (let attempt = 0; attempt < 40; attempt += 1) {
const res = await fetch(`${API_BASE}/tracking/batch?api_key=YOUR_TOKEN&task_id=${createdBody.data.task_id}`, {
headers: { Accept: "application/json" },
});
// Проверяем HTTP-ответ перед чтением результата.
if (!res.ok) throw new Error(`HTTP ${res.status}`);
// Читаем JSON; success и status уточняют результат запроса.
const body = await res.json();
if (body.status !== "OK") throw new Error(body.status_description ?? body.status);
task = body.data;
if (task.status === "PROCESSED") break;
await new Promise((resolve) => setTimeout(resolve, 3000));
}
if (task.status !== "PROCESSED") throw new Error(`Task ${createdBody.data.task_id} is still ${task.status}`);
for (const item of task.results ?? []) {
const track = item.request?.track_number;
console.log(track?.value, item.status, item.status === "OK" ? item.data?.shipment_status : item.status_description);
}Подробнее об обработке HTTP-статусов и результатов API — в разделе «Обработка ошибок».
Обновлено