Отслеживания
Получите список отслеживаний, измените заметку, архивируйте или удалите запись
Эти запросы позволяют управлять отслеживаниями в вашем аккаунте: получить список, добавить или изменить заметку, архивировать или удалить отслеживание.
GET /v2/shipmentsвозвращает список отслеживаний с пагинацией. Отслеживания текущей страницы находятся вdata.data. Полеdata.metaсодержит номер текущей страницы, размер страницы, общее количество отслеживаний и страниц. Вdata.linksнаходятся ссылки на текущую, первую, последнюю и соседние страницы. Для выбора активных или архивных записей передайтеstatus=ACTIVEилиstatus=ARCHIVED. Параметрlimitзадаёт размер страницы, до 500 записей.PATCH /v2/shipments/{id}добавляет или изменяет заметку длиной до 40 символов. Передайте текст заметки в полеnoteJSON-тела запроса:{ "note": "..." }. Чтобы убрать заметку, передайте пустую строку:{ "note": "" }.DELETE /v2/shipmentsс телом{ "shipmentIds": ["..."] }удаляет или архивирует указанные отслеживания. В ответеdata.deletedсодержит идентификаторы удалённых записей, аdata.archived— архивированных.
Если активное отслеживание создано не более 72 часов назад и shipment_status отличается от IN_TRANSIT (например, DELIVERED, UNKNOWN или STUCK), оно удаляется с возвратом одного отслеживания на баланс. Записи со статусом IN_TRANSIT и активные записи старше 72 часов архивируются без возврата. Архивные записи удаляются без возврата. Условия описаны в операции удаления.
Пример запросов
Сначала получите список и выберите id нужного отслеживания. Замените им aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee. Следующие запросы изменят заметку, а затем удалят или архивируют выбранное отслеживание.
// Получаем список, изменяем заметку и удаляем или архивируем выбранную запись.
// Задаём адрес API и параметры запроса.
const API_BASE = "https://tracking.cargotime.ru/v2";
const shipmentId = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
// 1. Получаем страницу отслеживаний, чтобы выбрать нужный id.
const list = await fetch(`${API_BASE}/shipments?api_key=YOUR_TOKEN&page=1&limit=50&status=ACTIVE`, {
headers: { Accept: "application/json" },
});
if (!list.ok) throw new Error(`HTTP ${list.status}`);
const listBody = await list.json();
if (listBody.status !== "OK") throw new Error(listBody.status_description ?? listBody.status);
console.log(listBody.data.data?.map((row) => ({ id: row.id, note: row.note, track_number: row.track_number })));
// 2. Добавляем или изменяем заметку выбранного отслеживания.
const note = await fetch(`${API_BASE}/shipments/${shipmentId}?api_key=YOUR_TOKEN`, {
method: "PATCH",
headers: { Accept: "application/json", "Content-Type": "application/json" },
body: JSON.stringify({ note: "Order 4521" }),
});
if (!note.ok) throw new Error(`HTTP ${note.status}`);
const noteBody = await note.json();
if (noteBody.status !== "OK") throw new Error(noteBody.status_description ?? noteBody.status);
// 3. Удаляем или архивируем эту запись по правилам API.
const removed = await fetch(`${API_BASE}/shipments?api_key=YOUR_TOKEN`, {
method: "DELETE",
headers: { Accept: "application/json", "Content-Type": "application/json" },
body: JSON.stringify({ shipmentIds: [shipmentId] }),
});
if (!removed.ok) throw new Error(`HTTP ${removed.status}`);
const removedBody = await removed.json();
if (removedBody.status !== "OK") throw new Error(removedBody.status_description ?? removedBody.status);
console.log(removedBody.data.deleted, removedBody.data.archived);Подробнее об обработке HTTP-статусов и результатов API — в разделе «Обработка ошибок».
Обновлено