Navo24 / TrackingMCP

Переход с Navo24 / TrackingMCP на Cargotime API v2: ключи доступа, запросы и обработка ответов

Руководство описывает переход с Navo24 REST API v1 на Cargotime API v2. В Navo24 POST /v1/containers сразу возвращает постоянный ID записи. При пакетном запуске в Cargotime сначала возвращается временный ID задачи. Постоянный ID отслеживания нужно получить из её результата.

Общий порядок переноса номеров и настройки уведомлений приведён в порядке перехода. Полные схемы Cargotime — в справочнике API.

Аутентификация

Navo24 передаёт токен в заголовке Authorization: Bearer tmcp_…. Базовый адрес Navo24 / TrackingMCP — https://api.trackingmcp.com.

Для перехода на Cargotime:

Создайте ключ в личном кабинете Cargotime.
Замените базовый адрес на https://tracking.cargotime.ru/v2. Например, полный адрес запроса отслеживания — https://tracking.cargotime.ru/v2/tracking.
Передавайте новый ключ в параметре URL api_key каждого запроса, включая пакетные задачи и управление вебхуками. Ключи и токены прежнего сервиса не подходят.

Правила использования ключа и ограничения запросов — в разделе аутентификации.

Отслеживания и идентификаторы

Navo24 / TrackingMCP	Cargotime	Что изменить
`container record (data.id)`	`shipment.id`	Сохраните связь исходного `data.id` с новым ID отслеживания. Один результат по коносаменту или букингу может содержать несколько контейнеров.
`identifier`	`track_number`	Передайте `identifier` как номер для отслеживания. Не используйте вместо него внутренний ID записи Navo24.
`container status`	`shipment_status`	Получайте состояние перевозки из `shipment_status`. Статус подписки `ACTIVE` или `ARCHIVED` проверяйте отдельно.

Соответствие операций

Navo24 / TrackingMCP	Cargotime	Что изменить
`POST /v1/containers`	`POST /v2/tracking/batch` → `GET /v2/tracking/batch`	Отправьте номера, сохраните `task_id` и получите результат задачи. Затем сохраните постоянный `data.results[].data.tracking_metadata.id` для каждого номера.
`GET /v1/containers`	`GET /v2/shipments`	Получайте страницы с помощью `page` и `limit` вместо `cursor`. Для действующих подписок передайте `status=ACTIVE`.
`GET /v1/containers/{id}, GET /v1/containers/lookup/{identifier}`	`GET /v2/shipments`	Получите страницы `/v2/shipments` и найдите запись по сохранённому новому `id`. Отдельного получения записи по ID или номеру нет.
`POST /v1/containers/{id}/recheck`	`GET /v2/tracking?force_update=true`	Передайте номер, тип и SCAC вместе с `force_update=true`. ID записи Navo24 в этом запросе не используется.
`DELETE /v1/containers/{id}`	`DELETE /v2/shipments`	Передайте новые ID в массиве `shipmentIds` в теле запроса. Проверьте условия архивации и удаления в жизненном цикле.
`/v1/webhooks: POST/GET/PATCH/DELETE/test`	`/v2/webhooks`	Создайте новые вебхуки и настройте секрет, проверку подписи и разбор уведомлений по руководству.
`GET /v2/events, summary, demurrage`	Нет прямого аналога	Получайте события из `containers[].events[]`. Отдельно сохраните данные DCSA и расчёты платы за задержку контейнера, которые использует ваша система.

Параметры запроса

Navo24 / TrackingMCP	Cargotime	Что изменить
`identifier`	`tracked_items[].track_number.value`	В теле `POST /v2/tracking/batch` передайте значение `identifier` в `tracked_items[].track_number.value`.
`identifier_type`	`tracked_items[].track_number.type`	Замените `container_id` на `container`, `bill_of_lading` на `bl`, `booking` на `bk`.
`carrier_code`	`tracked_items[].company`	Найдите перевозчика в `GET /v2/companies` и передайте его `scac` в `tracked_items[].company`.
`cursor / limit / archived`	`page / limit / status`	Перейдите на нумерацию страниц через `page`. Для архивных записей используйте `status=ARCHIVED`, для действующих — `status=ACTIVE`.
`bl_number / container_number`	Нет отдельного поля	Выберите один основной номер. Если перевозчик в Navo24 требует одновременно коносамент и контейнер, отдельно проверьте получение данных по выбранному номеру.
`tags / tracked_from`	`note` / нет аналога	Одну подпись до 40 символов сохраните через `PATCH /v2/shipments/{id}` в `note`. Остальные теги храните у себя. Ограничить события датой `tracked_from` нельзя.

Поля ответа

В ответе GET /v2/shipments выберите запись из data.data[]. Пути, начинающиеся с tracked_item, указаны относительно этой записи. Контейнеры находятся в tracked_item.data.data.containers[], события — в events[] каждого контейнера. В ответе GET /v2/tracking данные перевозки находятся сразу в data.

Navo24 / TrackingMCP	Cargotime	Как обработать ответ
`data.items[]`	`data.data[]`	Перебирайте массив `data.data` вместо `data.items`. Продолжайте запрашивать страницы до `data.meta.totalPages`.
`data.items[].id`	`data.data[].id`	Сохраните новые ID вместе с исходными ID Navo24. Для изменения подписи и остановки отслеживания используйте только новые ID.
`identifier / identifier_type`	`tracked_item.track_number / tracked_item.track_number_type`	В выбранной записи берите номер из `tracked_item.track_number`, тип из `tracked_item.track_number_type`.
`status`	`tracked_item.data.data.shipment_status`	Замените обработку значений Navo24 на значения `shipment_status`, например `in_transit` на `IN_TRANSIT`. Верхний `status` записи относится к подписке.
`events / route / current position`	`tracked_item.data.data.containers[].events / route_info`	В выбранной записи получайте события из `tracked_item.data.data.containers[].events[]`. Добавьте `need_route=true` к запросу списка, если нужен `route_info`.

Примеры ответов

В каждой паре подписаны ответы прежнего сервиса и Cargotime. Большие JSON-примеры можно раскрыть отдельно от таблиц сопоставления. Это сокращённые примеры с условными данными. Над каждым JSON указан путь к показанной части ответа. Пути в следующей таблице начинаются от этой части.

Принятие запроса и два вида ID

Navo24 / TrackingMCP — POST /v1/containers

Ответ, сокращённо.

{
    "ok": true,
    "data": {
        "id": "33333333-3333-4333-8333-333333333333",
        "identifier": "MSCU1234567",
        "status": "unknown",
        "carrier_code": "MSCU"
    }
}

Cargotime — POST /v2/tracking/batch

Ответ, сокращённо.

{
    "success": true,
    "status": "OK",
    "data": {
        "task_id": "22222222-2222-4222-8222-222222222222"
    }
}

Как сопоставить

Navo24 / TrackingMCP	Cargotime	Что изменить
`data.id = "33333333-3333-4333-8333-333333333333"`	`data.task_id = "22222222-2222-4222-8222-222222222222"`	Не сохраняйте `task_id` вместо ID отслеживания. Получите результат задачи и возьмите постоянный ID из `data.results[].data.tracking_metadata.id`.
`data.identifier = "MSCU1234567"`	Нет прямого аналога	Сохраните переданный номер у себя до получения результата. Ответ на запуск задачи содержит только её ID.
`data.status = "unknown"`	`status = "OK"`	`OK` подтверждает принятие запроса. Состояние перевозки появится в результате задачи в `shipment_status`.

Ответ на запуск содержит только ID задачи. После PROCESSED получите постоянный ID из data.results[].data.tracking_metadata.id и используйте его для поиска записи в списке и изменения подписи.

Список, тип номера и ожидаемая дата прибытия

Navo24 / TrackingMCP — GET /v1/containers

Ответ, сокращённо.

{
    "ok": true,
    "data": {
        "items": [
            {
                "id": "33333333-3333-4333-8333-333333333333",
                "identifier": "MSCU1234567",
                "identifier_type": "container_id",
                "carrier_code": "MSCU",
                "carrier_name": "MSC",
                "status": "in_transit",
                "eta": "2026-10-12T08:00:00+02:00",
                "eta_is_estimated": true,
                "destination_name": "Rotterdam",
                "tags": ["Order 123"],
                "archived_at": null
            }
        ],
        "has_more": false
    }
}

Cargotime — GET /v2/shipments

Ответ, сокращённо.

{
    "success": true,
    "status": "OK",
    "data": {
        "data": [
            {
                "id": "11111111-1111-4111-8111-111111111111",
                "status": "ACTIVE",
                "note": "Order 123",
                "track_number": "MSCU1234567",
                "tracked_item": {
                    "track_number": "MSCU1234567",
                    "track_number_type": "container",
                    "data": {
                        "success": true,
                        "status": "OK",
                        "data": {
                            "summary": {
                                "company": {
                                    "name": "MSC",
                                    "scacs": ["MEDU", "MSCU"]
                                },
                                "pod": {
                                    "location": 1,
                                    "date": "2026-10-12T08:00:00"
                                }
                            },
                            "shipment_status": "IN_TRANSIT",
                            "locations": [
                                {
                                    "id": 1,
                                    "name": "Rotterdam",
                                    "country": "Netherlands",
                                    "lat": 51.95,
                                    "lng": 4.14
                                }
                            ],
                            "containers": [
                                {
                                    "number": "MSCU1234567",
                                    "events": [
                                        {
                                            "location": 1,
                                            "status": "Vessel arrival",
                                            "status_code": "VAD",
                                            "date": "2026-10-12T08:00:00",
                                            "actual": false,
                                            "vessel": "EXAMPLE VESSEL",
                                            "voyage": "126E"
                                        }
                                    ]
                                }
                            ]
                        }
                    }
                }
            }
        ],
        "meta": {
            "currentPage": 1,
            "totalPages": 1,
            "totalItems": 1
        }
    }
}

Как сопоставить

Navo24 / TrackingMCP	Cargotime	Что изменить
`data.items[0].id = "33333333-3333-4333-8333-333333333333"`	`data.data[0].id = "11111111-1111-4111-8111-111111111111"`	Свяжите ID Navo24 с новым `id`. Номера контейнеров при этом остаются прежними.
`data.items[0].identifier_type = "container_id"`	`data.data[0].tracked_item.track_number_type = "container"`	Получайте тип из `tracked_item.track_number_type`. Для контейнера значение — `container`.
`data.items[0].status = "in_transit"`	`data.data[0].tracked_item.data.data.shipment_status = "IN_TRANSIT"`	Получайте состояние из `tracked_item.data.data.shipment_status`. В примере оно равно `IN_TRANSIT`.
`data.items[0].eta = "2026-10-12T08:00:00+02:00"`	`data.data[0].tracked_item.data.data.summary.pod.date = "2026-10-12T08:00:00"`	Используйте `summary.pod.date` для даты прибытия в порт выгрузки. Не подставляйте её вместо даты доставки до конечного адреса.
`data.items[0].eta_is_estimated = true`	`data.data[0].tracked_item.data.data.containers[0].events[0].actual = false`	Для события с прогнозной датой проверяйте `actual=false`. Значение `eta_is_estimated=true` не означает, что прибытие уже произошло.
`data.items[0].tags = ["Order 123"]`	`data.data[0].note = "Order 123"`	Перенесите один нужный тег в `note`, если он укладывается в 40 символов. Остальные теги храните в своей системе.
`data.has_more = false`	`data.meta.totalPages = 1`	Вместо `has_more` сравнивайте текущую страницу с `data.meta.totalPages` и увеличивайте `page`.

Даты показывают форматы полей. При переносе учитывайте смещение и часовой пояс источника: удаление Z или +08:00 не является преобразованием времени.

Событие и местоположение из подробного ответа

Navo24 / TrackingMCP — GET /v1/containers/{id}

Фрагмент: data.

{
    "container_number": "MSCU1234567",
    "events": [
        {
            "event_type": "EQUIPMENT",
            "equipment_event_type_code": "LOAD",
            "event_classifier_code": "ACT",
            "event_date_time": "2026-10-01T12:00:00+08:00",
            "equipment_reference": "MSCU1234567",
            "transport_call": {
                "location": {
                    "locationName": "Singapore",
                    "UNLocationCode": "SGSIN"
                }
            }
        }
    ],
    "vessel_position": {
        "name": "EXAMPLE VESSEL",
        "lat": 1.25,
        "lng": 103.75,
        "position_fix_at": "2026-10-03T08:30:00Z"
    },
    "eta_confidence_pct": 85
}

Cargotime — GET /v2/shipments?need_route=true

Фрагмент: data.data[0].tracked_item.data.data.

{
    "locations": [
        {
            "id": 0,
            "name": "Singapore",
            "country": "Singapore",
            "lat": 1.25,
            "lng": 103.75
        }
    ],
    "containers": [
        {
            "number": "MSCU1234567",
            "events": [
                {
                    "location": 0,
                    "status": "Loaded",
                    "status_code": "CLL",
                    "date": "2026-10-01T12:00:00",
                    "actual": true,
                    "vessel": "EXAMPLE VESSEL",
                    "voyage": "126E"
                }
            ]
        }
    ],
    "route_info": {
        "current_position": [1.25, 103.75],
        "last_updated": "2026-10-03T09:00:00"
    }
}

Как сопоставить

Navo24 / TrackingMCP	Cargotime	Что изменить
`events[0].equipment_reference = "MSCU1234567"`	`containers[0].number = "MSCU1234567"`	Найдите контейнер по `containers[].number` и обрабатывайте события из его `events`.
`events[0].equipment_event_type_code = "LOAD"`	`containers[0].events[0].status_code = "CLL"`	В примере `LOAD` относится к порту отправления и соответствует `CLL`. Для других этапов погрузки проверьте отдельный код.
`events[0].event_classifier_code = "ACT"`	`containers[0].events[0].actual = true`	Замените `ACT` на `actual=true`, `EST` и `PLN` на `actual=false`.
`events[0].transport_call.location`	`locations[0]`	Найдите место по `event.location` в массиве `locations`. Название и UN/LOCODE исходного места можно использовать при проверке соответствия.
`vessel_position`	`route_info.current_position = [1.25,103.75]`	Получайте текущую точку из `route_info.current_position` в порядке `[широта, долгота]`. `last_updated` маршрута не заменяет время измерения AIS.
`eta_confidence_pct = 85`	Нет прямого аналога	Поля с процентом достоверности прогноза нет. Не вычисляйте его из плановой даты или статуса перевозки.

Что сохранить отдельно

После пакетного запуска получите результат задачи со статусом PROCESSED и сохраните постоянные ID из data.results[].data.tracking_metadata.id. Примеры относятся к REST API Navo24. Режим совместимости с SeaRates и интерфейс DCSA имеют другие форматы, поэтому их обработчики нужно проверять отдельно.

Navo24 / TrackingMCP

АутентификацияСкопировать ссылку на раздел

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

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

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

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

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

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

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

Примеры JSON

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

Примеры JSON

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

Аутентификация

Отслеживания и идентификаторы

Соответствие операций

Параметры запроса

Поля ответа

Примеры ответов

Принятие запроса и два вида ID

Список, тип номера и ожидаемая дата прибытия

Событие и местоположение из подробного ответа

Что сохранить отдельно