Справочник API
Скачать OpenAPIВозвращает поддерживаемых перевозчиков, их SCAC-коды и типы отслеживания. В поле data ключ — название компании, значение — объект с полями scac, cn, bl, bk. Передавайте scac в параметре company. Флаги со значением true обозначают поддержку контейнеров, коносаментов и букингов соответственно.
Авторизация
api_key Передаётся в: query
Тело ответа
application/json
curl -X GET "https://example.com/v2/companies"{ "success": true, "data": { "Akkon Lines": { "scac": "AKKU", "cn": false, "bl": true, "bk": true }, "Aliança Navegação e Logística Ltda.": { "scac": "ANRM", "cn": true, "bl": true, "bk": true }, "American President Lines": { "scac": "APLU", "cn": true, "bl": true, "bk": true }, "Arkas Container Transport S.A.": { "scac": "ARKU", "cn": true, "bl": true, "bk": true } }}Возвращает состояние задачи из POST /v2/tracking/batch. В data.status: CREATED — ожидает обработки, HANDLING — выполняется, PROCESSED — завершена. После завершения получите data.results и прекратите запросы состояния этой задачи. Для последующих изменений перевозки используйте запросы на отслеживание или вебхуки. Данные задачи хранятся в кэше до 6 часов.
Авторизация
api_key Передаётся в: query
Параметры запроса
Уникальный идентификатор задачи трекинга. Получается при создании запроса через POST /v2/tracking/batch
uuidТело ответа
application/json
curl -X GET "https://example.com/v2/tracking/batch?task_id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"{ "success": true, "data": { "task_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "status": "PROCESSED", "results": [ { "success": true, "data": { "summary": { "origin": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pol": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pod": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "destination": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "company": { "name": "MSC", "full_name": "Mediterranean Shipping Company (MSC)", "url": "https://www.msc.com/", "scacs": [ "MEDU", "MSCU" ] } }, "locations": [ { "id": 0, "name": "Gothenburg", "state": "Halland", "terminal": "Port of Gothenburg", "country": "Sweden", "lat": 57.70887, "lng": 11.97456 } ], "terminals": [ { "id": 0, "name": "Port of Gothenburg" } ], "containers": [ { "number": "TCKU7858986", "type": "40' Dry", "events": [ { "location": 0, "terminal": 0, "status": "On Board", "status_code": "CLL", "date": "2023-10-25T11:11:11", "actual": false, "vessel": "Evergreen Teresa", "voyage": "V. 284" } ] } ], "route_info": { "route": [ { "path": [ [ 48.698306, 14.042056 ], [ 45.039944, 12.751222 ], [ 43.463278, 12.6745 ], [ 32.566855, 29.927166 ], [ 32.284501, 31.232806 ] ], "type": "sea" } ], "current_position": [ 32.284501, 31.232806 ], "last_updated": "2023-10-25T11:11:11", "course": "247.34" }, "shipment_status": "IN_TRANSIT", "references": { "booking_numbers": [ "2315887441" ], "bill_of_lading_numbers": [ "MEDUH1234567" ] }, "tracking_metadata": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "end_date": "2025-06-29T14:12:00.000Z", "status": "ACTIVE", "note": "Order 4521", "created_at": "2025-06-29T14:12:00.000Z", "updated_at": "2025-06-30T06:00:00.000Z" } }, "status": "OK", "status_description": "Информация найдена", "request": { "track_number": { "type": "container", "value": "TCKU7858986" }, "company": "MEDU" } } ] }, "status": "OK"}Создаёт задачу для отслеживания от 1 до 500 номеров. Обработка выполняется асинхронно. API возвращает task_id, не дожидаясь результатов отслеживания. Через некоторое время передайте его в GET /v2/tracking/batch, чтобы получить состояние и результаты. Данные задачи хранятся в кэше до 6 часов.
Авторизация
api_key Передаётся в: query
Параметры запроса
Нужен ли маршрут перевозки
falseТело запроса
application/json
Типы TypeScript
Используйте тип request body в TypeScript.
Тело ответа
application/json
curl -X POST "https://example.com/v2/tracking/batch?need_route=false" \ -H "Content-Type: application/json" \ -d '{ "tracked_items": [ { "company": "COSU", "track_number": { "value": "CSNU6184414", "type": "container" } }, { "company": "AKKU", "track_number": { "value": "AKKNEM25072638", "type": "bl" } } ] }'{ "success": true, "data": { "task_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "status": "OK"}Авторизация
api_key Передаётся в: query
Параметры запроса
SCAC-код перевозчика. Значение AUTO доступно только для type=container. Коды и поддерживаемые типы можно получить через GET /v2/companies.
Тип номера для трекинга. Контейнер - container, коносамент - bl, букинг - bk.
Значение из
- "container"
- "bl"
- "bk"
Значение номера для трекинга.
Обновлять ли информацию принудительно
falseНужен ли маршрут перевозки
falseТело ответа
application/json
curl -X GET "https://example.com/v2/tracking?company=AUTO&type=container&value=CSNU6184414&force_update=false&need_route=false"{ "success": true, "data": { "summary": { "origin": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pol": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pod": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "destination": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "company": { "name": "MSC", "full_name": "Mediterranean Shipping Company (MSC)", "url": "https://www.msc.com/", "scacs": [ "MEDU", "MSCU" ] } }, "locations": [ { "id": 0, "name": "Gothenburg", "state": "Halland", "terminal": "Port of Gothenburg", "country": "Sweden", "lat": 57.70887, "lng": 11.97456 } ], "terminals": [ { "id": 0, "name": "Port of Gothenburg" } ], "containers": [ { "number": "TCKU7858986", "type": "40' Dry", "events": [ { "location": 0, "terminal": 0, "status": "On Board", "status_code": "CLL", "date": "2023-10-25T11:11:11", "actual": false, "vessel": "Evergreen Teresa", "voyage": "V. 284" } ] } ], "route_info": { "route": [ { "path": [ [ 48.698306, 14.042056 ], [ 45.039944, 12.751222 ], [ 43.463278, 12.6745 ], [ 32.566855, 29.927166 ], [ 32.284501, 31.232806 ] ], "type": "sea" } ], "current_position": [ 32.284501, 31.232806 ], "last_updated": "2023-10-25T11:11:11", "course": "247.34" }, "shipment_status": "IN_TRANSIT", "references": { "booking_numbers": [ "2315887441" ], "bill_of_lading_numbers": [ "MEDUH1234567" ] }, "tracking_metadata": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "end_date": "2025-06-29T14:12:00.000Z", "status": "ACTIVE", "note": "Order 4521", "created_at": "2025-06-29T14:12:00.000Z", "updated_at": "2025-06-30T06:00:00.000Z" } }, "status": "OK", "status_description": "Information found", "request": { "track_number": { "type": "container", "value": "TCKU7858986" }, "company": "MEDU" }}Пример запроса: https://tracking.cargotime.ru/v2/shipments?api_key=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&page=1&limit=50&status=ACTIVE
Авторизация
api_key Передаётся в: query
Параметры запроса
Нужен ли маршрут перевозки
falseНомер страницы
1 <= value <= 1000000001Количество отслеживаний на странице
1 <= value <= 50050Фильтр по статусу отслеживания. Доступные значения: ACTIVE, ARCHIVED
Значение из
- "ACTIVE"
- "ARCHIVED"
Тело ответа
application/json
curl -X GET "https://example.com/v2/shipments?need_route=false&page=1&limit=50&status=ACTIVE"{ "success": true, "data": { "data": [ { "id": "d8976b45-e3e6-4115-b723-57f9b95fc76b", "tracked_item": { "track_number": "MSCU1234567", "track_number_type": "container", "company_id": 60, "data": { "success": true, "data": { "summary": { "origin": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pol": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pod": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "destination": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "company": { "name": "MSC", "full_name": "Mediterranean Shipping Company (MSC)", "url": "https://www.msc.com/", "scacs": [ "MEDU", "MSCU" ] } }, "locations": [ { "id": 0, "name": "Gothenburg", "state": "Halland", "terminal": "Port of Gothenburg", "country": "Sweden", "lat": 57.70887, "lng": 11.97456 } ], "terminals": [ { "id": 0, "name": "Port of Gothenburg" } ], "containers": [ { "number": "TCKU7858986", "type": "40' Dry", "events": [ { "location": 0, "terminal": 0, "status": "On Board", "status_code": "CLL", "date": "2023-10-25T11:11:11", "actual": false, "vessel": "Evergreen Teresa", "voyage": "V. 284" } ] } ], "route_info": { "route": [ { "path": [ [ 48.698306, 14.042056 ], [ 45.039944, 12.751222 ], [ 43.463278, 12.6745 ], [ 32.566855, 29.927166 ], [ 32.284501, 31.232806 ] ], "type": "sea" } ], "current_position": [ 32.284501, 31.232806 ], "last_updated": "2023-10-25T11:11:11", "course": "247.34" }, "shipment_status": "IN_TRANSIT", "references": { "booking_numbers": [ "2315887441" ], "bill_of_lading_numbers": [ "MEDUH1234567" ] } }, "status": "OK", "status_description": "Информация найдена" }, "updated_at": "2026-04-08T12:08:55.307Z", "checked_at": "2026-04-08T12:08:55.307Z", "company_name": "Mediterranean Shipping Company" }, "start_date": "2026-04-08T12:26:56.940Z", "end_date": "2026-04-12T09:18:49.395Z", "status": "ACTIVE", "note": "Order 4521", "created_at": "2026-04-08T12:08:54.569Z", "track_number": "MSCU1234567" } ], "meta": { "itemsPerPage": 50, "totalItems": 145, "currentPage": 2, "totalPages": 3, "sortBy": [ [ "created_at", "DESC" ], [ "id", "DESC" ] ], "filter": { "status": "$eq:ACTIVE" } }, "links": { "first": "/v2/shipments?page=1&limit=50&status=ACTIVE", "previous": "/v2/shipments?page=1&limit=50&status=ACTIVE", "current": "/v2/shipments?page=2&limit=50&status=ACTIVE", "next": "/v2/shipments?page=3&limit=50&status=ACTIVE", "last": "/v2/shipments?page=3&limit=50&status=ACTIVE" } }, "status": "OK", "status_description": "Информация найдена"}Если неархивное отслеживание создано не более 72 часов назад и shipment_status отличается от IN_TRANSIT (в том числе DELIVERED, UNKNOWN или STUCK), запись удаляется с возвратом одного отслеживания на баланс. Записи со статусом IN_TRANSIT и неархивные записи старше 72 часов архивируются без возврата. Уже архивные записи удаляются без возврата. В data.deleted возвращаются идентификаторы удалённых записей, в data.archived — архивированных.
Авторизация
api_key Передаётся в: query
Тело запроса
application/json
Типы TypeScript
Используйте тип request body в TypeScript.
Тело ответа
application/json
curl -X DELETE "https://example.com/v2/shipments" \ -H "Content-Type: application/json" \ -d '{ "shipmentIds": [ "9ff48bf7-4541-49e2-947c-c269200e030f", "fb8936b9-ff16-4776-8710-d4073ab06d1e", "2305a40b-97b2-4c1b-94c4-6d9416b22bde" ] }'{ "success": true, "data": { "deleted": [ "9ff48bf7-4541-49e2-947c-c269200e030f", "fb8936b9-ff16-4776-8710-d4073ab06d1e" ], "archived": [ "2305a40b-97b2-4c1b-94c4-6d9416b22bde" ] }, "status": "OK", "status_description": "Отслеживания успешно удалены"}Обновляет заметку отслеживания, в том числе архивного. Чтобы удалить заметку, отправьте в теле пустую строку { "note": "" }. Максимальная длина — 40 символов. Другие поля тела отклоняются.
Авторизация
api_key Передаётся в: query
Параметры пути
Идентификатор отслеживания
uuidТело запроса
application/json
Типы TypeScript
Используйте тип request body в TypeScript.
Тело ответа
application/json
curl -X PATCH "https://example.com/v2/shipments/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \ -H "Content-Type: application/json" \ -d '{ "note": "string" }'{ "success": true, "status": "OK", "status_description": "Информация найдена", "data": { "id": "d8976b45-e3e6-4115-b723-57f9b95fc76b", "tracked_item": { "track_number": "MSCU1234567", "track_number_type": "container", "company_id": 60, "data": { "success": true, "data": { "summary": { "origin": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pol": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pod": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "destination": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "company": { "name": "MSC", "full_name": "Mediterranean Shipping Company (MSC)", "url": "https://www.msc.com/", "scacs": [ "MEDU", "MSCU" ] } }, "locations": [ { "id": 0, "name": "Gothenburg", "state": "Halland", "terminal": "Port of Gothenburg", "country": "Sweden", "lat": 57.70887, "lng": 11.97456 } ], "terminals": [ { "id": 0, "name": "Port of Gothenburg" } ], "containers": [ { "number": "TCKU7858986", "type": "40' Dry", "events": [ { "location": 0, "terminal": 0, "status": "On Board", "status_code": "CLL", "date": "2023-10-25T11:11:11", "actual": false, "vessel": "Evergreen Teresa", "voyage": "V. 284" } ] } ], "route_info": { "route": [ { "path": [ [ 48.698306, 14.042056 ], [ 45.039944, 12.751222 ], [ 43.463278, 12.6745 ], [ 32.566855, 29.927166 ], [ 32.284501, 31.232806 ] ], "type": "sea" } ], "current_position": [ 32.284501, 31.232806 ], "last_updated": "2023-10-25T11:11:11", "course": "247.34" }, "shipment_status": "IN_TRANSIT", "references": { "booking_numbers": [ "2315887441" ], "bill_of_lading_numbers": [ "MEDUH1234567" ] } }, "status": "OK", "status_description": "Информация найдена" }, "updated_at": "2026-04-08T12:08:55.307Z", "checked_at": "2026-04-08T12:08:55.307Z", "company_name": "Mediterranean Shipping Company" }, "start_date": "2026-04-08T12:26:56.940Z", "end_date": "2026-04-12T09:18:49.395Z", "status": "ACTIVE", "note": "Order 4521", "created_at": "2026-04-08T12:08:54.569Z", "track_number": "MSCU1234567" }}Авторизация
api_key Передаётся в: query
Параметры запроса
API-ключ (передайте api_key или value)
uuidУстаревший алиас api_key (передайте api_key или value)
uuidТело ответа
application/json
curl -X GET "https://example.com/v2/apikey?api_key=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&value=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"{ "success": true, "data": { "creation_date": "2023-03-23T21:49:43.000Z", "api_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "requests_remaining_count": 45 }}curl -X GET "https://example.com/v2/webhook-event-types"{ "success": true, "data": [ { "type": "tracking.eta_update", "group": "tracking", "description": "Расчётная дата прибытия изменилась" }, { "type": "tracking.history_update", "group": "tracking", "description": "В историю отслеживания добавлено событие" }, { "type": "tracking.info_found", "group": "tracking", "description": "Данные отслеживания найдены" }, { "type": "tracking.info_not_found", "group": "tracking", "description": "Данные отслеживания не найдены" }, { "type": "tracking.auto_archiving", "group": "tracking", "description": "Подписки автоматически перенесены в архив" }, { "type": "tracking.delivered", "group": "tracking", "description": "Груз доставлен" } ], "status": "OK", "status_description": "Запрос выполнен успешно"}Возвращает историю доставок вебхуков на ваши callback_url.
По умолчанию в ответ попадают только неуспешные доставки. Чтобы выбрать другой статус, передайте status=pending или status=delivered. Параметр webhook_id ограничивает результаты одним вебхуком.
Результаты разбиты на страницы. В data ответа — объект с полями data, meta и links.
Авторизация
api_key Передаётся в: query
Параметры запроса
Статус доставки. По умолчанию — failed.
"failed"Значение из
- "pending"
- "delivered"
- "failed"
Идентификатор вебхука, по которому нужно отфильтровать доставки
uuidНомер страницы
1 <= value <= 1000000001Количество доставок на странице
1 <= value <= 10050Тело ответа
application/json
curl -X GET "https://example.com/v2/webhook-notifications?status=failed&webhook_id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&page=1&limit=50"{ "success": true, "data": { "data": [ { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "webhook_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "event_type": "tracking.delivered", "payload": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.delivered", "api_version": "2026-07-09", "created_at": "2026-07-08T13:11:22.758Z", "resource": { "tracked_item_id": "eeeeeeee-ffff-aaaa-bbbb-cccccccccccc", "track_number": { "type": "container", "value": "MSBU6501445" }, "company": "Mediterranean Shipping Company", "company_scac": "MSCU" }, "data": { "shipment_status": "DELIVERED", "route": { "origin": "Ho Chi Minh City, VN", "pol": "Wilmington, US", "pod": "Long Beach, US", "destination": "Dallas, US" }, "final_location": "DALLAS, US", "current_position": null, "event": { "location": "DALLAS, US", "status": "Delivered", "status_code": "CDC", "date": "2026-07-07T00:00:00", "actual": true, "vessel": null, "voyage": null } }, "changes": [] }, "status": "delivered", "attempt_count": 1, "next_attempt_at": null, "delivered_at": "2026-07-08T13:16:38.565Z", "created_at": "2026-07-08T13:16:38.371Z", "webhook": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/cargotime", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "created_at": "2026-07-08T09:39:36.311Z", "updated_at": "2026-07-08T13:10:43.554Z" }, "attempts": [ { "id": "dddddddd-eeee-ffff-aaaa-bbbbbbbbbbbb", "notification_id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "attempt_number": 1, "http_status": 200, "error_message": null, "attempted_at": "2026-07-08T13:16:38.396Z" } ] } ], "meta": { "itemsPerPage": 50, "totalItems": 1, "currentPage": 1, "totalPages": 1, "sortBy": [ [ "created_at", "DESC" ], [ "id", "DESC" ] ], "searchBy": [], "search": "", "select": [] }, "links": { "first": "/v2/webhook-notifications?page=1&limit=50&status=failed", "previous": null, "current": "/v2/webhook-notifications?page=1&limit=50&status=failed", "next": null, "last": "/v2/webhook-notifications?page=1&limit=50&status=failed" } }, "status": "OK", "status_description": "Запрос выполнен успешно"}curl -X GET "https://example.com/v2/webhooks"{ "success": true, "data": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/cargotime", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "created_at": "2026-07-08T09:39:36.311Z", "updated_at": "2026-07-08T13:10:43.554Z" } ], "status": "OK", "status_description": "Запрос выполнен успешно"}Создаёт вебхук для вашего аккаунта.
В ответе вы получите secret для проверки подписи (22 символа из алфавита base64url: A–Z, a–z, 0–9, -, _). Секрет показывается только в этом ответе и не возвращается при последующем чтении вебхука, поэтому сразу сохраните его в безопасном месте.
При каждой доставке Cargotime отправляет POST-запрос на ваш callback_url. Запрос содержит JSON-объект WebhookOutgoingPayload и заголовки:
x-cargotime-signature— HMAC SHA-256-подпись строкиtimestamp + '.' + rawBodyс префиксомsha256=;x-cargotime-timestamp— метка времени Unix, использованная для подписи;x-cargotime-event-id— уникальный идентификатор события, совпадающий сpayload.id;x-cargotime-delivery-id— уникальный идентификатор попытки доставки.
Авторизация
api_key Передаётся в: query
Тело запроса
application/json
Типы TypeScript
Используйте тип request body в TypeScript.
Тело ответа
application/json
curl -X POST "https://example.com/v2/webhooks" \ -H "Content-Type: application/json" \ -d '{ "callback_url": "https://example.com/webhooks/cargotime", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ] }'{ "success": true, "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/cargotime", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "created_at": "2026-07-08T09:39:36.311Z", "updated_at": "2026-07-08T13:10:43.554Z", "secret": "AaBbCcDdEe-_0123456789" }, "status": "OK", "status_description": "Запрос выполнен успешно"}Авторизация
api_key Передаётся в: query
Параметры пути
ID вебхука
uuidТело ответа
application/json
curl -X GET "https://example.com/v2/webhooks/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"{ "success": true, "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/cargotime", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "created_at": "2026-07-08T09:39:36.311Z", "updated_at": "2026-07-08T13:10:43.554Z" }, "status": "OK", "status_description": "Запрос выполнен успешно"}Изменяет callback_url, статус вебхука и список событий. При regenerate_secret=true ответ содержит новый secret. Он показывается только в этом ответе и не возвращается при последующем чтении вебхука.
Авторизация
api_key Передаётся в: query
Параметры пути
ID вебхука
uuidТело запроса
application/json
Типы TypeScript
Используйте тип request body в TypeScript.
Тело ответа
application/json
curl -X PATCH "https://example.com/v2/webhooks/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \ -H "Content-Type: application/json" \ -d '{ "is_active": true, "regenerate_secret": false, "event_types": [ "tracking.eta_update", "tracking.history_update" ] }'{ "success": true, "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/cargotime", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "created_at": "2026-07-08T09:39:36.311Z", "updated_at": "2026-07-08T13:10:43.554Z" }, "status": "OK", "status_description": "Запрос выполнен успешно"}Авторизация
api_key Передаётся в: query
Параметры пути
ID вебхука
uuidТело ответа
application/json
curl -X DELETE "https://example.com/v2/webhooks/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"{ "success": true, "data": null, "status": "OK", "status_description": "Запрос выполнен успешно"}Отправляет тестовое событие tracking.test на ваш callback_url.
Авторизация
api_key Передаётся в: query
Параметры пути
ID вебхука
uuidТело ответа
application/json
curl -X POST "https://example.com/v2/webhooks/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/test"{ "success": true, "data": { "success": true, "http_status": 200 }, "status": "OK", "status_description": "Запрос выполнен успешно"}{ "success": true, "data": { "success": false, "http_status": 500, "error_message": "fetch failed" }, "status": "OK", "status_description": "Запрос выполнен успешно"}Когда происходит событие отслеживания, на которое вы подписаны, Cargotime отправляет POST-запрос на ваш callback_url.
После получения события как можно скорее верните 200 OK. Если обработка занимает время, сначала поставьте событие в очередь, отправьте ответ, а затем обработайте его асинхронно. Cargotime ждёт ответ 10 секунд.
Доставка считается успешной при любом статусе 2xx. Cargotime повторяет доставку после статусов 408, 409, 425, 429 и 5xx, а также при таймаутах и ошибках DNS или сети. После статусов 400, 401, 403, 404 и 422 повторной попытки не будет. При статусе 429 Cargotime учитывает заголовок Retry-After, если он передан. Всего может быть не более пяти попыток.
Чтобы проверить источник запроса, используйте секрет вебхука и заголовки x-cargotime-timestamp и x-cargotime-signature. Значение подписи — HMAC SHA-256 от строки timestamp + '.' + rawBody с префиксом sha256=. В rawBody должно попасть исходное тело запроса без изменений. Проверять подпись необязательно, но мы рекомендуем это делать.
Node.js / Express
import crypto from 'node:crypto';import express from 'express';const app = express();const secret = process.env.CARGOTIME_WEBHOOK_SECRET;if (!secret) { throw new Error('CARGOTIME_WEBHOOK_SECRET is not set');}function queueWebhook(payload: unknown): void { // Здесь можно поставить событие в очередь, // сохранить его в базе данных или передать внутреннему сервису. console.log('Cargotime прислал вебхук:', payload);}app.post('/webhooks/cargotime', express.raw({ type: 'application/json' }), (req, res) => { const timestamp = req.header('x-cargotime-timestamp'); const signature = req.header('x-cargotime-signature'); if (!timestamp || !signature) { return res.sendStatus(401); } const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(timestamp).update('.').update(req.body).digest('hex'); const signatureBuffer = Buffer.from(signature); const expectedBuffer = Buffer.from(expected); if (signatureBuffer.length !== expectedBuffer.length || !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) { return res.sendStatus(401); } const payload = JSON.parse(req.body.toString('utf8')); queueWebhook(payload); return res.sendStatus(200);});app.listen(3000, () => { console.log('Сервер вебхуков запущен на порту 3000');});Python / FastAPI
import hmacimport hashlibimport osfrom fastapi import FastAPI, Request, HTTPExceptionapp = FastAPI()secret = os.environ["CARGOTIME_WEBHOOK_SECRET"].encode()def enqueue_webhook(payload: dict) -> None: # Здесь можно поставить событие в очередь, # сохранить его в базе данных или передать внутреннему сервису. print("Cargotime прислал вебхук:", payload)@app.post("/webhooks/cargotime")async def cargotime_webhook(request: Request): body = await request.body() timestamp = request.headers.get("x-cargotime-timestamp") signature = request.headers.get("x-cargotime-signature") if not timestamp or not signature: raise HTTPException(status_code=401) digest = hmac.new( secret, timestamp.encode() + b"." + body, hashlib.sha256, ).hexdigest() expected = f"sha256={digest}" if not hmac.compare_digest(signature, expected): raise HTTPException(status_code=401) payload = await request.json() enqueue_webhook(payload) return {"ok": True}Параметры заголовков
HMAC SHA-256-подпись строки timestamp + '.' + rawBody с префиксом sha256=. Для rawBody используйте исходное тело запроса без изменений.
Метка времени Unix, использованная для подписи
Уникальный идентификатор события, совпадающий с payload.id
uuidУникальный идентификатор попытки доставки
uuidТело запроса
application/json
Типы TypeScript
Используйте тип request body в TypeScript.
Тело ответа
Примеры запросов
/trackingWebhookDeliveryИстория изменений API
Изменения в v2 и переход с v1
Список поддерживаемых перевозчиков GET
Возвращает поддерживаемых перевозчиков, их SCAC-коды и типы отслеживания. В поле `data` ключ — название компании, значение — объект с полями `scac`, `cn`, `bl`, `bk`. Передавайте `scac` в параметре `company`. Флаги со значением `true` обозначают поддержку контейнеров, коносаментов и букингов соответственно.