SeaRates

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

Руководство описывает переход с SeaRates Container Tracking API v3 на Cargotime API v2. Для старых методов /container, /reference и /apiv2 отдельно указаны отличия параметров.

Открытая документация SeaRates сейчас недоступна. Перед переходом уточните используемую версию API и параметры вашей интеграции в личном кабинете или у поддержки SeaRates. Таблицы ниже относятся к версии v3, если не указано иное.

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

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

SeaRates передаёт ключ в параметре URL api_key. Базовый адрес SeaRates — https://tracking.searates.com.

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

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

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

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

SeaRates	Cargotime	Что изменить
`metadata.number + metadata.type`	`request.track_number`	Берите исходный номер и его тип из `metadata`. В новом ответе они находятся в `request.track_number`.
`containers[]`	`data.containers[]`	Обрабатывайте каждый элемент `data.containers[]`. При поиске по коносаменту или букингу ответ может содержать несколько контейнеров.
`metadata.status`	`data.shipment_status`	Получайте состояние перевозки из `data.shipment_status`. Поле `status` на верхнем уровне сообщает результат запроса.

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

SeaRates	Cargotime	Что изменить
`GET /tracking`	`GET /v2/tracking`	Передайте номер, тип и перевозчика. Для нескольких номеров используйте `POST /v2/tracking/batch`.
`GET /info/sealines`	`GET /v2/companies`	Найдите перевозчика в новом справочнике. Используйте его `scac` и проверьте поддержку нужного типа номера в `cn`, `bl` или `bk`.
`GET /route`	`GET /v2/tracking?need_route=true`	Добавьте `need_route=true` к запросу отслеживания. Для сохранённых данных используйте `GET /v2/shipments?need_route=true`.
`GET /history, GET /history?id=…`	Нет прямого аналога	Выгрузите нужные прошлые ответы SeaRates до отключения сервиса. Список отслеживаний содержит текущие данные, а не архив этих ответов.
`GET /container, /reference, /apiv2`	`GET /v2/tracking`	Сначала определите используемую версию SeaRates. Замените числовой `sealine` на SCAC из `GET /v2/companies`.

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

SeaRates	Cargotime	Что изменить
`number`	`value`	Передайте значение `number` в параметре URL `value` без изменения номера.
`type: CT / BL / BK`	`type: container / bl / bk`	Замените `CT` на `container`, `BL` на `bl`, `BK` на `bk`. Передавайте `type` в каждом запросе.
`sealine`	`company`	Передайте SCAC перевозчика в `company`. Проверьте его через `GET /v2/companies`. Значение `AUTO` доступно только для номеров контейнеров.
`route / ais`	`need_route`	Для получения маршрута передайте `need_route=true`. Параметр `ais` удалите из запроса. Отдельного переключателя AIS нет.
`force_update`	`force_update`	Передавайте `force_update=true`, только когда требуется обновить данные у перевозчика. Учитывайте ограничения запросов.

Поля ответа

В этой таблице пути указаны от корня ответа GET /v2/tracking. В списке /v2/shipments данные перевозки находятся внутри каждой записи в tracked_item.data.data. Формат вебхуков описан в отдельном разделе.

SeaRates	Cargotime	Как обработать ответ
`data.metadata.number`	`request.track_number.value`	Получайте запрошенный номер из `request.track_number.value`. Номера контейнеров в результате находятся в `data.containers[].number`.
`data.metadata.sealine`	`data.summary.company.scacs[]`	Обрабатывайте `scacs` как массив строк. Не сравнивайте его с одним кодом как со строкой.
`data.metadata.status`	`data.shipment_status`	Переведите условия обработки на значения `shipment_status`. Прибытие судна, выгрузка контейнера и доставка — разные этапы.
`data.containers[].events[]`	`data.containers[].events[]`	Получайте текст события из `status`, код из `status_code`, дату из `date`, признак фактического события из `actual`. Место события найдите по `location` в `data.locations`.
`data.route`	`data.route_info`	Получайте линию маршрута из `route_info.route[].path`, текущую точку из `route_info.current_position`. Порядок координат — `[широта, долгота]`.
`metadata.api_calls / unique_shipments`	`GET /v2/apikey`	Запрашивайте остаток доступных отслеживаний через `GET /v2/apikey`. Счётчики и остаток SeaRates в новый аккаунт не переносятся.

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

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

Номер, тип отслеживания и состояние перевозки

SeaRates — GET /tracking

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

{
    "status": "success",
    "message": "OK",
    "data": {
        "metadata": {
            "number": "MSCU1234567",
            "type": "CT",
            "sealine": "MSCU",
            "sealine_name": "MSC",
            "status": "IN_TRANSIT"
        },
        "containers": [
            {
                "number": "MSCU1234567",
                "iso_code": "45G1",
                "size_type": "40' High Cube Dry"
            }
        ]
    }
}

Cargotime — GET /v2/tracking

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

{
    "success": true,
    "status": "OK",
    "request": {
        "track_number": {
            "type": "container",
            "value": "MSCU1234567"
        },
        "company": "MSCU"
    },
    "data": {
        "summary": {
            "company": {
                "name": "MSC",
                "scacs": ["MEDU", "MSCU"]
            }
        },
        "shipment_status": "IN_TRANSIT",
        "containers": [
            {
                "number": "MSCU1234567",
                "type": "40' High Cube Dry"
            }
        ],
        "tracking_metadata": {
            "id": "11111111-1111-4111-8111-111111111111",
            "status": "ACTIVE"
        }
    }
}

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

SeaRates	Cargotime	Что изменить
`data.metadata.number = "MSCU1234567"`	`request.track_number.value = "MSCU1234567"`	Номер остаётся `MSCU1234567`. В новом ответе получайте его из `request.track_number.value`.
`data.metadata.type = "CT"`	`request.track_number.type = "container"`	Значению `CT` в SeaRates соответствует `container`. Используйте это значение при формировании запроса.
`data.metadata.sealine = "MSCU"`	`data.summary.company.scacs = ["MEDU","MSCU"]`	Вместо одного кода обрабатывайте массив `scacs`. В примере MSC представлен кодами `MEDU` и `MSCU`.
`data.metadata.status = "IN_TRANSIT"`	`data.shipment_status = "IN_TRANSIT"`	Состояние перевозки здесь — `IN_TRANSIT`. Значение `ACTIVE` в `tracking_metadata.status` означает действующую подписку на отслеживание.
`data.containers[0].size_type = "40' High Cube Dry"`	`data.containers[0].type = "40' High Cube Dry"`	Получайте описание размера и типа контейнера из `containers[].type` вместо `size_type`.
`data.containers[0].iso_code = "45G1"`	Нет прямого аналога	Отдельного поля с ISO-кодом нет. Если код нужен вашей системе, сохраните исходное значение отдельно.

События, места и судно

SeaRates — GET /tracking

Фрагмент: data.

{
    "locations": [
        {
            "id": 10,
            "name": "Singapore",
            "country": "Singapore",
            "lat": 1.25,
            "lng": 103.75
        },
        {
            "id": 20,
            "name": "Rotterdam",
            "country": "Netherlands",
            "lat": 51.95,
            "lng": 4.14
        }
    ],
    "vessels": [
        {
            "id": 5,
            "name": "EXAMPLE VESSEL"
        }
    ],
    "containers": [
        {
            "number": "MSCU1234567",
            "events": [
                {
                    "location": 10,
                    "description": "Loaded",
                    "status": "CLL",
                    "date": "2026-10-01 12:00:00",
                    "actual": true,
                    "vessel": 5,
                    "voyage": "126E"
                },
                {
                    "location": 20,
                    "description": "Vessel arrival",
                    "status": "VAD",
                    "date": "2026-10-12 08:00:00",
                    "actual": false,
                    "vessel": 5,
                    "voyage": "126E"
                }
            ]
        }
    ]
}

Cargotime — GET /v2/tracking

Фрагмент: data.

{
    "locations": [
        {
            "id": 0,
            "name": "Singapore",
            "country": "Singapore",
            "lat": 1.25,
            "lng": 103.75
        },
        {
            "id": 1,
            "name": "Rotterdam",
            "country": "Netherlands",
            "lat": 51.95,
            "lng": 4.14
        }
    ],
    "containers": [
        {
            "number": "MSCU1234567",
            "type": "40' High Cube Dry",
            "events": [
                {
                    "location": 1,
                    "status": "Vessel arrival",
                    "status_code": "VAD",
                    "date": "2026-10-12T08:00:00",
                    "actual": false,
                    "vessel": "EXAMPLE VESSEL",
                    "voyage": "126E"
                },
                {
                    "location": 0,
                    "status": "Loaded",
                    "status_code": "CLL",
                    "date": "2026-10-01T12:00:00",
                    "actual": true,
                    "vessel": "EXAMPLE VESSEL",
                    "voyage": "126E"
                }
            ]
        }
    ]
}

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

SeaRates	Cargotime	Что изменить
`containers[0].events[0].description = "Loaded"`	`containers[0].events[1].status = "Loaded"`	Текст события находится в `status`. Замените обращение к `description`.
`containers[0].events[0].status = "CLL"`	`containers[0].events[1].status_code = "CLL"`	Код события находится в `status_code`. В примере `CLL` обозначает погрузку в порту отправления, `VAD` — прибытие судна.
`containers[0].events[1].actual = false`	`containers[0].events[0].actual = false`	Сохраните проверку `actual`: `true` означает фактическое событие, `false` — плановое.
`containers[0].events[0].location = 10`	`containers[0].events[1].location = 0`	По `event.location` найдите объект с таким же `id` в `locations`. Числовые ID из SeaRates не используйте для поиска в новом ответе.
`containers[0].events[0].vessel = 5`	`containers[0].events[1].vessel = "EXAMPLE VESSEL"`	Получайте название судна прямо из `event.vessel`. Поиск в отдельном массиве судов больше не нужен.
`containers[0].events[0].date = "2026-10-01 12:00:00"`	`containers[0].events[1].date = "2026-10-01T12:00:00"`	Разбирайте дату с разделителем `T`. Если смещение часового пояса отсутствует, не добавляйте `Z` и не считайте время UTC.

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

Перед отключением SeaRates выгрузите нужные прошлые ответы и историю координат. Маршрут Cargotime может содержать текущую точку и участки пути, но не заменяет архив AIS или историю запросов SeaRates.

SeaRates

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

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

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

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

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

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

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

Примеры JSON

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