Жизненный цикл отслеживания

Выберите подходящий способ получения данных: запрос по одному номеру возвращает результат в ответе, а пакетный запрос создаёт задачу, результаты которой нужно получить отдельно.

Отслеживание одного номераСкопировать ссылку на раздел

GET /v2/tracking работает синхронно для клиента: запрос ожидает результат и возвращает его в том же HTTP-ответе.

• Для номера контейнера можно использовать company=AUTO, чтобы определить перевозчика автоматически.
• Для коносамента или букинга укажите SCAC-код перевозчика из списка компаний.
• Параметр force_update запрашивает обновление данных, а need_route добавляет информацию о маршруте. Подробности — в описании запроса.

Код запроса приведён в примерах.

Пакетное отслеживаниеСкопировать ссылку на раздел

POST /v2/tracking/batch создаёт задачу для отслеживания от 1 до 500 номеров и возвращает task_id. Обработка выполняется асинхронно: API возвращает идентификатор задачи, не дожидаясь результатов отслеживания. Через некоторое время передайте этот идентификатор в GET /v2/tracking/batch, чтобы получить её состояние и результаты.

CREATED означает, что задача ожидает обработки, HANDLING — что она выполняется, а PROCESSED — что она завершена. После завершения дальнейшие запросы состояния задачи можно прекратить. Для получения последующих изменений перевозки используйте запросы на отслеживание или вебхуки.

Данные задачи хранятся в кэше до 6 часов. Сохраните результаты, как только задача завершится. Пошаговый код приведён в примере пакетного отслеживания.

КомпанииСкопировать ссылку на раздел

GET /v2/companies возвращает поддерживаемых перевозчиков, их SCAC-коды и доступные типы отслеживания. В data находится объект: название компании → { scac, cn, bl, bk }.

• Передайте scac в параметре запроса company.
• Флаги cn, bl и bk показывают поддержку контейнеров, коносаментов и букингов соответственно. Выберите тип, для которого флаг равен true.
• На данный момент отдельного статуса работоспособности перевозчика в ответе нет. О временных работах над источником данных сообщает статус LINE_IS_UNDER_MAINTENANCE в результате отслеживания.

Как выбрать перевозчиков по поддерживаемому типу номера, показано в примере запроса списка компаний.

Фактическое и расчётное времяСкопировать ссылку на раздел

После запроса по номеру контейнера, коносамента или букинга API возвращает данные перевозки в data. Массив data.containers содержит контейнеры, а events у каждого контейнера — события перевозки: например, погрузку, прибытие судна или выгрузку.

Поле date содержит дату события, а actual показывает, что она означает:

Если даты указаны у всех событий, API возвращает их от самого нового к самому старому. В этом случае первый элемент с actual: true — последнее произошедшее событие. Если хотя бы у одного события нет даты, API сохраняет порядок, в котором события пришли от перевозчика. Это позволяет не перепутать последовательность событий.

У событий есть тип — поле status_code. Например:

VAT относится к транзитному порту, поэтому не подтверждает прибытие в порт назначения. Пока нет произошедшего события VAD или CDD, дату summary.pod.date следует считать расчётной датой прибытия (ETA). Когда ETA изменяется, API может отправить событие вебхука tracking.eta_update, если вы на него подписаны. Это уведомление об изменении прогноза, а не подтверждение прибытия.

Пример ниже обрабатывает каждый контейнер и возвращает последнее произошедшее событие, ближайшее ожидаемое событие с известной датой и признак прибытия в порт назначения.

function readEvents(data) {
    // В ответе по коносаменту или букингу может быть несколько контейнеров.
    return (data?.containers ?? []).map((container) => {
        const events = container.events ?? [];
        // События идут от новых к старым: выбираем первое произошедшее.
        const lastActual = events.find((event) => event.actual === true) ?? null;
        // Ближайшее ожидаемое событие находится в конце списка ожидаемых дат.
        const expected = events.filter((event) => event.actual === false && event.date);
        const nextExpected = expected.length > 0 ? expected[expected.length - 1] : null;
        const arrived = events.some((event) => event.actual === true && ["VAD", "CDD"].includes(event.status_code));
        return { number: container.number, lastActual, nextExpected, arrived };
    });
}

Управление отслеживаниямиСкопировать ссылку на раздел

GET /v2/shipments возвращает список активных (ACTIVE) и архивных (ARCHIVED) отслеживаний. PATCH /v2/shipments/{id} добавляет или изменяет заметку. DELETE /v2/shipments удаляет или архивирует записи с учётом их возраста и статуса перевозки.

Порядок запросов и условия возврата на баланс описаны в примере управления отслеживаниями.