Vizion
Переход с Vizion на Cargotime API v2: ключи доступа, запросы и обработка ответов
Руководство описывает переход с Vizion Container Tracking API на Cargotime API v2. В Vizion reference — запись отслеживания номера, а update — данные, полученные при отдельном обновлении. При переходе сохраните ID записей и нужную историю обновлений.
Общий порядок переноса номеров и настройки уведомлений приведён в порядке перехода. Полные схемы Cargotime — в справочнике API.
Аутентификация
Vizion передаёт ключ в заголовке X-API-Key. Базовый адрес Vizion — https://prod.vizionapi.com.
Для перехода на Cargotime:
- Создайте ключ в личном кабинете Cargotime.
- Замените базовый адрес на
https://tracking.cargotime.ru/v2. Например, полный адрес запроса отслеживания —https://tracking.cargotime.ru/v2/tracking. - Передавайте новый ключ в параметре URL
api_keyкаждого запроса, включая пакетные задачи и управление вебхуками. Ключи и токены прежнего сервиса не подходят.
Правила использования ключа и ограничения запросов — в разделе аутентификации.
Отслеживания и идентификаторы
| Vizion | Cargotime | Что изменить |
|---|---|---|
reference | shipment | Сохраните связь ID reference с новым ID отслеживания. Для управления записью используйте новый ID. |
parent reference / child references | shipment + containers[] | Для коносамента или букинга обрабатывайте контейнеры внутри одного результата. Связи исходных родительских и дочерних ID сохраните у себя. |
update / milestone | Данные обновления / containers[].events[] | Получайте текущие данные из записи отслеживания, события перевозки из containers[].events[]. Для истории обновлений сохраняйте получаемые вебхуки. |
Соответствие операций
| Vizion | Cargotime | Что изменить |
|---|---|---|
POST /references | POST /v2/tracking/batch → GET /v2/tracking/batch | Отправьте номера, получите результат задачи и сохраните постоянный ID из data.results[].data.tracking_metadata.id. |
GET /references | GET /v2/shipments?status=ACTIVE | Получайте действующие записи постранично через page и limit. Для архива используйте отдельный запрос с status=ARCHIVED. |
GET /references/{referenceId} | GET /v2/shipments | Получите страницы списка и найдите запись по новому ID из вашей таблицы соответствий. Отдельного запроса по ID нет. |
GET /references/{referenceId}/updates | /v2/webhooks + сохранение снимков | Выгрузите прошлые обновления из Vizion. Для будущей истории настройте вебхуки и сохраняйте каждое полученное уведомление у себя. |
GET /references/last-known-positions | GET /v2/shipments?need_route=true | Получайте route_info.current_position у сохранённого отслеживания. Историю координат Vizion сохраните отдельно. |
GET /carriers | GET /v2/companies | Сопоставьте код Vizion со SCAC из нового справочника. Проверьте поддержку нужного типа номера в cn, bl, bk. |
POST/DELETE /tags, привязка тегов | PATCH /v2/shipments/{id} (частично) | Перенесите одну подпись до 40 символов в note. Коллекцию тегов и связи с отслеживаниями храните в своей системе. |
DELETE /references/{referenceId} | DELETE /v2/shipments | Передайте новые ID в массиве shipmentIds. Проверьте правила архивации и удаления в жизненном цикле. |
Параметры запроса
| Vizion | Cargotime | Что изменить |
|---|---|---|
container_id / bill_of_lading / booking_number | tracked_items[].track_number.value + type | Выберите основной номер и передайте его в track_number.value. Для контейнера укажите type: "container", коносамента — bl, букинга — bk. |
carrier_code / scac | tracked_items[].company | Найдите соответствующий SCAC в GET /v2/companies. Не считайте внутренний код Vizion подходящим без проверки. |
callback_url | POST /v2/webhooks | Уберите callback_url из запроса отслеживания. Создайте вебхук отдельным POST /v2/webhooks по руководству. |
tags / reference metadata | note + ваша система | После получения постоянного ID сохраните одну подпись в note через PATCH /v2/shipments/{id}. Остальные данные храните у себя. |
pagination / filters | page / limit / status | Используйте page, limit и фильтр подписки status. Остальные условия отбора применяйте у себя после получения страниц. |
Поля ответа
В ответе GET /v2/shipments выберите запись из data.data[]. Пути, начинающиеся с tracked_item, указаны относительно этой записи. Контейнеры находятся в tracked_item.data.data.containers[], события — в events[] каждого контейнера. В ответе GET /v2/tracking данные перевозки находятся сразу в data.
| Vizion | Cargotime | Как обработать ответ |
|---|---|---|
reference.id / id | data.data[].id | Сохраните новый data.data[].id рядом с исходным ID Vizion. Эти ID выданы разными системами и не совпадают. |
active | data.data[].status | Замените проверку логического active на сравнение со строками ACTIVE и ARCHIVED. |
last_update_status | tracked_item.data.success / status | Проверяйте наличие данных по вложенным success и status. Ошибки доставки вебхука проверяйте отдельно в журнале уведомлений. |
update.payload.milestones[] | tracked_item.data.data.containers[].events[] | Получайте события из containers[].events[]. Замените timestamp на date, description на status, а planned — на обратное значение actual. |
geolocation.latitude / longitude | route_info.current_position | Получайте координаты из массива current_position: первый элемент — широта, второй — долгота. Обработайте возможный null. |
timestamp / mode_details | route_info.last_updated / частично | last_updated относится к обновлению текущей позиции и может быть null. Источник позиции может отличаться от Vizion; полного объекта mode_details нет. |
Примеры ответов
В каждой паре подписаны ответы прежнего сервиса и Cargotime. Большие JSON-примеры можно раскрыть отдельно от таблиц сопоставления. Это сокращённые примеры с условными данными. Над каждым JSON указан путь к показанной части ответа. Пути в следующей таблице начинаются от этой части.
Запись отслеживания, номер и статус подписки
Vizion — GET /references/{referenceId}
Ответ, сокращённо.
{
"id": "33333333-3333-4333-8333-333333333333",
"container_id": "MSCU1234567",
"bill_of_lading": null,
"carrier_code": "MSCU",
"active": true,
"last_update_status": "data_received",
"latest_update_id": "55555555-5555-4555-8555-555555555555",
"parent_reference_id": null
}Cargotime — GET /v2/shipments
Фрагмент: data.data[0].
{
"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"]
}
},
"shipment_status": "IN_TRANSIT",
"containers": [
{
"number": "MSCU1234567",
"type": "40' High Cube Dry"
}
]
}
}
}
}Как сопоставить
| Vizion | Cargotime | Что изменить |
|---|---|---|
id = "33333333-3333-4333-8333-333333333333" | id = "11111111-1111-4111-8111-111111111111" | Свяжите исходный ID reference с новым id в своей базе. Не передавайте ID Vizion в методы управления отслеживанием. |
container_id = "MSCU1234567" | tracked_item.track_number = "MSCU1234567" | Здесь container_id содержит номер контейнера. Получайте тот же номер из tracked_item.track_number. |
active = true | status = "ACTIVE" | Вместо active=true проверяйте status: "ACTIVE". Это статус подписки, а не этап перевозки. |
last_update_status = "data_received" | tracked_item.data.status = "OK" | Значению data_received в примере соответствует вложенный status: "OK". Состояние перевозки проверяйте отдельно в shipment_status. |
carrier_code = "MSCU" | tracked_item.data.data.summary.company.scacs = ["MEDU","MSCU"] | Ищите MSCU в массиве scacs. В других записях сначала проверьте соответствие кода Vizion новому справочнику. |
latest_update_id = "55555555-5555-4555-8555-555555555555" | Нет прямого аналога | Отдельного ID обновления в текущем ответе нет. Сохраните старый latest_update_id вместе с архивом обновлений, если он нужен. |
События и плановые даты перевозки
Vizion — GET /references/{referenceId}/updates
Фрагмент: [0].
{
"id": "55555555-5555-4555-8555-555555555555",
"reference_id": "33333333-3333-4333-8333-333333333333",
"status": "data_received",
"payload": {
"container_id": "MSCU1234567",
"container_iso": "45G1",
"carrier_scac": "MSCU",
"milestones": [
{
"description": "Loaded",
"timestamp": "2026-10-01T04:00:00Z",
"planned": false,
"shipment_location": {
"type_code": "POL"
},
"location": {
"name": "Singapore",
"unlocode": "SGSIN",
"geolocation": {
"latitude": 1.25,
"longitude": 103.75
}
},
"vessel": "EXAMPLE VESSEL",
"voyage": "126E"
},
{
"description": "Vessel arrival",
"timestamp": "2026-10-12T06:00:00Z",
"planned": true,
"shipment_location": {
"type_code": "POD"
},
"location": {
"name": "Rotterdam",
"unlocode": "NLRTM",
"geolocation": {
"latitude": 51.95,
"longitude": 4.14
}
},
"vessel": "EXAMPLE VESSEL",
"voyage": "126E"
}
]
}
}Cargotime — GET /v2/shipments
Фрагмент: data.data[0].tracked_item.data.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"
}
]
}
]
}Как сопоставить
| Vizion | Cargotime | Что изменить |
|---|---|---|
payload.container_id = "MSCU1234567" | containers[0].number = "MSCU1234567" | Найдите контейнер по containers[].number и обрабатывайте события именно этого контейнера. |
payload.milestones[0].description = "Loaded" | containers[0].events[1].status = "Loaded" | Текст Loaded находится в status. Для программной обработки погрузки в порту отправления используйте status_code: "CLL". |
payload.milestones[0].planned = false | containers[0].events[1].actual = true | Для фактического события замените planned=false на actual=true. |
payload.milestones[1].planned = true | containers[0].events[0].actual = false | Для планового события замените planned=true на actual=false. |
payload.milestones[0].location | locations[0] | Ищите объект места в locations по значению event.location. Не ожидайте вложенный объект внутри события. |
payload.milestones[0].timestamp = "2026-10-01T04:00:00Z" | containers[0].events[1].date = "2026-10-01T12:00:00" | В примере 04:00 UTC соответствует 12:00 в Сингапуре. При сравнении дат учитывайте часовой пояс места, а не просто удаляйте Z. |
payload.container_iso = "45G1" | Нет прямого аналога | Отдельного ISO-кода оборудования нет. Сохраните 45G1 у себя, если ваша система использует этот классификатор. |
В примере Vizion показано одно обновление из массива, а в примере Cargotime — текущие данные сохранённого отслеживания. Для хранения всех прошлых обновлений нужен отдельный архив.
Последняя позиция и сведения о судне
Vizion — GET /references/last-known-positions
Фрагмент: [0].
{
"reference_id": "33333333-3333-4333-8333-333333333333",
"container_id": "MSCU1234567",
"timestamp": "2026-10-03T08:30:00Z",
"mode": "Vessel",
"mode_details": {
"vessel": "EXAMPLE VESSEL",
"vessel_imo": "9000003"
},
"geolocation": {
"latitude": 1.25,
"longitude": 103.75
}
}Cargotime — GET /v2/shipments?need_route=true
Фрагмент: data.data[0].
{
"id": "11111111-1111-4111-8111-111111111111",
"tracked_item": {
"data": {
"data": {
"route_info": {
"current_position": [1.25, 103.75],
"last_updated": "2026-10-03T09:00:00"
}
}
}
}
}Как сопоставить
| Vizion | Cargotime | Что изменить |
|---|---|---|
reference_id = "33333333-3333-4333-8333-333333333333" | id = "11111111-1111-4111-8111-111111111111" | Найдите новый ID по сохранённой связи с reference_id. Исходный ID Vizion в новом ответе не появится. |
geolocation | tracked_item.data.data.route_info.current_position = [1.25,103.75] | Получайте точку из массива [широта, долгота], например [1.25, 103.75]. |
timestamp = "2026-10-03T08:30:00Z" | tracked_item.data.data.route_info.last_updated = "2026-10-03T09:00:00" | last_updated относится к текущей позиции нового ответа. Она может быть получена из другого источника, поэтому сохраняйте исходную метку Vizion отдельно. |
mode_details.vessel_imo = "9000003" | Нет прямого аналога | IMO судна отдельным полем не возвращается. Храните его у себя, если он нужен для связи с внешними данными о судах. |
Что сохранить отдельно
Выгрузите нужные обновления Vizion до отключения сервиса. Для будущей истории сохраняйте входящие вебхуки у себя. Список /v2/shipments возвращает текущие данные, а журнал /v2/webhook-notifications — сведения о доставке уведомлений. Для получения существующей записи используйте список, а не повторный запуск /v2/tracking.
Обновлено