Порядок перехода

Следуйте этому порядку вместе с руководством по вашему сервису. Здесь описаны общие действия, а на странице сервиса указано, какие методы и поля заменить. Полные схемы запросов и ответов — в справочнике API.

1. Сохраните номера и связи идентификаторовСкопировать ссылку на раздел

Одна запись Cargotime отслеживает один номер: контейнера, коносамента (bl) или букинга (bk, бронирования перевозки). Результат по коносаменту или букингу может содержать несколько контейнеров. Внутренние ID прежнего сервиса не переносятся. После запуска сохраните соответствие старых и новых ID в своей базе.

2. Настройте аутентификацию и параметры запросаСкопировать ссылку на раздел

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

Для одного номера используйте GET /v2/tracking, для нескольких — POST /v2/tracking/batch.

Номер, тип и перевозчик обязательны. Через GET /v2/companies найдите SCAC перевозчика и проверьте поддержку нужного типа номера в cn, bl или bk. Числовой ID или внутренний код другого сервиса сначала сопоставьте с этим справочником. Автоматическое определение перевозчика company=AUTO доступно только при type=container. Для коносамента и букинга укажите SCAC.

3. Настройте вебхуки и сохраните историюСкопировать ссылку на раздел

Если нужны уведомления с первых обновлений, создайте вебхуки через POST /v2/webhooks до переноса номеров. Они настраиваются для аккаунта. Передавать callback_url в каждом запросе отслеживания не нужно. Настройте event_types, новый секрет, проверку подписи и обработку повторных доставок по руководству по вебхукам.

GET /v2/webhook-notifications содержит сведения о доставке уведомлений. Для собственного архива обновлений сохраняйте полученные уведомления у себя. Историю прежнего сервиса, теги, сроки бесплатного вывоза контейнеров, сборы, измерения AIS и пользовательские поля выгрузите отдельно.

4. Разделите запуск отслеживания и получение сохранённых данныхСкопировать ссылку на раздел

Для получения одной сохранённой записи найдите её по новому ID в страницах /v2/shipments. Отдельного GET /v2/shipments/{id} и фильтра списка по ID нет. Не заменяйте получение сохранённых данных повторным запуском /v2/tracking: у этих операций разное назначение и правила списания кредитов.

Например, запрос одного контейнера:

GET https://tracking.cargotime.ru/v2/tracking?api_key=YOUR_API_KEY&value=MSCU1234567&type=container&company=MSCU

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

Отправьте POST /v2/tracking/batch?api_key=YOUR_API_KEY с телом:

{
    "tracked_items": [
        {
            "track_number": {
                "type": "container",
                "value": "MSCU1234567"
            },
            "company": "MSCU"
        }
    ]
}

Ответ на запуск содержит ID задачи. Данные перевозки нужно получить отдельным запросом:

Ответ POST /v2/tracking/batch

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

Затем выполните GET /v2/tracking/batch?api_key=YOUR_API_KEY&task_id=22222222-2222-4222-8222-222222222222. Ниже показан пример завершённой задачи с условными данными контейнера, событиями и постоянным ID отслеживания.

{
    "success": true,
    "status": "OK",
    "data": {
        "task_id": "22222222-2222-4222-8222-222222222222",
        "status": "PROCESSED",
        "results": [
            {
                "success": true,
                "status": "OK",
                "status_description": "Информация найдена",
                "request": {
                    "track_number": {
                        "type": "container",
                        "value": "MSCU1234567"
                    },
                    "company": "MSCU"
                },
                "data": {
                    "summary": {
                        "origin": {
                            "location": null,
                            "terminal": null,
                            "date": null
                        },
                        "pol": {
                            "location": 0,
                            "terminal": null,
                            "date": "2026-10-01T12:00:00"
                        },
                        "pod": {
                            "location": 1,
                            "terminal": null,
                            "date": "2026-10-12T08:00:00"
                        },
                        "destination": {
                            "location": null,
                            "terminal": null,
                            "date": null
                        },
                        "company": {
                            "name": "MSC",
                            "full_name": "Mediterranean Shipping Company",
                            "url": "https://www.msc.com/",
                            "scacs": ["MEDU", "MSCU"]
                        }
                    },
                    "locations": [
                        {
                            "id": 0,
                            "name": "Singapore",
                            "state": null,
                            "terminal": null,
                            "country": "Singapore",
                            "lat": 1.264,
                            "lng": 103.84
                        },
                        {
                            "id": 1,
                            "name": "Rotterdam",
                            "state": null,
                            "terminal": null,
                            "country": "Netherlands",
                            "lat": 51.95,
                            "lng": 4.14
                        }
                    ],
                    "terminals": [],
                    "containers": [
                        {
                            "number": "MSCU1234567",
                            "type": "40' High Cube Dry",
                            "events": [
                                {
                                    "location": 1,
                                    "terminal": null,
                                    "status": "Vessel arrival",
                                    "status_code": "VAD",
                                    "date": "2026-10-12T08:00:00",
                                    "actual": false,
                                    "vessel": "EXAMPLE VESSEL",
                                    "voyage": "126E"
                                },
                                {
                                    "location": 0,
                                    "terminal": null,
                                    "status": "Loaded",
                                    "status_code": "CLL",
                                    "date": "2026-10-01T12:00:00",
                                    "actual": true,
                                    "vessel": "EXAMPLE VESSEL",
                                    "voyage": "126E"
                                }
                            ]
                        }
                    ],
                    "route_info": null,
                    "shipment_status": "IN_TRANSIT",
                    "references": {
                        "booking_numbers": ["BOOKING123"],
                        "bill_of_lading_numbers": ["MEDU1234567"]
                    },
                    "tracking_metadata": {
                        "id": "11111111-1111-4111-8111-111111111111",
                        "end_date": null,
                        "status": "ACTIVE",
                        "note": null,
                        "created_at": "2026-10-03T09:00:00.000Z",
                        "updated_at": "2026-10-03T09:00:00.000Z"
                    }
                }
            }
        ]
    }
}

Статусы задачи: CREATED — ожидает обработки, HANDLING — обрабатывается, PROCESSED — обработка завершена. После PROCESSED проверяйте success и status каждого элемента data.results[]. Завершение задачи не означает, что данные найдены по всем номерам.

Связывайте результат с исходным номером через results[].request.track_number. Сохраняйте постоянный results[].data.tracking_metadata.id, если data и tracking_metadata не равны null. Результаты хранятся до 6 часов. Сохраните их после завершения задачи; пример опроса с ограничением повторов — в пакетном отслеживании.

5. Обновите обработку ответаСкопировать ссылку на раздел

В GET /v2/tracking данные перевозки находятся в data. В GET /v2/shipments сначала выберите запись из data.data[], затем получите её данные по путям из третьего столбца.

Проверяйте статусы по отдельности:

• success и status сообщают результат API-запроса. В списке также проверьте tracked_item.data.success и tracked_item.data.status каждой записи.
• data.status пакетной задачи сообщает, завершена ли её обработка.
• ACTIVE и ARCHIVED относятся к подписке на отслеживание.
• shipment_status описывает состояние перевозки: например, IN_TRANSIT или DELIVERED.

Для событий используйте status_code, date и actual. При наличии всех дат события идут от новых к старым; если дата отсутствует, сохраняется порядок перевозчика. Не сопоставляйте события разных сервисов по индексу массива.

Например, CLL означает погрузку в порту отправления, CLT — погрузку при перегрузке. По event.location найдите объект с соответствующим id в locations, по event.terminal — в terminals. actual=true означает произошедшее событие, false — ожидаемое. Если значение равно null, сведений недостаточно. Дату без часового пояса нельзя автоматически считать UTC.

Маршрут запрашивается через need_route=true. Если информации о перевозке недостаточно для его построения, route_info может быть null. Координаты в route_info имеют порядок [широта, долгота]. Для GeoJSON поменяйте его на [долгота, широта].

Пустой результат не означает доставку. Разделяйте отсутствие данных, ошибки перевозчика и завершённую перевозку. Повторные запросы и HTTP 429 обрабатывайте по руководству по ошибкам, учитывая Retry-After, если он передан.

6. Проверьте переход на небольшой выборкеСкопировать ссылку на раздел

1. Выгрузите номера, типы, перевозчиков и связи исходных ID. Для проверки можно использовать пробный период Cargotime. При запуске учитывайте правила расходования доступных отслеживаний.
2. Проверьте контейнер, коносамент или букинг с несколькими контейнерами, отсутствие данных и завершённую перевозку.
3. Сравните ответы по примерам из руководства сервиса. Проверьте пути к полям, коды событий, плановые и фактические даты, координаты. Прогнозы разных сервисов могут отличаться.
4. Проверьте переход между страницами, ошибки отдельных номеров в пакетной задаче, отсутствие маршрута и повторную доставку уведомлений.
5. Переключите получение данных и уведомлений на Cargotime. Сохраните таблицу соответствий ID и возможность возврата к прежней интеграции. После проверки остановите прежние подписки: Cargotime не отменяет их автоматически.