GoComet
Переход с GoComet на Cargotime API v2: ключи доступа, запросы и обработка ответов
Руководство описывает переход с GoComet Integration API v1 на Cargotime API v2. После запуска отслеживания GoComet возвращает постоянный tracking_id. Пакетный запрос Cargotime возвращает временный task_id, а постоянный ID доступен в результате задачи.
Общий порядок переноса номеров и настройки уведомлений приведён в порядке перехода. Полные схемы Cargotime — в справочнике API.
Аутентификация
Для доступа к GoComet сначала получают токен по электронной почте и паролю. Затем передают его в поле token. Базовый адрес GoComet — https://tracking.gocomet.com.
Для перехода на Cargotime:
- Создайте ключ в личном кабинете Cargotime.
- Замените базовый адрес на
https://tracking.cargotime.ru/v2. Например, полный адрес запроса отслеживания —https://tracking.cargotime.ru/v2/tracking. - Передавайте новый ключ в параметре URL
api_keyкаждого запроса, включая пакетные задачи и управление вебхуками. Ключи и токены прежнего сервиса не подходят.
Правила использования ключа и ограничения запросов — в разделе аутентификации.
Отслеживания и идентификаторы
| GoComet | Cargotime | Что изменить |
|---|---|---|
tracking / tracking_id | shipment / id | Сохраните связь tracking_id GoComet с новым ID отслеживания. Используйте новый ID для изменения подписи и остановки отслеживания. |
tracking_number + tracking_type | track_number.value + type | Перенесите номер и преобразуйте его тип по таблице параметров ниже. Внутренний tracking_id не является номером перевозчика. |
updated_trackings | data.data | Получайте текущие записи из data.data[]. Для сохранения истории изменений настройте вебхуки и сохраняйте уведомления у себя. |
Соответствие операций
| GoComet | Cargotime | Что изменить |
|---|---|---|
POST /api/v1/integrations/add_tracking_number | POST /v2/tracking/batch → GET /v2/tracking/batch | Отправьте один элемент в tracked_items. Получите результат задачи и сохраните постоянный ID из data.results[].data.tracking_metadata.id. |
POST /api/v1/integrations/add-multiple-tracking | POST /v2/tracking/batch → GET /v2/tracking/batch | Разбейте номера на группы до 500 элементов. Для каждой задачи получите результаты и проверьте success каждого элемента. |
GET /api/v1/integrations/live-tracking | GET /v2/shipments | Получите текущие записи через page и limit. Фильтров по исходным ID, номерам и периоду обновления в этом запросе нет. |
GET /api/v1/integrations/trackings-by-reference | GET /v2/shipments + ваша таблица ID | Храните связь своего номера заказа с новым ID. Получите страницы списка и выберите нужную запись по этому ID. |
POST /api/v1/integrations/update-multiple-tracking, add-or-update-multiple-tracking | Частичный аналог | Для изменения подписи используйте PATCH /v2/shipments/{id} с полем note. Для другого номера запустите отслеживание заново. Изменение всех полей одной операцией не поддерживается. |
DELETE /api/v1/integrations/delete-trackings | DELETE /v2/shipments | Передайте новые ID в массиве shipmentIds. Условия архивации и удаления описаны в жизненном цикле. |
PUT /api/v1/integrations/restore-trackings | Нет прямого аналога | Проверьте возможность повторной активации в жизненном цикле. Для неё используется новый запрос отслеживания, а не метод restore. |
GET /api/v1/integrations/mapdata | GET /v2/shipments?need_route=true | Получайте маршрут из tracked_item.data.data.route_info выбранной записи. Переведите обработчик карты на массивы точек этой структуры. |
Параметры запроса
| GoComet | Cargotime | Что изменить |
|---|---|---|
tracking.tracking_number | tracked_items[].track_number.value | Передайте номер в tracked_items[].track_number.value в теле пакетного запроса. |
tracking.tracking_type | tracked_items[].track_number.type | Замените cn на container, bl оставьте без изменения, bn замените на bk. Типы pro, po и ln этим API не поддерживаются. |
tracking.mode | Нет отдельного параметра | Не передавайте mode. Это руководство относится к морским перевозкам, для которых в GoComet используется ocean. |
tracking.carrier_code | tracked_items[].company | Сопоставьте код GoComet со SCAC из GET /v2/companies и передайте SCAC в company. |
tracking.reference_no / remarks / other_data | note + ваша система | Сохраните одну подпись до 40 символов через PATCH /v2/shipments/{id} в note. Остальные сведения оставьте в своей системе. |
start_date / end_date / tracking_ids[] | page / limit / status | Удалите эти фильтры из запроса. Получайте текущие записи постранично и выбирайте нужные ID у себя. Историю за период сохраняйте отдельно. |
Поля ответа
В ответе GET /v2/shipments выберите запись из data.data[]. Пути, начинающиеся с tracked_item, указаны относительно этой записи. Контейнеры находятся в tracked_item.data.data.containers[], события — в events[] каждого контейнера. В ответе GET /v2/tracking данные перевозки находятся сразу в data.
| GoComet | Cargotime | Как обработать ответ |
|---|---|---|
tracking_id при создании | data.task_id → results[].data.tracking_metadata.id | После запуска сохраните временный data.task_id. Получив результат задачи, свяжите исходный tracking_id с постоянным data.results[].data.tracking_metadata.id. |
updated_trackings[] | data.data[] | Перебирайте data.data[] вместо updated_trackings[]. Это список текущих записей, поэтому не считайте каждый элемент новым изменением. |
tracking_id / tracking_number / container_number | id / tracked_item.track_number / tracked_item.data.data.containers[].number | Разделите три значения: id записи, запрошенный номер в tracked_item.track_number и номера физических контейнеров в containers[].number. |
status | tracked_item.data.data.shipment_status | Получайте состояние из tracked_item.data.data.shipment_status. Обработку отсутствующих данных выполняйте по tracked_item.data.status. |
events[].event | tracked_item.data.data.containers[].events[].status_code | Используйте status_code события. Проверяйте этап перевозки: въезд контейнера, погрузка и прибытие судна имеют разные коды. |
events[].actual_datetime / planned_datetime | events[].date / actual | Получайте дату из date и проверяйте actual. При переносе старых данных берите actual_datetime, если она есть, иначе planned_datetime. |
Примеры ответов
В каждой паре подписаны ответы прежнего сервиса и Cargotime. Большие JSON-примеры можно раскрыть отдельно от таблиц сопоставления. Это сокращённые примеры с условными данными. Над каждым JSON указан путь к показанной части ответа. Пути в следующей таблице начинаются от этой части.
Принятие отслеживания
GoComet — POST /api/v1/integrations/add_tracking_number
Ответ, сокращённо.
{
"tracking_id": "33333333-3333-4333-8333-333333333333",
"message": "Added Successfully",
"status": "success"
}Cargotime — POST /v2/tracking/batch
Ответ, сокращённо.
{
"success": true,
"status": "OK",
"data": {
"task_id": "22222222-2222-4222-8222-222222222222"
}
}Как сопоставить
| GoComet | Cargotime | Что изменить |
|---|---|---|
tracking_id = "33333333-3333-4333-8333-333333333333" | data.task_id = "22222222-2222-4222-8222-222222222222" | ID GoComet относится к отслеживанию, а новый task_id — только к фоновой задаче. Постоянный ID получите из результата задачи. |
status = "success" | status = "OK" | OK сообщает, что запрос принят. Наличие данных по номеру проверяйте отдельно в результате задачи. |
Ответ на запуск содержит только ID задачи. После PROCESSED получите постоянный ID из data.results[].data.tracking_metadata.id и используйте его для поиска записи в списке и изменения подписи.
Сохранённое отслеживание и оборудование
GoComet — GET /api/v1/integrations/live-tracking
Фрагмент: updated_trackings[0].
{
"tracking_id": "33333333-3333-4333-8333-333333333333",
"tracking_number": "MSCU1234567",
"container_number": "MSCU1234567",
"carrier_code": "MSCU",
"carrier_name": "MSC",
"reference_no": "Order 123",
"container_size": "40 ft",
"container_type": "High Cube",
"pol_name": "Singapore, SGSIN",
"pod_name": "Rotterdam, NLRTM",
"archived": false,
"other_data": {
"purchase_order": "PO-456"
}
}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"]
},
"pol": {
"location": 0,
"date": "2026-10-01T12:00:00"
},
"pod": {
"location": 1,
"date": "2026-10-12T08:00:00"
}
},
"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"
}
]
}
}
}
}Как сопоставить
| GoComet | Cargotime | Что изменить |
|---|---|---|
tracking_id = "33333333-3333-4333-8333-333333333333" | id = "11111111-1111-4111-8111-111111111111" | Сохраните исходный и новый ID в одной таблице соответствий. Используйте новый ID в запросах управления отслеживанием. |
tracking_number = "MSCU1234567" | tracked_item.track_number = "MSCU1234567" | Получайте запрошенный номер из tracked_item.track_number. Если запрос был по коносаменту, это будет номер коносамента, а не контейнера. |
reference_no = "Order 123" | note = "Order 123" | Перенесите номер заказа в note после создания отслеживания. Значение должно укладываться в 40 символов. |
container_type = "High Cube" | tracked_item.data.data.containers[0].type = "40' High Cube" | Получайте размер и тип из одной строки containers[].type. Отдельное поле размера в этом ответе не предусмотрено. |
pod_name = "Rotterdam, NLRTM" | tracked_item.data.data.locations[1].name = "Rotterdam" | Для названия порта выгрузки найдите locations с id, равным summary.pod.location. Индекс массива может отличаться от ID. |
other_data | Нет прямого аналога | Сохраните other_data в своей базе. В ответе отслеживания отдельного поля для произвольных данных нет. |
Фактические и плановые даты
GoComet — GET /api/v1/integrations/live-tracking
Фрагмент: updated_trackings[0].
{
"container_number": "MSCU1234567",
"events": [
{
"event": "gate_in",
"carrier_event": "Gate in full",
"location": "SINGAPORE, SG",
"actual_datetime": "01/10/2026 10:00:00",
"planned_datetime": "01/10/2026 09:00:00",
"vessel_details": {
"vessel_name": "",
"voyage_num": null
}
},
{
"event": "arrival",
"carrier_event": "Vessel arrival",
"location": "ROTTERDAM, NL",
"actual_datetime": "",
"planned_datetime": "12/10/2026 08:00:00",
"vessel_details": {
"vessel_name": "EXAMPLE VESSEL",
"voyage_num": "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",
"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": "Gate in full",
"status_code": "CGI",
"date": "2026-10-01T10:00:00",
"actual": true,
"vessel": null,
"voyage": null
}
]
}
]
}Как сопоставить
| GoComet | Cargotime | Что изменить |
|---|---|---|
events[0].actual_datetime = "01/10/2026 10:00:00" | containers[0].events[1].date = "2026-10-01T10:00:00" | При переносе этой даты разберите формат дд/ММ/гггг ЧЧ:мм:сс и установите actual=true. Часовой пояс нельзя определить по такой строке. |
events[1].planned_datetime = "12/10/2026 08:00:00" | containers[0].events[0].date = "2026-10-12T08:00:00" | Используйте плановую дату только при отсутствии фактической и установите actual=false. |
events[0].event = "gate_in" | containers[0].events[1].status_code = "CGI" | Въезд гружёного контейнера в примере соответствует CGI. Сохраните отдельную обработку других операций с контейнером. |
events[1].event = "arrival" | containers[0].events[0].status_code = "VAD" | Прибытие судна в примере соответствует VAD. Не используйте этот код как подтверждение выгрузки контейнера. |
events[1].vessel_details.vessel_name = "EXAMPLE VESSEL" | containers[0].events[0].vessel = "EXAMPLE VESSEL" | Получайте название судна прямо из event.vessel вместо vessel_details.vessel_name. |
Разберите формат dd/MM/yyyy HH:mm:ss. Он не содержит часового пояса, не добавляйте UTC автоматически. Историю первоначальных прогнозов храните отдельно.
Отслеживание существует, но данных пока нет
GoComet — GET /api/v1/integrations/live-tracking
Фрагмент: updated_trackings[0].
{
"tracking_id": "33333333-3333-4333-8333-333333333333",
"tracking_number": "MSCU1234567",
"status": "Data Not Found",
"archived": false,
"events": []
}Cargotime — GET /v2/shipments
Фрагмент: data.data[0].
{
"id": "11111111-1111-4111-8111-111111111111",
"status": "ACTIVE",
"track_number": "MSCU1234567",
"tracked_item": {
"track_number": "MSCU1234567",
"track_number_type": "container",
"data": {
"status": "INFO_NOT_FOUND",
"data": null
}
}
}Как сопоставить
| GoComet | Cargotime | Что изменить |
|---|---|---|
status = "Data Not Found" | tracked_item.data.status = "INFO_NOT_FOUND" | Проверяйте tracked_item.data.status на INFO_NOT_FOUND. Это отсутствие данных, а не состояние доставленной перевозки. |
archived = false | status = "ACTIVE" | При status: "ACTIVE" подписка остаётся действующей, даже если сведения о перевозке пока не найдены. |
events = [] | tracked_item.data.data = null | Перед обращением к контейнерам проверьте, что tracked_item.data.data не равен null. Пустой ответ не подтверждает завершение перевозки. |
Что сохранить отдельно
Коды GoComet для создания отслеживаний доступны в шаблоне массовой загрузки Bulk Upload Template. При переходе сопоставьте их со SCAC из GET /v2/companies. Одну подпись можно сохранить в note, а коллекции тегов и поиск по ним следует оставить в своей системе. Расписания, сведения об инцидентах и аналитические отчёты GoComet в ответ отслеживания не переносятся.
Обновлено