Qubictron
Переход с Qubictron на Cargotime API v2: ключи доступа, запросы и обработка ответов
Руководство описывает переход с Qubictron Container Tracking API v1 на Cargotime API v2. В Qubictron маршрут запрашивается параметром route_details у метода /ocean.
Общий порядок переноса номеров и настройки уведомлений приведён в порядке перехода. Полные схемы Cargotime — в справочнике API.
Аутентификация
Qubictron передаёт ключ в заголовке x-api-key. Базовый адрес Qubictron — https://api.qubictron.com/tracking/v1.
Для перехода на Cargotime:
- Создайте ключ в личном кабинете Cargotime.
- Замените базовый адрес на
https://tracking.cargotime.ru/v2. Например, полный адрес запроса отслеживания —https://tracking.cargotime.ru/v2/tracking. - Передавайте новый ключ в параметре URL
api_keyкаждого запроса, включая пакетные задачи и управление вебхуками. Ключи и токены прежнего сервиса не подходят.
Правила использования ключа и ограничения запросов — в разделе аутентификации.
Отслеживания и идентификаторы
| Qubictron | Cargotime | Что изменить |
|---|---|---|
shipment | data | Получайте сводку перевозки из data.summary, контейнеры из data.containers. Замените обращения к объекту shipment. |
facilities / locations | terminals / locations | Ищите место и терминал события в массивах нового ответа по полям location и terminal. Исходные числовые ID не сохраняются. |
transports | containers[].events[].vessel / voyage | Получайте название судна и рейс из vessel и voyage каждого события. Отдельного массива transports нет. |
Соответствие операций
| Qubictron | Cargotime | Что изменить |
|---|---|---|
GET /ocean | GET /v2/tracking | Передайте номер в value, тип в type, SCAC перевозчика в company. Для нескольких номеров используйте POST /v2/tracking/batch. |
GET /ocean/carriers | GET /v2/companies | Найдите перевозчика по SCAC и проверьте поддержку нужного типа номера в полях cn, bl и bk. |
Параметры запроса
| Qubictron | Cargotime | Что изменить |
|---|---|---|
reference_number | value | Передайте reference_number в параметре URL value без изменения номера. |
reference_type | type | Используйте container для контейнера, bl для коносамента, bk вместо booking для букинга. Тип обязателен. |
carrier_code | company | Проверьте carrier_code через GET /v2/companies и передайте соответствующий SCAC в company. |
route_details | need_route | Замените route_details=true на need_route=true. Обработчик ответа должен использовать структуру route_info. |
Поля ответа
В этой таблице пути указаны от корня ответа GET /v2/tracking. В списке /v2/shipments данные перевозки находятся внутри каждой записи в tracked_item.data.data. Формат вебхуков описан в отдельном разделе.
| Qubictron | Cargotime | Как обработать ответ |
|---|---|---|
success / status_code | success / status | Проверяйте success и status в JSON, даже если HTTP-код равен 200. Перепишите обработку ошибок под значения нового status. |
data.shipment.reference_number | request.track_number.value | Получайте исходный номер из request.track_number.value. Для управления отслеживанием сохраняйте отдельный data.tracking_metadata.id. |
data.shipment.carrier | data.summary.company | Вместо carrier.code проверяйте массив company.scacs. Название берите из company.name или company.full_name. |
data.shipment.status | data.shipment_status | Получайте состояние перевозки из data.shipment_status и обновите обработку допустимых значений. |
events[].datetime / is_actual | events[].date / actual | В событиях контейнера замените datetime на date, is_actual на actual. Сохраняйте различие между фактическими и плановыми датами. |
events[].event_code | events[].status_code | Проверяйте этап погрузки: LOAD в порту отправления соответствует CLL, при перегрузке — CLT. Одной замены названия кода недостаточно. |
events[].location_id / facility_id | events[].location / terminal | По location найдите id в data.locations, по terminal — в data.terminals. Не переносите числовые ID из Qubictron. |
data.route | data.summary | Получайте порт погрузки из data.summary.pol, порт выгрузки из data.summary.pod. Координаты линии маршрута находятся отдельно в data.route_info. |
data.containers[].route_details | data.route_info | Получайте путь из route_info.route[].path, текущую точку из route_info.current_position. Отдельные поля AIS из Qubictron могут отсутствовать. |
Примеры ответов
В каждой паре подписаны ответы прежнего сервиса и Cargotime. Большие JSON-примеры можно раскрыть отдельно от таблиц сопоставления. Это сокращённые примеры с условными данными. Над каждым JSON указан путь к показанной части ответа. Пути в следующей таблице начинаются от этой части.
Номер, перевозчик и тип контейнера
Qubictron — GET /ocean
Ответ, сокращённо.
{
"success": true,
"status_code": "OK",
"data": {
"shipment": {
"reference_number": "MSCU1234567",
"reference_type": "CONTAINER",
"carrier": {
"code": "MSCU",
"name": "MSC"
},
"status": "IN_TRANSIT"
},
"containers": [
{
"number": "MSCU1234567",
"size": 40,
"type": "High Cube Dry",
"iso_code": "45G1"
}
]
}
}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"
}
}
}Как сопоставить
| Qubictron | Cargotime | Что изменить |
|---|---|---|
data.shipment.reference_type = "CONTAINER" | request.track_number.type = "container" | В запросах используйте container в нижнем регистре. Значение CONTAINER из исходного ответа не копируйте в type. |
data.shipment.reference_number = "MSCU1234567" | request.track_number.value = "MSCU1234567" | Номер не меняется. Получайте его из request.track_number.value. |
data.shipment.carrier.code = "MSCU" | data.summary.company.scacs = ["MEDU","MSCU"] | Проверяйте наличие MSCU в массиве scacs, а не равенство поля одной строке. |
data.shipment.status = "IN_TRANSIT" | data.shipment_status = "IN_TRANSIT" | Получайте IN_TRANSIT из shipment_status. Статус подписки проверяется отдельно в tracking_metadata.status. |
data.containers[0].type = "High Cube Dry" | data.containers[0].type = "40' High Cube Dry" | В новом ответе размер и тип указаны одной строкой containers[].type. Обновите отображение этих сведений. |
data.containers[0].iso_code = "45G1" | Нет прямого аналога | Отдельного iso_code нет. Храните прежний код у себя, если он нужен для учёта оборудования. |
Фактическое и плановое события
Qubictron — GET /ocean
Фрагмент: data.
{
"locations": [
{
"id": 10,
"name": "Singapore",
"coordinates": {
"lat": 1.25,
"lng": 103.75
}
},
{
"id": 20,
"name": "Rotterdam",
"coordinates": {
"lat": 51.95,
"lng": 4.14
}
}
],
"transports": [
{
"id": 5,
"type": "VESSEL",
"name": "EXAMPLE VESSEL"
}
],
"containers": [
{
"number": "MSCU1234567",
"events": [
{
"event_code": "LOAD",
"description": "Loaded",
"datetime": "2026-10-01T12:00:00+08:00",
"is_actual": true,
"location_id": 10,
"location_type": "FIRST_PORT_OF_LOADING",
"transport_id": 5,
"voyage_number": "126E"
},
{
"event_code": "ARRI",
"description": "Vessel arrival",
"datetime": "2026-10-12T08:00:00+02:00",
"is_actual": false,
"location_id": 20,
"location_type": "FINAL_PORT_OF_DISCHARGE",
"transport_id": 5,
"voyage_number": "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"
}
]
}
]
}Как сопоставить
| Qubictron | Cargotime | Что изменить |
|---|---|---|
containers[0].events[0].event_code = "LOAD" | containers[0].events[1].status_code = "CLL" | В примере погрузка происходит в порту отправления, поэтому используйте CLL. Для погрузки при перегрузке применяется CLT. |
containers[0].events[1].event_code = "ARRI" | containers[0].events[0].status_code = "VAD" | Прибытие судна в порт выгрузки обозначено VAD. Оно само по себе не подтверждает выгрузку контейнера или доставку. |
containers[0].events[1].is_actual = false | containers[0].events[0].actual = false | Значение false сохраняет плановый характер даты. Не показывайте это событие как уже произошедшее. |
containers[0].events[0].location_id = 10 | containers[0].events[1].location = 0 | В примере место события имеет ID 0 в новом массиве locations. Ищите объект по этому ID, а не по прежнему 10. |
containers[0].events[0].transport_id = 5 | containers[0].events[1].vessel = "EXAMPLE VESSEL" | Название судна теперь находится в самом событии. Уберите поиск по transport_id в массиве transports. |
containers[0].events[0].voyage_number = "126E" | containers[0].events[1].voyage = "126E" | Получайте номер рейса из event.voyage. В примере значение остаётся 126E. |
Даты показывают форматы полей. При переносе учитывайте смещение и часовой пояс источника: удаление Z или +08:00 не является преобразованием времени.
Маршрут и текущее местоположение
Qubictron — GET /ocean?route_details=true
Фрагмент: data.containers[0].route_details.
{
"predicted_position": {
"coordinates": {
"lat": 1.25,
"lng": 103.75
}
},
"latest_ais_data": {
"transport_id": 5,
"coordinates": {
"lat": 1.2,
"lng": 103.7
},
"timestamp": "2026-10-03T08:30:00Z"
},
"route_legs": [
{
"from_location_id": 10,
"to_location_id": 20,
"transport_mode": "VESSEL",
"route_path": [
[1.25, 103.75],
[1.1, 103.4]
]
}
]
}Cargotime — GET /v2/tracking?need_route=true
Фрагмент: data.route_info.
{
"current_position": [1.25, 103.75],
"last_updated": "2026-10-03T09:00:00",
"route": [
{
"type": "sea",
"path": [
[1.25, 103.75],
[1.1, 103.4]
]
}
]
}Как сопоставить
| Qubictron | Cargotime | Что изменить |
|---|---|---|
predicted_position.coordinates | current_position = [1.25,103.75] | Получайте текущую точку как массив [широта, долгота]. Не ожидайте объект с отдельными свойствами координат. |
route_legs[0].route_path | route[0].path | Обрабатывайте route_info.route[] и массив точек path каждого участка вместо route_legs[].route_path. |
route_legs[0].transport_mode = "VESSEL" | route[0].type = "sea" | Для морского участка используйте type: "sea" вместо transport_mode: "VESSEL". |
latest_ais_data | Нет прямого аналога | Не подставляйте текущую точку маршрута вместо последнего измерения AIS. Данные измерения и его время храните отдельно, если они нужны. |
Что сохранить отдельно
Отдельные данные AIS и прогнозы Qubictron могут отсутствовать в ответе Cargotime. Проверьте, какие из этих полей использует ваше приложение, и сохраните необходимые сведения до перехода. Сведения о поддержке вебхуков Qubictron не удалось найти в открытой документации. Если вы уже получаете такие уведомления, проверьте настройки аккаунта и создайте вебхуки Cargotime отдельно по руководству.
Обновлено