История изменений API
Изменения в v2 и переход с v1
2.1
Текущая версия API. Операции, параметры и форматы ответов описаны в справочнике API.
2.0
Первое крупное обновление API после v1. В этой версии переработаны запросы на отслеживание и управление записями, добавлены отслеживание по документам и вебхуки.
| Изменение | Что появилось в v2 |
|---|---|
| Эндпоинты и методы | Запросы перенесены в /v2/tracking, /v2/tracking/batch и /v2/shipments. Для удаления используется DELETE. Полное соответствие приведено в таблице миграции ниже. |
| Отслеживание по документам | Помимо номера контейнера поддерживаются номера коносаментов (bl) и букингов (bk). |
| Параметры запроса | Вместо container_number передаются value и type. Например, container_number=MSDU8368827 заменяется на value=MSDU8368827&type=container. |
| Пакетные запросы | Массив tracked_items содержит объекты с company и track_number: { value, type }. В одной задаче можно передать до 500 номеров разных типов. |
| Формат ответа | Данные контейнеров приведены к единому массиву data.containers. Добавлены связанные номера в data.references, сведения об отслеживании в data.tracking_metadata и исходные параметры в request. |
| Управление отслеживаниями | Список возвращается по страницам. Поддерживаются заметки, архивирование и удаление записей. |
| Поддерживаемые компании | GET /v2/companies возвращает SCAC-коды перевозчиков и поддерживаемые типы отслеживания. |
| Вебхуки | Можно получать события отслеживания по мере появления обновлений. Подробнее — в разделе «Вебхуки». |
API-ключ по-прежнему передаётся в параметре api_key. Формат ответа включает success, status, status_description и data, когда эти поля предусмотрены операцией.
Миграция с v1
Не переключайте рабочую интеграцию на v2 без проверки ответов и обработки ошибок. Миграцию можно выполнить поэтапно.
| v1 | v2 |
|---|---|
GET /v1/container | GET /v2/tracking |
POST /v1/containers | POST /v2/tracking/batch |
GET /v1/containers | GET /v2/tracking/batch |
GET /v1/apikey | GET /v2/apikey |
GET /v1/subscriptions/get | GET /v2/shipments |
POST /v1/subscriptions/remove | DELETE /v2/shipments |
| нет | GET /v2/companies |
| нет | вебхуки: /v2/webhooks, /v2/webhook-event-types, /v2/webhook-notifications |
Замените container_number на value и передайте обязательный type: container, bl или bk.
GET /v1/container?api_key=YOUR_TOKEN&company=AUTO&container_number=MSDU8368827
GET /v2/tracking?api_key=YOUR_TOKEN&company=AUTO&value=MSDU8368827&type=containerДля коносаментов и букингов укажите SCAC-код перевозчика. Поддержку нужного типа номера проверьте через GET /v2/companies.
Обработка выполняется асинхронно: API возвращает идентификатор задачи, не дожидаясь результатов отслеживания. Получите task_id в ответе на POST /v2/tracking/batch, затем запросите результаты через GET /v2/tracking/batch. Данные задачи хранятся в кэше до 6 часов.
Замените массив containers на tracked_items, а поле container_number — на объект track_number с полями value и type. В одном запросе можно передать от 1 до 500 номеров разных типов.
{
"tracked_items": [
{
"company": "AUTO",
"track_number": { "value": "MSDU8368827", "type": "container" }
},
{
"company": "COSU",
"track_number": { "value": "ABCD1234567890", "type": "bl" }
}
]
}В v1 данные контейнера возвращались в data.container. В v2 используется массив data.containers, в том числе для одного контейнера. Перед обращением к первому элементу проверьте, что массив не пуст.
Также появились:
data.references— связанные номера;request— исходные параметрыtrack_numberиcompany;data.tracking_metadata— может бытьnullдо создания отслеживания.
Проверяйте HTTP-статус, success и status: например, INFO_NOT_FOUND означает отсутствие данных. Подробнее — в разделе «Ошибки и результаты запросов».
GET /v1/subscriptions/get возвращал весь список. GET /v2/shipments возвращает его по страницам: передайте page, limit (до 500) и при необходимости status. Отслеживания находятся в data.data, сведения о страницах — в data.meta, ссылки — в data.links.
Удаление: POST /v1/subscriptions/remove с subscriptionIds → DELETE /v2/shipments с shipmentIds.
Условия удаления и возврата на баланс зависят от времени создания отслеживания и статуса перевозки. Проверьте их в примере управления отслеживаниями и операции удаления.
Вебхуки появились в v2. Создайте подписку, сохраните secret для проверки подписи и принимайте события на callback_url. Чтобы не обрабатывать события повторно, используйте x-cargotime-event-id. См. Вебхуки.
v1
v1 — только для существующих интеграций. Документация: Swagger UI.
Поддерживаются только контейнеры: GET /v1/container, batch POST/GET /v1/containers, GET /v1/apikey, GET /v1/subscriptions/get / POST /v1/subscriptions/remove. Для новой разработки используйте v2.
Обновлено