{ "openapi": "3.1.2", "paths": { "/v2/companies": { "get": { "description": "Возвращает поддерживаемых перевозчиков, их SCAC-коды и типы отслеживания. В поле `data` ключ — название компании, значение — объект с полями `scac`, `cn`, `bl`, `bk`. Передавайте `scac` в параметре `company`. Флаги со значением `true` обозначают поддержку контейнеров, коносаментов и букингов соответственно.", "operationId": "CompaniesV2Controller_getCompaniesList_v2", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "type": "object", "description": "Ключ — полное название компании, значение — SCAC и флаги поддерживаемых типов отслеживания.", "additionalProperties": { "$ref": "#/components/schemas/CompanyTrackingCapabilitiesDto" }, "example": { "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 } } } } }, "example": { "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 } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Список поддерживаемых перевозчиков", "tags": [ "companies" ] } }, "/v2/tracking/batch": { "post": { "description": "Создаёт задачу для отслеживания от 1 до 500 номеров. Обработка выполняется асинхронно. API возвращает `task_id`, не дожидаясь результатов отслеживания. Через некоторое время передайте его в `GET /v2/tracking/batch`, чтобы получить состояние и результаты. Данные задачи хранятся в кэше до 6 часов.", "operationId": "MultipleTrackingPublicV2Controller_multipleContainerTracking_v2", "parameters": [ { "name": "need_route", "required": false, "in": "query", "description": "Нужен ли маршрут перевозки", "schema": { "default": false, "example": false, "type": "boolean" }, "example": false } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackMultipleItemsRequestDto" }, "example": { "tracked_items": [ { "company": "COSU", "track_number": { "value": "CSNU6184414", "type": "container" } }, { "company": "AKKU", "track_number": { "value": "AKKNEM25072638", "type": "bl" } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackMultipleItemsResponseDto" }, "example": { "success": true, "data": { "task_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "status": "OK" } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Создание задачи пакетного отслеживания", "tags": [ "tracking-batch" ] }, "get": { "description": "Возвращает состояние задачи из `POST /v2/tracking/batch`. В `data.status`: `CREATED` — ожидает обработки, `HANDLING` — выполняется, `PROCESSED` — завершена. После завершения получите `data.results` и прекратите запросы состояния этой задачи. Для последующих изменений перевозки используйте запросы на отслеживание или вебхуки. Данные задачи хранятся в кэше до 6 часов.", "operationId": "MultipleTrackingPublicV2Controller_getContainerTrackingStatus_v2", "parameters": [ { "name": "task_id", "required": true, "in": "query", "description": "Уникальный идентификатор задачи трекинга. Получается при создании запроса через POST /v2/tracking/batch", "schema": { "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "string" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingStatusResponseDto" }, "example": { "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" } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Статус и результаты пакетного отслеживания", "tags": [ "tracking-batch" ] } }, "/v2/tracking": { "get": { "description": "Пример запроса: https://tracking.cargotime.ru/v2/tracking?api_key=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&company=COSU&value=CSNU6184414&type=container&force_update=false", "operationId": "SingleTrackingPublicV2Controller_singleContainerTracking_v2", "parameters": [ { "name": "company", "required": true, "in": "query", "examples": { "AUTO": { "value": "AUTO", "summary": "Автоматическое определение линии" }, "VSKH": { "value": "VSKH", "summary": "Восход" }, "TSJL": { "value": "TSJL", "summary": "ТрансКонтейнер" }, "AKKU": { "value": "AKKU", "summary": "Akkon Lines" }, "ANRM": { "value": "ANRM", "summary": "Aliança Navegação e Logística Ltda." }, "APLU": { "value": "APLU", "summary": "American President Lines" }, "ARKU": { "value": "ARKU", "summary": "Arkas Container Transport S.A." }, "ACLU": { "value": "ACLU", "summary": "Atlantic Container Line" }, "ANNU": { "value": "ANNU", "summary": "Australia National Line" }, "BLJU": { "value": "BLJU", "summary": "Avana Logistek" }, "BLZU": { "value": "BLZU", "summary": "BLPL Singapore Pte Ltd" }, "BANQ": { "value": "BANQ", "summary": "Blue Anchor Line Ltd." }, "BWLU": { "value": "BWLU", "summary": "Blue Water Lines Pte Ltd" }, "BMSU": { "value": "BMSU", "summary": "BMC Lines Shipping" }, "11DX": { "value": "11DX", "summary": "Cheng Lie Navigation Company" }, "COSU": { "value": "COSU", "summary": "China Ocean Shipping Group Company" }, "CULU": { "value": "CULU", "summary": "China United Lines" }, "CKLU": { "value": "CKLU", "summary": "CK Line" }, "CMDU": { "value": "CMDU", "summary": "CMA CGM" }, "CXNU": { "value": "CXNU", "summary": "Container Corporation of India Ltd" }, "CSYU": { "value": "CSYU", "summary": "Cordelia Container Shipping Line" }, "CAMN": { "value": "CAMN", "summary": "Crowley Maritime Corporation" }, "DMCQ": { "value": "DMCQ", "summary": "Damco Marine Management, Inc." }, "DWCH": { "value": "DWCH", "summary": "De Well Container Shipping" }, "11PG": { "value": "11PG", "summary": "Dongjin Shipping Co., Ltd." }, "PCSL": { "value": "PCSL", "summary": "DONGYOUNG Shipping Co., Ltd." }, "DSVF": { "value": "DSVF", "summary": "DSV" }, "ECNU": { "value": "ECNU", "summary": "ECON Shipping Group" }, "EMES": { "value": "EMES", "summary": "Emes Feedering S.r.L." }, "ESPU": { "value": "ESPU", "summary": "Emirates Shipping Line" }, "EMKU": { "value": "EMKU", "summary": "Emkay Lines" }, "ESLU": { "value": "ESLU", "summary": "Ethiopian Shipping Lines" }, "EBLU": { "value": "EBLU", "summary": "Eurosib line" }, "EGLV": { "value": "EGLV", "summary": "Evergreen Marine Corporation" }, "FESO": { "value": "FESO", "summary": "FESCO Transportation Group" }, "GSLU": { "value": "GSLU", "summary": "Gold Star Line" }, "HYNS": { "value": "HYNS", "summary": "Hainan Yangpu" }, "SUDU": { "value": "SUDU", "summary": "Hamburg Süd" }, "HLCU": { "value": "HLCU", "summary": "Hapag-Lloyd" }, "11QU": { "value": "11QU", "summary": "Heung-A Line" }, "HUBU": { "value": "HUBU", "summary": "Hub Shipping" }, "HYDU": { "value": "HYDU", "summary": "Hyde Shipping" }, "HDMU": { "value": "HDMU", "summary": "Hyundai Merchant Marine" }, "LMCU": { "value": "LMCU", "summary": "Ignazio Messina Container Line" }, "IILU": { "value": "IILU", "summary": "Independent Container Line" }, "12AT": { "value": "12AT", "summary": "Interasia Lines Ltd." }, "JASO": { "value": "JASO", "summary": "JAS Worldwide" }, "KKCL": { "value": "KKCL", "summary": "Kambara Kisen Co., Ltd." }, "KKLU": { "value": "KKLU", "summary": "Kawasaki Kisen Kaisha, Ltd." }, "KMTU": { "value": "KMTU", "summary": "Korea Marine Transport Co., Ltd." }, "KHNN": { "value": "KHNN", "summary": "Küehne + Nagel" }, "LEHO": { "value": "LEHO", "summary": "Leschaco" }, "MODU": { "value": "MODU", "summary": "M-Line Shipping" }, "MAEI": { "value": "MAEI", "summary": "Maersk Line" }, "MFTU": { "value": "MFTU", "summary": "Marfret Compagnie Maritime" }, "MEXU": { "value": "MEXU", "summary": "Mariana Express Lines" }, "MATS": { "value": "MATS", "summary": "Matson, Inc." }, "MXCU": { "value": "MXCU", "summary": "Maxicon Container Line" }, "MEDU": { "value": "MEDU", "summary": "Mediterranean Shipping Company" }, "MRTU": { "value": "MRTU", "summary": "Meratus Group" }, "MILA": { "value": "MILA", "summary": "Milaha Shipping Line" }, "MOLU": { "value": "MOLU", "summary": "Mitsui O.S.K. Lines" }, "NSRU": { "value": "NSRU", "summary": "Namsung Shipping Co., Ltd." }, "PDLU": { "value": "PDLU", "summary": "Neptune Pacific Direct Line" }, "NYKS": { "value": "NYKS", "summary": "Nippon Yusen Kabushiki Kaisha" }, "32GH": { "value": "32GH", "summary": "Nirint Shipping B.V." }, "OAXU": { "value": "OAXU", "summary": "Ocean Axis Shipping Services LLC" }, "ONEY": { "value": "ONEY", "summary": "Ocean Network Express" }, "OOLU": { "value": "OOLU", "summary": "Orient Overseas Container Line" }, "OVPU": { "value": "OVPU", "summary": "OVP Shipping" }, "PCIU": { "value": "PCIU", "summary": "Pacific International Lines" }, "15AC": { "value": "15AC", "summary": "Pan Continental Shipping Co., Ltd." }, "POBU": { "value": "POBU", "summary": "Pan Ocean Co., Ltd." }, "PSHI": { "value": "PSHI", "summary": "Pasha Hawaii" }, "PLLU": { "value": "PLLU", "summary": "Polynesia Line Ltd." }, "PSL1": { "value": "PSL1", "summary": "PSL Navegação" }, "SIKU": { "value": "SIKU", "summary": "PT Samudera Indonesia Tbk" }, "QNLU": { "value": "QNLU", "summary": "Qatar Navigation Lines" }, "RELU": { "value": "RELU", "summary": "Reel Shipping" }, "REGU": { "value": "REGU", "summary": "Regional Container Lines" }, "SFNM": { "value": "SFNM", "summary": "Safetrans Logistics" }, "SAFM": { "value": "SAFM", "summary": "Safmarine" }, "SPNU": { "value": "SPNU", "summary": "Salam Pacific Indonesia Lines" }, "SJKU": { "value": "SJKU", "summary": "Sarjak Container Lines" }, "SMLU": { "value": "SMLU", "summary": "Seaboard Marine" }, "SEAU": { "value": "SEAU", "summary": "Sealand Maersk" }, "SJHH": { "value": "SJHH", "summary": "SeaLead Shipping Pte. Ltd." }, "JUNU": { "value": "JUNU", "summary": "Shanghai Junan Shipping Co., Ltd." }, "13CQ": { "value": "13CQ", "summary": "Shanghai Minsheng Shipping Co., Ltd." }, "COSP": { "value": "COSP", "summary": "Shanghai Panasia Shipping Co., Ltd." }, "SCIU": { "value": "SCIU", "summary": "Shipping Corporation of India" }, "SLMU": { "value": "SLMU", "summary": "Silmar Shipping Line" }, "SKLU": { "value": "SKLU", "summary": "Sinokor Merchant Marine Co., Ltd." }, "12IH": { "value": "12IH", "summary": "Sinotrans Limited" }, "12PD": { "value": "12PD", "summary": "SITC Container Lines Co., Ltd." }, "SMLM": { "value": "SMLM", "summary": "SM Line Corporation" }, "SNTU": { "value": "SNTU", "summary": "Stolt Tank Containers" }, "CHVW": { "value": "CHVW", "summary": "Swire Shipping" }, "13DF": { "value": "13DF", "summary": "T.S. Lines Limited" }, "TAKU": { "value": "TAKU", "summary": "Tanto Intim Line" }, "GETU": { "value": "GETU", "summary": "Tarros Group" }, "TOTE": { "value": "TOTE", "summary": "TOTE Maritime" }, "TLXU": { "value": "TLXU", "summary": "Trans Asia Group" }, "TJFH": { "value": "TJFH", "summary": "Transfar Shipping Pte. Ltd." }, "TRKU": { "value": "TRKU", "summary": "Turkon Line" }, "UNFR": { "value": "UNFR", "summary": "Unifeeder Group" }, "UGLS": { "value": "UGLS", "summary": "United Global Logistics" }, "VCLU": { "value": "VCLU", "summary": "Volta Container Line" }, "VUXX": { "value": "VUXX", "summary": "VUXX Shipping" }, "22AA": { "value": "22AA", "summary": "Wan Hai Lines" }, "WECU": { "value": "WECU", "summary": "WEC Lines" }, "WWSU": { "value": "WWSU", "summary": "Westwood Shipping Lines" }, "YMLU": { "value": "YMLU", "summary": "Yang Ming Marine Transport Corporation" }, "YASV": { "value": "YASV", "summary": "Yusen Logistics" }, "ZIMU": { "value": "ZIMU", "summary": "ZIM Integrated Shipping Services Ltd." }, "ZLNL": { "value": "ZLNL", "summary": "ZLINE Shipping Private Limited" } }, "description": "SCAC-код перевозчика. Значение AUTO доступно только для type=container. Коды и поддерживаемые типы можно получить через GET /v2/companies.", "schema": { "type": "string" } }, { "name": "type", "required": true, "in": "query", "description": "Тип номера для трекинга. Контейнер - container, коносамент - bl, букинг - bk.", "schema": { "example": "container", "type": "string", "enum": [ "container", "bl", "bk" ] }, "example": "container" }, { "name": "value", "required": true, "in": "query", "description": "Значение номера для трекинга.", "schema": { "example": "CSNU6184414", "type": "string" }, "example": "CSNU6184414" }, { "name": "force_update", "required": false, "in": "query", "description": "Обновлять ли информацию принудительно", "schema": { "default": false, "example": false, "type": "boolean" }, "example": false }, { "name": "need_route", "required": false, "in": "query", "description": "Нужен ли маршрут перевозки", "schema": { "default": false, "example": false, "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackByDocumentOrContainerResponseDto" }, "example": { "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" } } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Отслеживание по одному номеру", "tags": [ "tracking" ] } }, "/v2/shipments": { "get": { "description": "Пример запроса: https://tracking.cargotime.ru/v2/shipments?api_key=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&page=1&limit=50&status=ACTIVE", "operationId": "ShipmentPublicV2Controller_getShipments_v2", "parameters": [ { "name": "need_route", "required": false, "in": "query", "description": "Нужен ли маршрут перевозки", "schema": { "default": false, "example": false, "type": "boolean" }, "example": false }, { "name": "page", "required": false, "in": "query", "description": "Номер страницы", "schema": { "minimum": 1, "maximum": 100000000, "default": 1, "example": 1, "type": "number" }, "example": 1 }, { "name": "limit", "required": false, "in": "query", "description": "Количество отслеживаний на странице", "schema": { "minimum": 1, "maximum": 500, "default": 50, "example": 50, "type": "number" }, "example": 50 }, { "name": "status", "required": false, "in": "query", "description": "Фильтр по статусу отслеживания. Доступные значения: ACTIVE, ARCHIVED", "schema": { "example": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "example": "ACTIVE" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShipmentsResponseDto" }, "example": { "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": "Информация найдена" } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Список отслеживаний", "tags": [ "shipments" ] }, "delete": { "description": "Если неархивное отслеживание создано не более 72 часов назад и shipment_status отличается от IN_TRANSIT (в том числе DELIVERED, UNKNOWN или STUCK), запись удаляется с возвратом одного отслеживания на баланс. Записи со статусом IN_TRANSIT и неархивные записи старше 72 часов архивируются без возврата. Уже архивные записи удаляются без возврата. В data.deleted возвращаются идентификаторы удалённых записей, в data.archived — архивированных.", "operationId": "ShipmentPublicV2Controller_removeShipments_v2", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveShipmentsRequestDto" }, "example": { "shipmentIds": [ "9ff48bf7-4541-49e2-947c-c269200e030f", "fb8936b9-ff16-4776-8710-d4073ab06d1e", "2305a40b-97b2-4c1b-94c4-6d9416b22bde" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveShipmentsResponseDto" }, "example": { "success": true, "data": { "deleted": [ "9ff48bf7-4541-49e2-947c-c269200e030f", "fb8936b9-ff16-4776-8710-d4073ab06d1e" ], "archived": [ "2305a40b-97b2-4c1b-94c4-6d9416b22bde" ] }, "status": "OK", "status_description": "Отслеживания успешно удалены" } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Удаление или архивирование отслеживаний", "tags": [ "shipments" ] } }, "/v2/shipments/{id}": { "patch": { "description": "Обновляет заметку отслеживания, в том числе архивного. Чтобы удалить заметку, отправьте в теле пустую строку `{ \"note\": \"\" }`. Максимальная длина — 40 символов. Другие поля тела отклоняются.", "operationId": "ShipmentPublicV2Controller_updateShipment_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Идентификатор отслеживания", "schema": { "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "string" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "$ref": "#/components/schemas/UpdateShipmentRequestDto/properties/note" } }, "required": [ "note" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShipmentResponseDto" }, "example": { "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" } } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "404": { "description": "Отслеживание не найдено или недоступно" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "summary": "Изменение заметки к отслеживанию", "tags": [ "shipments" ] } }, "/v2/apikey": { "get": { "operationId": "ApiKeyV2Controller_getApiKeyInfo_v2", "parameters": [ { "name": "api_key", "required": false, "in": "query", "description": "API-ключ (передайте api_key или value)", "schema": { "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "string" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "value", "required": false, "in": "query", "deprecated": true, "description": "Устаревший алиас api_key (передайте api_key или value)", "schema": { "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "string" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" }, "example": { "success": true, "data": { "creation_date": "2023-03-23T21:49:43.000Z", "api_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "requests_remaining_count": 45 } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Invalid API key" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Информация об API-ключе", "tags": [ "apikey" ] } }, "/v2/webhook-event-types": { "get": { "operationId": "WebhooksPublicV2Controller_getEventTypes_v2", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventTypeDescription" } }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Описание статуса" } } }, "example": { "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": "Запрос выполнен успешно" } } } } }, "summary": "Типы событий вебхуков", "tags": [ "webhooks" ] } }, "/v2/webhook-notifications": { "get": { "description": "Возвращает историю доставок вебхуков на ваши `callback_url`.\n\nПо умолчанию в ответ попадают только неуспешные доставки. Чтобы выбрать другой статус, передайте `status=pending` или `status=delivered`. Параметр `webhook_id` ограничивает результаты одним вебхуком.\n\nРезультаты разбиты на страницы. В `data` ответа — объект с полями `data`, `meta` и `links`.", "operationId": "WebhooksPublicV2Controller_listNotifications_v2", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "Статус доставки. По умолчанию — `failed`.", "schema": { "default": "failed", "type": "string", "enum": [ "pending", "delivered", "failed" ], "example": "failed" }, "example": "failed" }, { "name": "webhook_id", "required": false, "in": "query", "description": "Идентификатор вебхука, по которому нужно отфильтровать доставки", "schema": { "format": "uuid", "type": "string", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "page", "required": false, "in": "query", "description": "Номер страницы", "schema": { "minimum": 1, "maximum": 100000000, "default": 1, "type": "number", "example": 1 }, "example": 1 }, { "name": "limit", "required": false, "in": "query", "description": "Количество доставок на странице", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number", "example": 50 }, "example": 50 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "oneOf": [ { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookNotification" } }, "meta": { "type": "object", "properties": { "itemsPerPage": { "type": "number", "example": 50 }, "totalItems": { "type": "number", "example": 1 }, "currentPage": { "type": "number", "example": 1 }, "totalPages": { "type": "number", "example": 1 }, "sortBy": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "searchBy": { "type": "array", "items": { "type": "string" } }, "search": { "type": "string" }, "select": { "type": "array", "items": { "type": "string" } } } }, "links": { "type": "object", "properties": { "first": { "type": "string" }, "previous": { "type": "string" }, "current": { "type": "string" }, "next": { "type": "string" }, "last": { "type": "string" } } } } }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Описание статуса" } } }, "example": { "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": "Запрос выполнен успешно" } } } } }, "summary": "История доставки вебхуков", "tags": [ "webhooks" ] } }, "/v2/webhooks": { "post": { "description": "Создаёт вебхук для вашего аккаунта.\n\nВ ответе вы получите `secret` для проверки подписи (22 символа из алфавита base64url: A–Z, a–z, 0–9, `-`, `_`). Секрет показывается только в этом ответе и не возвращается при последующем чтении вебхука, поэтому сразу сохраните его в безопасном месте.\n\nПри каждой доставке Cargotime отправляет `POST`-запрос на ваш `callback_url`. Запрос содержит JSON-объект `WebhookOutgoingPayload` и заголовки:\n- `x-cargotime-signature` — HMAC SHA-256-подпись строки `timestamp + '.' + rawBody` с префиксом `sha256=`;\n- `x-cargotime-timestamp` — метка времени Unix, использованная для подписи;\n- `x-cargotime-event-id` — уникальный идентификатор события, совпадающий с `payload.id`;\n- `x-cargotime-delivery-id` — уникальный идентификатор попытки доставки.", "operationId": "WebhooksPublicV2Controller_create_v2", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookDto" }, "example": { "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" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Описание статуса" } } }, "example": { "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": "Запрос выполнен успешно" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "summary": "Создание вебхука", "tags": [ "webhooks" ] }, "get": { "operationId": "WebhooksPublicV2Controller_list_v2", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Описание статуса" } } }, "example": { "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": "Запрос выполнен успешно" } } } } }, "summary": "Список вебхуков", "tags": [ "webhooks" ] } }, "/v2/webhooks/{id}": { "get": { "operationId": "WebhooksPublicV2Controller_get_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "ID вебхука", "schema": { "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "string" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Описание статуса" } } }, "example": { "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": "Запрос выполнен успешно" } } } } }, "summary": "Получение вебхука", "tags": [ "webhooks" ] }, "patch": { "description": "Изменяет `callback_url`, статус вебхука и список событий. При `regenerate_secret=true` ответ содержит новый `secret`. Он показывается только в этом ответе и не возвращается при последующем чтении вебхука.", "operationId": "WebhooksPublicV2Controller_update_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "ID вебхука", "schema": { "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "string" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookDto" }, "example": { "is_active": true, "regenerate_secret": false, "event_types": [ "tracking.eta_update", "tracking.history_update" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Webhook" }, { "$ref": "#/components/schemas/Webhook" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Описание статуса" } } }, "example": { "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": "Запрос выполнен успешно" } } } } }, "summary": "Обновление вебхука", "tags": [ "webhooks" ] }, "delete": { "operationId": "WebhooksPublicV2Controller_delete_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "ID вебхука", "schema": { "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "string" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "type": "null", "example": null }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Описание статуса" } } }, "example": { "success": true, "data": null, "status": "OK", "status_description": "Запрос выполнен успешно" } } } } }, "summary": "Удаление вебхука", "tags": [ "webhooks" ] } }, "/v2/webhooks/{id}/test": { "post": { "description": "Отправляет тестовое событие `tracking.test` на ваш `callback_url`.", "operationId": "WebhooksPublicV2Controller_test_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "ID вебхука", "schema": { "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "type": "string" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "oneOf": [ { "$ref": "#/components/schemas/WebhookDeliveryResult" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Описание статуса" } } }, "examples": { "success": { "value": { "success": true, "data": { "success": true, "http_status": 200 }, "status": "OK", "status_description": "Запрос выполнен успешно" } }, "failure": { "value": { "success": true, "data": { "success": false, "http_status": 500, "error_message": "fetch failed" }, "status": "OK", "status_description": "Запрос выполнен успешно" } } } } } } }, "summary": "Тестовая отправка вебхука", "tags": [ "webhooks" ] } } }, "info": { "title": "Справочник API", "description": "Получайте данные о перевозках по номеру контейнера, коносамента или букинга через API Cargotime.", "version": "2.1", "contact": { "name": "Cargotime Team", "url": "https://cargotime.ru", "email": "info@cargotime.ru" } }, "tags": [ { "name": "companies", "x-displayName": "Компании" }, { "name": "tracking-batch", "x-displayName": "Пакетное отслеживание" }, { "name": "tracking", "x-displayName": "Отслеживание одного номера" }, { "name": "shipments", "x-displayName": "Управление отслеживаниями" }, { "name": "apikey", "x-displayName": "API-ключи" }, { "name": "webhooks", "x-displayName": "Вебхуки" } ], "servers": [ { "url": "https://tracking.cargotime.ru" } ], "components": { "securitySchemes": { "api_key": { "type": "apiKey", "in": "query", "name": "api_key" } }, "schemas": { "ApiKey": { "type": "object", "properties": { "creation_date": { "format": "date-time", "type": "string", "description": "Дата создания API-ключа в формате YYYY-MM-DDThh:mm:ss.SSSZ. Возвращает timestamp в UTC", "example": "2023-03-23T21:49:43.000Z" }, "api_key": { "type": "string", "format": "uuid", "description": "Значение API-ключа", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "requests_remaining_count": { "type": [ "number", "null" ], "description": "Оставшееся количество отслеживаний, информацию о которых можно получить при помощи данного API-ключа", "example": 45 } }, "required": [ "creation_date", "api_key", "requests_remaining_count" ] }, "ApiKeyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "description": "Информация об API-ключе", "allOf": [ { "$ref": "#/components/schemas/ApiKey" } ] } }, "required": [ "success", "data" ] }, "PublicApiWebhookOkResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Запрос выполнен успешно", "description": "Описание статуса" } }, "required": [ "success", "status", "status_description" ] }, "PublicApiWebhookResponseDto": { "type": "object", "properties": { "secret": { "type": "string", "description": "Секрет подписи. Возвращается только при создании вебхука или regenerate_secret=true" } } }, "PublicApiWebhookWithSecretOkResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Запрос выполнен успешно", "description": "Описание статуса" }, "data": { "$ref": "#/components/schemas/PublicApiWebhookResponseDto" } }, "required": [ "success", "status", "status_description", "data" ] }, "PublicApiWebhookDeleteOkResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE", "NOT_FOUND" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Запрос выполнен успешно", "description": "Описание статуса" }, "data": { "type": [ "null", "null" ], "example": null, "description": "Всегда null при успешном удалении" } }, "required": [ "success", "status", "status_description", "data" ] }, "CreateWebhookDto": { "type": "object", "properties": { "callback_url": { "type": "string", "example": "https://example.com/webhooks/cargotime", "description": "URL, на который Cargotime будет отправлять вебхуки" }, "is_active": { "type": "boolean", "default": true, "description": "Получает ли вебхук события. Тестовую доставку можно запустить и для неактивного вебхука." }, "event_types": { "type": "array", "description": "Типы событий, которые нужно отправлять. Если поле не задано, вебхук получает все публичные типы событий. Для тестовой доставки всегда доступно событие `tracking.test`.", "items": { "type": "string", "enum": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered", "tracking.updates_unavailable", "tracking.updates_restored" ] } } }, "required": [ "callback_url" ] }, "UpdateWebhookDto": { "type": "object", "properties": { "callback_url": { "type": "string", "example": "https://example.com/webhooks/cargotime", "description": "URL, на который Cargotime будет отправлять вебхуки" }, "is_active": { "type": "boolean", "default": true, "description": "Получает ли вебхук события. Тестовую доставку можно запустить и для неактивного вебхука." }, "event_types": { "type": "array", "description": "Типы событий, которые нужно отправлять. Если поле не задано, список событий не изменится. Для тестовой доставки всегда доступно событие `tracking.test`.", "items": { "type": "string", "enum": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered", "tracking.updates_unavailable", "tracking.updates_restored" ] } }, "regenerate_secret": { "type": "boolean", "description": "Создать новый секрет для проверки подписи вебхуков" } } }, "LocWithDate": { "type": "object", "properties": { "location": { "type": [ "number", "null" ], "description": "Идентификатор локации. См. locations", "example": 0 }, "terminal": { "type": [ "number", "null" ], "description": "Идентификатор терминала. См. terminals.", "example": 0 }, "date": { "type": [ "string", "null" ], "description": "Дата в формате YYYY-MM-DDThh:mm:ss / YYYY-MM-DDThh:mm / YYYY-MM-DD", "format": "date-time", "example": "2023-03-25T00:00:00" } }, "required": [ "location", "terminal", "date" ] }, "CompanyInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Короткое название компании", "example": "MSC" }, "full_name": { "type": "string", "description": "Полное название компании", "example": "Mediterranean Shipping Company (MSC)" }, "url": { "type": "string", "description": "Ссылка на сайт компании", "example": "https://www.msc.com/" }, "scacs": { "description": "SCAC-коды перевозчика", "example": [ "MEDU", "MSCU" ], "type": "array", "items": { "type": "string" } } }, "required": [ "name", "full_name", "url", "scacs" ] }, "Summary": { "type": "object", "properties": { "origin": { "description": "Место отправки", "allOf": [ { "$ref": "#/components/schemas/LocWithDate" } ] }, "pol": { "description": "Порт загрузки", "allOf": [ { "$ref": "#/components/schemas/LocWithDate" } ] }, "pod": { "description": "Порт выгрузки", "allOf": [ { "$ref": "#/components/schemas/LocWithDate" } ] }, "destination": { "description": "Место назначения", "allOf": [ { "$ref": "#/components/schemas/LocWithDate" } ] }, "company": { "description": "Перевозчик", "allOf": [ { "$ref": "#/components/schemas/CompanyInfo" } ] } }, "required": [ "origin", "pol", "pod", "destination", "company" ] }, "RouteLocation": { "type": "object", "properties": { "id": { "type": "number", "description": "Идентификатор локации. Используется в TrackingEvent и LocWithDate. Нумерация начинается с нуля.", "example": 0 }, "name": { "type": [ "string", "null" ], "description": "Название локации или город", "example": "Gothenburg" }, "state": { "type": [ "string", "null" ], "description": "Штат/регион", "example": "Halland" }, "terminal": { "type": [ "string", "null" ], "description": "Терминал/порт/склад", "example": "Port of Gothenburg", "deprecated": true }, "country": { "type": [ "string", "null" ], "description": "Страна", "example": "Sweden" }, "lat": { "type": [ "number", "null" ], "description": "Широта", "example": 57.70887 }, "lng": { "type": [ "number", "null" ], "description": "Долгота", "example": 11.97456 } }, "required": [ "id", "name", "state", "terminal", "country", "lat", "lng" ] }, "RouteTerminal": { "type": "object", "properties": { "id": { "type": "number", "description": "Идентификатор терминала. Используется в TrackingEvent и LocWithDate. Нумерация начинается с нуля.", "example": 0 }, "name": { "type": [ "string", "null" ], "description": "Терминал/порт/склад", "example": "Port of Gothenburg" } }, "required": [ "id", "name" ] }, "TrackingEvent": { "type": "object", "properties": { "location": { "type": [ "number", "null" ], "description": "Идентификатор локации", "example": 0 }, "terminal": { "type": [ "number", "null" ], "description": "Идентификатор терминала", "example": 0 }, "status": { "type": [ "string", "null" ], "description": "Наименование события / статус", "example": "On Board" }, "status_code": { "type": [ "string", "null" ], "description": "Статус-код события.\n\n CEP: Отправка порожнего контейнера.\n CPS: Забор груженого контейнера.\n CGI: Прием груженого контейнера.\n CLL: Погрузка в порту отправления.\n VDL: Выход судна из порта отправления.\n VAT: Заход судна в транзитный порт.\n CDT: Выгрузка в транзитном порту.\n TSD: Задержка в пути.\n CLT: Погрузка в транзитном порту.\n VDT: Выход судна из транзитного порта.\n VAD: Заход судна в порт назначения.\n CDD: Выгрузка в порту назначения.\n CGO: Выдача груженого контейнера.\n CDC: Доставка груженого контейнера.\n CER: Возврат порожнего контейнера.\n LTS: Перевозка наземным транспортом.\n BTS: Перевозка водным транспортом.\n UNK: Не определен.\n ", "example": "CLL", "enum": [ "CEP", "CPS", "CGI", "CLL", "VDL", "VAT", "CDT", "TSD", "CLT", "VDT", "VAD", "CDD", "CGO", "CDC", "CER", "LTS", "BTS", "UNK" ] }, "date": { "type": [ "string", "null" ], "description": "Дата в формате YYYY-MM-DDThh:mm:ss", "example": "2023-10-25T11:11:11" }, "actual": { "type": [ "boolean", "null" ], "description": "true — событие произошло и date содержит фактическую дату. false — событие ожидается, дата получена от перевозчика", "example": false }, "vessel": { "type": [ "string", "null" ], "description": "Наименование судна", "example": "Evergreen Teresa" }, "voyage": { "type": [ "string", "null" ], "description": "Рейс", "example": "V. 284" } }, "required": [ "location", "terminal", "status", "status_code", "date", "actual", "vessel", "voyage" ] }, "ContainerInfo": { "type": "object", "properties": { "number": { "type": "string", "description": "Номер контейнера", "example": "TCKU7858986" }, "type": { "type": [ "string", "null" ], "description": "Тип контейнера", "example": "40' Dry" }, "events": { "description": "События перевозки: произошедшие и ожидаемые. Если даты есть у всех событий, они расположены от новых к старым. Если хотя бы одна дата отсутствует, сохраняется порядок перевозчика.", "type": "array", "items": { "$ref": "#/components/schemas/TrackingEvent" } } }, "required": [ "number", "type", "events" ] }, "RouteSection": { "type": "object", "properties": { "path": { "description": "Координаты участка маршрута между двумя местоположениями. Каждая точка — массив чисел [lat, lng].", "example": [ [ 48.698306, 14.042056 ], [ 45.039944, 12.751222 ], [ 43.463278, 12.6745 ], [ 32.566855, 29.927166 ], [ 32.284501, 31.232806 ] ], "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "description": "Является ли отрезок маршрута наземным или морским", "enum": [ "sea", "land" ], "example": "sea" } }, "required": [ "path", "type" ] }, "RouteInfo": { "type": "object", "properties": { "route": { "description": "Маршрут перевозки, представленный в виде массива отрезков пути между соседними локациями", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/RouteSection" } }, "current_position": { "type": [ "object", "null" ], "description": "Текущее местоположение контейнера: массив координат [lat, lng].", "example": [ 32.284501, 31.232806 ] }, "last_updated": { "type": [ "string", "null" ], "description": "Дата последнего обновления местоположения контейнера в формате YYYY-MM-DDThh:mm:ss", "example": "2023-10-25T11:11:11" }, "course": { "type": [ "number", "null" ], "description": "Текущий курс судна", "example": "247.34" } }, "required": [ "route", "current_position", "last_updated", "course" ] }, "TrackingReferences": { "type": "object", "properties": { "booking_numbers": { "description": "Номера букингов", "example": [ "2315887441" ], "type": "array", "items": { "type": "string" } }, "bill_of_lading_numbers": { "description": "Номера коносаментов", "example": [ "MEDUH1234567" ], "type": "array", "items": { "type": "string" } } }, "required": [ "booking_numbers", "bill_of_lading_numbers" ] }, "PublicTrackingDataDto": { "type": "object", "properties": { "summary": { "description": "Общая информация о перевозке", "allOf": [ { "$ref": "#/components/schemas/Summary" } ] }, "locations": { "description": "Локации на маршруте", "type": "array", "items": { "$ref": "#/components/schemas/RouteLocation" } }, "terminals": { "description": "Терминалы на маршруте", "type": "array", "items": { "$ref": "#/components/schemas/RouteTerminal" } }, "containers": { "description": "Контейнеры и события их перевозки", "type": "array", "items": { "$ref": "#/components/schemas/ContainerInfo" } }, "route_info": { "description": "Информация о маршруте", "oneOf": [ { "$ref": "#/components/schemas/RouteInfo" }, { "type": "null" } ] }, "shipment_status": { "type": "string", "description": "Статус перевозки.\n\n IN_TRANSIT: В процессе перевозки.\n DELIVERED: Доставлен получателю.\n UNKNOWN: Не определен.\n STUCK: Перевозка задерживается.\n ", "example": "IN_TRANSIT", "enum": [ "IN_TRANSIT", "DELIVERED", "UNKNOWN", "STUCK" ] }, "references": { "description": "Номера букингов и коносаментов, связанные с перевозкой", "allOf": [ { "$ref": "#/components/schemas/TrackingReferences" } ] } }, "required": [ "summary", "locations", "terminals", "containers", "route_info", "shipment_status" ] }, "ShipmentTrackingResultDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "description": "Результат трекинга", "oneOf": [ { "$ref": "#/components/schemas/PublicTrackingDataDto" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "OK", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "UNEXPECTED_ERROR" ], "example": "OK", "description": "Статус ответа отслеживания" }, "status_description": { "type": [ "string", "null" ], "example": "Информация найдена", "description": "Описание статуса" } }, "required": [ "success", "data", "status", "status_description" ] }, "ShipmentTrackedItemDto": { "type": "object", "properties": { "track_number": { "type": "string", "example": "MSCU1234567", "description": "Номер отслеживания" }, "track_number_type": { "type": "string", "enum": [ "container", "bl", "bk" ], "example": "container", "description": "Тип номера: контейнер, коносамент или букинг" }, "company_id": { "type": [ "number", "null" ], "example": 60, "description": "Идентификатор перевозчика, если известен" }, "data": { "description": "Результат трекинга. Во вложенном data при успехе — данные перевозки; поле containers — один или несколько контейнеров (для BL/BK — несколько).", "oneOf": [ { "$ref": "#/components/schemas/ShipmentTrackingResultDto" }, { "type": "null" } ] }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-04-08T12:08:55.307Z" }, "checked_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-04-08T12:08:55.307Z" }, "company_name": { "type": [ "string", "null" ], "example": "Mediterranean Shipping Company", "description": "Название компании (если известно)" } }, "required": [ "track_number", "track_number_type", "company_id", "data", "updated_at", "checked_at", "company_name" ] }, "PreviewShipmentsInfoDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d8976b45-e3e6-4115-b723-57f9b95fc76b", "description": "Идентификатор отслеживания (shipment)" }, "tracked_item": { "description": "Данные по отслеживаемому объекту (без balance_id / tracked_item_id / id)", "allOf": [ { "$ref": "#/components/schemas/ShipmentTrackedItemDto" } ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-04-08T12:26:56.940Z" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-04-12T09:18:49.395Z" }, "status": { "type": "string", "example": "ACTIVE", "description": "Статус отслеживания в виде строки" }, "note": { "type": [ "string", "null" ], "example": "Order 4521", "description": "Пользовательская заметка к отслеживанию (до 40 символов)", "maxLength": 40 }, "created_at": { "type": "string", "format": "date-time", "example": "2026-04-08T12:08:54.569Z" }, "track_number": { "type": "string", "example": "MSCU1234567", "description": "Номер отслеживания (дублирует tracked_item.track_number для удобства)" } }, "required": [ "id", "tracked_item", "start_date", "end_date", "status", "note", "created_at", "track_number" ] }, "ShipmentsPaginationMetaDto": { "type": "object", "properties": { "itemsPerPage": { "type": "number", "example": 50, "description": "Количество элементов на странице" }, "totalItems": { "type": "number", "example": 145, "description": "Общее количество элементов" }, "currentPage": { "type": "number", "example": 2, "description": "Текущая страница" }, "totalPages": { "type": "number", "example": 3, "description": "Общее количество страниц" }, "sortBy": { "type": "array", "example": [ [ "created_at", "DESC" ], [ "id", "DESC" ] ], "description": "Применённая сортировка" }, "filter": { "type": "object", "example": { "status": "$eq:ACTIVE" }, "description": "Применённые фильтры" } }, "required": [ "itemsPerPage", "totalItems", "currentPage", "totalPages", "sortBy" ] }, "ShipmentsPaginationLinksDto": { "type": "object", "properties": { "first": { "type": "string", "example": "/v2/shipments?page=1&limit=50&status=ACTIVE", "description": "Ссылка на первую страницу" }, "previous": { "type": [ "string", "null" ], "example": "/v2/shipments?page=1&limit=50&status=ACTIVE", "description": "Ссылка на предыдущую страницу" }, "current": { "type": "string", "example": "/v2/shipments?page=2&limit=50&status=ACTIVE", "description": "Ссылка на текущую страницу" }, "next": { "type": [ "string", "null" ], "example": "/v2/shipments?page=3&limit=50&status=ACTIVE", "description": "Ссылка на следующую страницу" }, "last": { "type": "string", "example": "/v2/shipments?page=3&limit=50&status=ACTIVE", "description": "Ссылка на последнюю страницу" } }, "required": [ "current" ] }, "GetShipmentsPaginatedDataDto": { "type": "object", "properties": { "data": { "description": "Информация об отслеживаниях", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PreviewShipmentsInfoDto" } }, "meta": { "description": "Сведения о страницах", "allOf": [ { "$ref": "#/components/schemas/ShipmentsPaginationMetaDto" } ] }, "links": { "description": "Ссылки на страницы", "allOf": [ { "$ref": "#/components/schemas/ShipmentsPaginationLinksDto" } ] } }, "required": [ "data", "meta", "links" ] }, "GetShipmentsResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "description": "Информация об отслеживаниях вместе с пагинацией", "oneOf": [ { "$ref": "#/components/schemas/GetShipmentsPaginatedDataDto" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Информация найдена", "description": "Описание статуса" } }, "required": [ "success", "data", "status", "status_description" ] }, "UpdateShipmentRequestDto": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 40, "example": "Order 123", "description": "Заметка: до 40 любых символов, включая пробелы и переносы. Длина считается до удаления пробелов по краям. Чтобы удалить заметку, отправьте пустую строку `\"note\": \"\"`. null не допускается." } }, "required": [ "note" ] }, "UpdateShipmentResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Информация найдена", "description": "Описание статуса" }, "data": { "description": "Обновлённое отслеживание", "allOf": [ { "$ref": "#/components/schemas/PreviewShipmentsInfoDto" } ] } }, "required": [ "success", "status", "status_description", "data" ] }, "RemoveShipmentsRequestDto": { "type": "object", "properties": { "shipmentIds": { "example": [ "9ff48bf7-4541-49e2-947c-c269200e030f", "fb8936b9-ff16-4776-8710-d4073ab06d1e", "2305a40b-97b2-4c1b-94c4-6d9416b22bde" ], "description": "UUID отслеживаний, которые вы хотите удалить", "type": "array", "items": { "type": "string" } } }, "required": [ "shipmentIds" ] }, "RemovedAndArchivedShipmentsData": { "type": "object", "properties": { "deleted": { "example": [ "9ff48bf7-4541-49e2-947c-c269200e030f", "fb8936b9-ff16-4776-8710-d4073ab06d1e" ], "description": "Идентификаторы удалённых отслеживаний", "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "archived": { "example": [ "2305a40b-97b2-4c1b-94c4-6d9416b22bde" ], "description": "Идентификаторы архивированных отслеживаний", "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } } }, "required": [ "deleted", "archived" ] }, "RemoveShipmentsResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "description": "Информация об удаленных и архивированных отслеживаниях", "oneOf": [ { "$ref": "#/components/schemas/RemovedAndArchivedShipmentsData" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Отслеживания успешно удалены", "description": "Описание статуса" } }, "required": [ "success", "data", "status", "status_description" ] }, "CompanyTrackingCapabilitiesDto": { "type": "object", "properties": { "scac": { "type": "string", "description": "SCAC-код линии", "example": "APLU" }, "cn": { "type": "boolean", "description": "Поддержка трекинга контейнеров (CN)", "example": true }, "bl": { "type": "boolean", "description": "Поддержка трекинга коносамента (BL)", "example": true }, "bk": { "type": "boolean", "description": "Поддержка трекинга букинга (BK)", "example": true } }, "required": [ "scac", "cn", "bl", "bk" ] }, "TrackedItemRequestDto": { "type": "object", "properties": { "company": { "type": "string", "examples": [], "description": "SCAC-код перевозчика. Значение AUTO доступно только для type=container. Коды и поддерживаемые типы можно получить через GET /v2/companies." }, "track_number": { "examples": { "container": { "summary": "Контейнер", "value": { "value": "CSNU6184414", "type": "container" } }, "bl": { "summary": "Коносамент", "value": { "value": "AKKNEM25072638", "type": "bl" } }, "bk": { "summary": "Букинг", "value": { "value": "2315887441", "type": "bk" } } }, "oneOf": [ { "type": "object", "required": [ "value", "type" ], "properties": { "value": { "type": "string", "example": "CSNU6184414" }, "type": { "type": "string", "enum": [ "container" ], "example": "container" } } }, { "type": "object", "required": [ "value", "type" ], "properties": { "value": { "type": "string", "example": "AKKNEM25072638" }, "type": { "type": "string", "enum": [ "bl" ], "example": "bl" } } }, { "type": "object", "required": [ "value", "type" ], "properties": { "value": { "type": "string", "example": "2315887441" }, "type": { "type": "string", "enum": [ "bk" ], "example": "bk" } } } ], "description": "Номер для трекинга (контейнер / букинг / коносамент )" } }, "required": [ "company", "track_number" ] }, "TrackMultipleItemsRequestDto": { "type": "object", "properties": { "tracked_items": { "description": "Массив номеров для трекинга (максимум 500)", "maxItems": 500, "example": [ { "company": "COSU", "track_number": { "value": "CSNU6184414", "type": "container" } }, { "company": "AKKU", "track_number": { "value": "AKKNEM25072638", "type": "bl" } } ], "type": "array", "items": { "$ref": "#/components/schemas/TrackedItemRequestDto" } } }, "required": [ "tracked_items" ] }, "TrackViaStatusDto": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "Идентификатор задачи (UUID)" } }, "required": [ "task_id" ] }, "TrackMultipleItemsResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "description": "Информация о созданной задаче", "oneOf": [ { "$ref": "#/components/schemas/TrackViaStatusDto" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "API_KEY_WRONG", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE" ], "description": "Статус выполнения запроса" } }, "required": [ "success", "data", "status" ] }, "ShipmentTrackingMetadataDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "Уникальный идентификатор отслеживания (UUID)" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "example": "2025-06-29T14:12:00.000Z", "description": "Дата окончания отслеживания в ISO-формате" }, "status": { "type": "string", "example": "ACTIVE", "description": "Статус отслеживания" }, "note": { "type": [ "string", "null" ], "example": "Order 4521", "description": "Пользовательская заметка к отслеживанию (до 40 символов)", "maxLength": 40 }, "created_at": { "type": "string", "format": "date-time", "example": "2025-06-29T14:12:00.000Z", "description": "Дата создания отслеживания в ISO-формате" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-06-30T06:00:00.000Z", "description": "Дата последнего изменения в ISO-формате" } }, "required": [ "id", "end_date", "status", "note", "created_at", "updated_at" ] }, "TrackByDocumentOrContainerShipmentDto": { "type": "object", "properties": { "summary": { "description": "Общая информация о перевозке", "allOf": [ { "$ref": "#/components/schemas/Summary" } ] }, "locations": { "description": "Локации на маршруте", "type": "array", "items": { "$ref": "#/components/schemas/RouteLocation" } }, "terminals": { "description": "Терминалы на маршруте", "type": "array", "items": { "$ref": "#/components/schemas/RouteTerminal" } }, "containers": { "description": "Контейнеры и события их перевозки", "type": "array", "items": { "$ref": "#/components/schemas/ContainerInfo" } }, "route_info": { "description": "Информация о маршруте", "oneOf": [ { "$ref": "#/components/schemas/RouteInfo" }, { "type": "null" } ] }, "shipment_status": { "type": "string", "description": "Статус перевозки.\n\n IN_TRANSIT: В процессе перевозки.\n DELIVERED: Доставлен получателю.\n UNKNOWN: Не определен.\n STUCK: Перевозка задерживается.\n ", "example": "IN_TRANSIT", "enum": [ "IN_TRANSIT", "DELIVERED", "UNKNOWN", "STUCK" ] }, "references": { "description": "Номера букингов и коносаментов, связанные с перевозкой", "allOf": [ { "$ref": "#/components/schemas/TrackingReferences" } ] }, "tracking_metadata": { "description": "Сведения об отслеживании. Может быть null, если запись отслеживания ещё не создана.", "oneOf": [ { "$ref": "#/components/schemas/ShipmentTrackingMetadataDto" }, { "type": "null" } ] } }, "required": [ "summary", "locations", "terminals", "containers", "route_info", "shipment_status", "tracking_metadata" ] }, "TrackingRequestTrackNumberDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "container", "bl", "bk" ], "example": "container", "description": "Тип номера, с которым выполнялся поиск" }, "value": { "type": "string", "example": "TCKU7858986", "description": "Номер, с которым выполнялся поиск" } }, "required": [ "type", "value" ] }, "TrackingRequestEchoDto": { "type": "object", "properties": { "track_number": { "description": "Номер и тип, с которыми выполнялся поиск", "allOf": [ { "$ref": "#/components/schemas/TrackingRequestTrackNumberDto" } ] }, "company": { "type": "string", "example": "MEDU", "description": "Запрошенная компания (SCAC) или AUTO" } }, "required": [ "track_number", "company" ] }, "TrackingResult": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "description": "Информация о перевозке и метаданные отслеживания (как в GET /v2/tracking)", "oneOf": [ { "$ref": "#/components/schemas/TrackByDocumentOrContainerShipmentDto" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "OK", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "UNEXPECTED_ERROR" ], "example": "OK", "description": "Статус ответа отслеживания" }, "status_description": { "type": [ "string", "null" ], "example": "Информация найдена", "description": "Описание статуса" }, "request": { "description": "Исходный элемент batch-запроса: номер, тип и запрошенная компания", "example": { "track_number": { "type": "container", "value": "TCKU7858986" }, "company": "MEDU" }, "allOf": [ { "$ref": "#/components/schemas/TrackingRequestEchoDto" } ] } }, "required": [ "success", "data", "status", "status_description" ] }, "TrackingStatusDataDto": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "Идентификатор задачи пакетного отслеживания" }, "status": { "type": "string", "example": "PROCESSED", "enum": [ "CREATED", "HANDLING", "PROCESSED" ], "description": "Текущий статус выполнения задачи трекинга: CREATED (задача создана, ожидает обработки), HANDLING (обрабатывается в данный момент), PROCESSED (завершена, результаты доступны в поле results)" }, "results": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TrackingResult" } ] }, "description": "Результат каждого номера: исходный запрос, success, status и данные отслеживания. Доступны после завершения задачи (PROCESSED). Проверяйте результат каждого номера отдельно." } }, "required": [ "task_id", "status" ] }, "TrackingStatusResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "description": "Состояние задачи и результаты отслеживания, если обработка завершена", "oneOf": [ { "$ref": "#/components/schemas/TrackingStatusDataDto" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "API_KEY_WRONG", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE" ], "description": "Статус выполнения запроса" } }, "required": [ "success", "data", "status" ] }, "TrackByDocumentOrContainerResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Признак успешной обработки. В результатах отслеживания проверяйте также status: success=true не означает, что данные найдены." }, "data": { "description": "Информация об отслеживании", "oneOf": [ { "$ref": "#/components/schemas/TrackByDocumentOrContainerShipmentDto" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "API_KEY_WRONG", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE" ], "description": "Статус выполнения запроса" }, "status_description": { "type": [ "string", "null" ], "example": "Information found", "description": "Описание статуса" }, "request": { "description": "Исходный запрос трекинга: номер, тип и запрошенная компания", "example": { "track_number": { "type": "container", "value": "TCKU7858986" }, "company": "MEDU" }, "allOf": [ { "$ref": "#/components/schemas/TrackingRequestEchoDto" } ] } }, "required": [ "success", "data", "status", "status_description" ] }, "WebhookEtaUpdatePayload": { "title": "tracking.eta_update", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "type": { "type": "string", "const": "tracking.eta_update" }, "api_version": { "type": "string", "const": "2026-07-09", "example": "2026-07-09" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-08T13:11:22.758Z" }, "resource": { "$ref": "#/components/schemas/WebhookResource" }, "data": { "$ref": "#/components/schemas/WebhookEtaUpdateData" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookChange" }, "example": [ { "field": "eta", "old": "2026-07-01T00:00:00", "new": "2026-07-15T00:00:00" } ] } }, "required": [ "id", "type", "api_version", "created_at", "resource", "data", "changes" ], "example": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.eta_update", "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": "IN_TRANSIT", "route": { "origin": "Wilmington, US", "pol": "Wilmington, US", "pod": "Long Beach, US", "destination": "Dallas, US" }, "eta": "2026-07-15T00:00:00", "current_position": { "lat": 33.74, "lng": -118.27, "updated_at": "2026-07-08T12:00:00.000Z" } }, "changes": [ { "field": "eta", "old": "2026-07-01T00:00:00", "new": "2026-07-15T00:00:00" } ] } }, "WebhookHistoryUpdatePayload": { "title": "tracking.history_update", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "type": { "type": "string", "const": "tracking.history_update" }, "api_version": { "type": "string", "const": "2026-07-09", "example": "2026-07-09" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-08T13:11:22.758Z" }, "resource": { "$ref": "#/components/schemas/WebhookResource" }, "data": { "$ref": "#/components/schemas/WebhookHistoryUpdateData" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookChange" }, "example": [ { "field": "route.pol", "old": null, "new": "Wilmington, US" }, { "field": "route.pod", "old": null, "new": "Long Beach, US" }, { "field": "event", "old": null, "new": { "location": "Long Beach, US", "status": "Vessel arrived", "status_code": "VAD", "date": "2026-07-07T00:00:00", "actual": true, "vessel": "MSC OSCAR", "voyage": "FJ123E" } } ] } }, "required": [ "id", "type", "api_version", "created_at", "resource", "data", "changes" ], "example": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.history_update", "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": "IN_TRANSIT", "route": { "origin": "Wilmington, US", "pol": "Wilmington, US", "pod": "Long Beach, US", "destination": "Dallas, US" }, "event": { "location": "Long Beach, US", "status": "Vessel arrived", "status_code": "VAD", "date": "2026-07-07T00:00:00", "actual": true, "vessel": "MSC OSCAR", "voyage": "FJ123E" }, "current_position": { "lat": 33.74, "lng": -118.27, "updated_at": "2026-07-08T12:00:00.000Z" } }, "changes": [ { "field": "route.pol", "old": null, "new": "Wilmington, US" }, { "field": "route.pod", "old": null, "new": "Long Beach, US" }, { "field": "event", "old": null, "new": { "location": "Long Beach, US", "status": "Vessel arrived", "status_code": "VAD", "date": "2026-07-07T00:00:00", "actual": true, "vessel": "MSC OSCAR", "voyage": "FJ123E" } } ] } }, "WebhookInfoFoundPayload": { "title": "tracking.info_found", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "type": { "type": "string", "const": "tracking.info_found" }, "api_version": { "type": "string", "const": "2026-07-09", "example": "2026-07-09" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-08T13:11:22.758Z" }, "resource": { "$ref": "#/components/schemas/WebhookResource" }, "data": { "$ref": "#/components/schemas/WebhookInfoFoundData" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookChange" }, "example": [] } }, "required": [ "id", "type", "api_version", "created_at", "resource", "data", "changes" ], "example": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.info_found", "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": "IN_TRANSIT", "route": { "origin": "Wilmington, US", "pol": "Wilmington, US", "pod": "Long Beach, US", "destination": "Dallas, US" }, "current_position": { "lat": 33.74, "lng": -118.27, "updated_at": "2026-07-08T12:00:00.000Z" } }, "changes": [] } }, "WebhookInfoNotFoundPayload": { "title": "tracking.info_not_found", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "type": { "type": "string", "const": "tracking.info_not_found" }, "api_version": { "type": "string", "const": "2026-07-09", "example": "2026-07-09" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-08T13:11:22.758Z" }, "resource": { "$ref": "#/components/schemas/WebhookResource" }, "data": { "$ref": "#/components/schemas/WebhookInfoNotFoundData" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookChange" }, "example": [] } }, "required": [ "id", "type", "api_version", "created_at", "resource", "data", "changes" ], "example": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.info_not_found", "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": null, "company_scac": "MSCU" }, "data": { "tracking_status": "INFO_NOT_FOUND", "tracking_status_description": "Information not found" }, "changes": [] } }, "WebhookAutoArchivingPayload": { "title": "tracking.auto_archiving", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "type": { "type": "string", "const": "tracking.auto_archiving" }, "api_version": { "type": "string", "const": "2026-07-09", "example": "2026-07-09" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-08T13:11:22.758Z" }, "resource": { "type": "null", "description": "Для события `tracking.auto_archiving`, относящегося ко всему аккаунту, значение всегда равно `null`", "example": null }, "data": { "$ref": "#/components/schemas/WebhookAutoArchivingData" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookChange" }, "example": [] } }, "required": [ "id", "type", "api_version", "created_at", "resource", "data", "changes" ], "example": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.auto_archiving", "api_version": "2026-07-09", "created_at": "2026-07-08T13:11:22.758Z", "resource": null, "data": { "auto_renewal_agreement": true }, "changes": [] } }, "WebhookDeliveredPayload": { "title": "tracking.delivered", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "type": { "type": "string", "const": "tracking.delivered" }, "api_version": { "type": "string", "const": "2026-07-09", "example": "2026-07-09" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-08T13:11:22.758Z" }, "resource": { "$ref": "#/components/schemas/WebhookResource" }, "data": { "$ref": "#/components/schemas/WebhookDeliveredData" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookChange" }, "example": [] } }, "required": [ "id", "type", "api_version", "created_at", "resource", "data", "changes" ], "example": { "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": [] } }, "WebhookTestPayload": { "title": "tracking.test", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "type": { "type": "string", "const": "tracking.test" }, "api_version": { "type": "string", "const": "2026-07-09", "example": "2026-07-09" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-08T13:11:22.758Z" }, "resource": { "$ref": "#/components/schemas/WebhookResource" }, "data": { "$ref": "#/components/schemas/WebhookEmptyData" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookChange" }, "example": [] } }, "required": [ "id", "type", "api_version", "created_at", "resource", "data", "changes" ], "example": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.test", "api_version": "2026-07-09", "created_at": "2026-07-08T13:11:22.758Z", "resource": null, "data": {}, "changes": [] } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "callback_url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/cargotime" }, "is_active": { "type": "boolean", "example": true }, "event_types": { "type": "array", "description": "Публичные типы событий, на которые подписан вебхук. Событие `tracking.test` всегда доступно для тестовой доставки и не входит в этот список.", "items": { "type": "string", "enum": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ] }, "example": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-08T09:39:36.311Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-08T13:10:43.554Z" }, "secret": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{22}$", "description": "Секрет для проверки подписи: 22 символа base64url (A–Z, a–z, 0–9, `-`, `_`). Есть только после создания вебхука или при regenerate_secret=true; в остальных ответах поле отсутствует.", "example": "AaBbCcDdEe-_0123456789" } }, "required": [ "id", "callback_url", "is_active", "event_types", "created_at", "updated_at" ] }, "WebhookDeliveryResult": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "http_status": { "type": [ "integer", "null" ], "example": 200 }, "error_message": { "type": "string", "example": "fetch failed" } }, "required": [ "success", "http_status" ] }, "WebhookEventTypeDescription": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "example": "tracking.info_found" }, "group": { "type": "string", "example": "tracking" }, "description": { "type": "string", "example": "Tracking information was found" } }, "required": [ "type", "group", "description" ] }, "WebhookNotification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "webhook_id": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "event_type": { "type": "string", "enum": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered", "tracking.test" ], "example": "tracking.test" }, "payload": { "$ref": "#/components/schemas/WebhookOutgoingPayload" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ], "example": "delivered" }, "attempt_count": { "type": "integer", "example": 1 }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "example": null }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-08T13:16:38.565Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-08T13:16:38.371Z" }, "webhook": { "$ref": "#/components/schemas/Webhook" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryAttempt" } } }, "required": [ "id", "webhook_id", "event_type", "payload", "status", "attempt_count", "created_at" ] }, "WebhookOutgoingPayload": { "description": "JSON-объект, который Cargotime отправляет на ваш `callback_url`. Общие поля одинаковы для всех событий, а содержимое `data` зависит от типа события.", "oneOf": [ { "$ref": "#/components/schemas/WebhookEtaUpdatePayload" }, { "$ref": "#/components/schemas/WebhookHistoryUpdatePayload" }, { "$ref": "#/components/schemas/WebhookInfoFoundPayload" }, { "$ref": "#/components/schemas/WebhookInfoNotFoundPayload" }, { "$ref": "#/components/schemas/WebhookAutoArchivingPayload" }, { "$ref": "#/components/schemas/WebhookDeliveredPayload" }, { "$ref": "#/components/schemas/WebhookTestPayload" } ], "discriminator": { "propertyName": "type", "mapping": { "tracking.eta_update": "#/components/schemas/WebhookEtaUpdatePayload", "tracking.history_update": "#/components/schemas/WebhookHistoryUpdatePayload", "tracking.info_found": "#/components/schemas/WebhookInfoFoundPayload", "tracking.info_not_found": "#/components/schemas/WebhookInfoNotFoundPayload", "tracking.auto_archiving": "#/components/schemas/WebhookAutoArchivingPayload", "tracking.delivered": "#/components/schemas/WebhookDeliveredPayload", "tracking.test": "#/components/schemas/WebhookTestPayload" } } }, "WebhookDeliveryAttempt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "dddddddd-eeee-ffff-aaaa-bbbbbbbbbbbb" }, "notification_id": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "attempt_number": { "type": "integer", "example": 1 }, "http_status": { "type": [ "integer", "null" ], "example": 200 }, "error_message": { "type": [ "string", "null" ], "example": null }, "attempted_at": { "type": "string", "format": "date-time", "example": "2026-07-08T13:16:38.396Z" } }, "required": [ "id", "notification_id", "attempt_number", "attempted_at" ] }, "WebhookResource": { "type": [ "object", "null" ], "description": "Технические данные отслеживаемого объекта. Для событий уровня аккаунта, например `tracking.auto_archiving` и `tracking.test`, значение равно `null`.", "properties": { "tracked_item_id": { "type": "string", "format": "uuid", "example": "eeeeeeee-ffff-aaaa-bbbb-cccccccccccc" }, "track_number": { "$ref": "#/components/schemas/WebhookTrackNumber" }, "company": { "type": [ "string", "null" ], "example": "Mediterranean Shipping Company" }, "company_scac": { "type": [ "string", "null" ], "example": "MSCU" } }, "required": [ "tracked_item_id", "track_number", "company", "company_scac" ] }, "WebhookEmptyData": { "type": "object", "additionalProperties": false, "description": "Пустой объект, используемый только в событиях `tracking.test`", "example": {} }, "WebhookChange": { "type": "object", "properties": { "field": { "type": "string", "example": "eta" }, "old": { "oneOf": [ { "example": "2026-07-01T00:00:00" }, { "type": "null" } ] }, "new": { "oneOf": [ { "example": "2026-07-15T00:00:00" }, { "type": "null" } ] } }, "required": [ "field", "old", "new" ] }, "WebhookTrackNumber": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "container", "bl", "bk" ], "description": "Тип номера для отслеживания", "example": "container" }, "value": { "type": "string", "description": "Номер контейнера, коносамента или букинга", "example": "MSBU6501445" } }, "required": [ "type", "value" ] }, "WebhookDeliveredData": { "type": "object", "properties": { "shipment_status": { "type": "string", "enum": [ "IN_TRANSIT", "DELIVERED", "UNKNOWN", "STUCK" ], "example": "DELIVERED" }, "route": { "$ref": "#/components/schemas/WebhookRoute" }, "final_location": { "type": [ "string", "null" ], "example": "Long Beach, US", "description": "Последнее известное местоположение: `event.location`, `route.destination` или `route.pod` — первое доступное значение" }, "current_position": { "$ref": "#/components/schemas/WebhookCurrentPosition" }, "event": { "$ref": "#/components/schemas/WebhookTrackingEvent", "description": "Последнее событие отслеживания. Его местоположение может отличаться от `final_location`." } }, "required": [ "shipment_status", "route", "final_location", "event", "current_position" ] }, "WebhookRoute": { "type": "object", "description": "Маршрут из сводки отслеживания: origin → pol → pod → destination", "properties": { "origin": { "type": [ "string", "null" ], "example": "Wilmington, US" }, "pol": { "type": [ "string", "null" ], "example": "Wilmington, US" }, "pod": { "type": [ "string", "null" ], "example": "Long Beach, US" }, "destination": { "type": [ "string", "null" ], "example": "Dallas, US" } }, "required": [ "origin", "pol", "pod", "destination" ] }, "WebhookCurrentPosition": { "type": [ "object", "null" ], "properties": { "lat": { "type": "number", "example": 33.74 }, "lng": { "type": "number", "example": -118.27 }, "updated_at": { "type": [ "string", "null" ], "example": "2026-07-08T12:00:00.000Z" } }, "required": [ "lat", "lng", "updated_at" ] }, "WebhookTrackingEvent": { "type": [ "object", "null" ], "properties": { "location": { "type": [ "string", "null" ], "example": "Long Beach, US" }, "status": { "type": [ "string", "null" ], "example": "Vessel arrived" }, "status_code": { "type": "string", "example": "VAD" }, "date": { "type": [ "string", "null" ], "example": "2026-07-07T00:00:00" }, "actual": { "type": [ "boolean", "null" ], "example": true }, "vessel": { "type": [ "string", "null" ], "example": "MSC OSCAR" }, "voyage": { "type": [ "string", "null" ], "example": "FJ123E" } }, "required": [ "location", "status", "status_code", "date", "actual", "vessel", "voyage" ] }, "WebhookAutoArchivingData": { "type": "object", "description": "Данные об автоматическом архивировании отслеживаний в аккаунте.", "properties": { "auto_renewal_agreement": { "type": "boolean", "description": "Включено ли у пользователя автоматическое продление подписок", "example": true } }, "required": [ "auto_renewal_agreement" ], "additionalProperties": false, "example": { "auto_renewal_agreement": true } }, "WebhookInfoNotFoundData": { "type": "object", "properties": { "tracking_status": { "type": "string", "enum": [ "OK", "INFO_NOT_FOUND", "LINE_IS_UNDER_MAINTENANCE", "LINE_NO_RESPONSE", "UNEXPECTED_ERROR" ], "example": "INFO_NOT_FOUND" }, "tracking_status_description": { "type": [ "string", "null" ], "example": "Information not found" } }, "required": [ "tracking_status", "tracking_status_description" ] }, "WebhookInfoFoundData": { "type": "object", "properties": { "shipment_status": { "type": "string", "enum": [ "IN_TRANSIT", "DELIVERED", "UNKNOWN", "STUCK" ], "example": "IN_TRANSIT" }, "route": { "$ref": "#/components/schemas/WebhookRoute" }, "current_position": { "$ref": "#/components/schemas/WebhookCurrentPosition" } }, "required": [ "shipment_status", "route", "current_position" ] }, "WebhookHistoryUpdateData": { "type": "object", "properties": { "shipment_status": { "type": "string", "enum": [ "IN_TRANSIT", "DELIVERED", "UNKNOWN", "STUCK" ], "example": "IN_TRANSIT" }, "route": { "$ref": "#/components/schemas/WebhookRoute" }, "event": { "$ref": "#/components/schemas/WebhookTrackingEvent" }, "current_position": { "$ref": "#/components/schemas/WebhookCurrentPosition" } }, "required": [ "shipment_status", "route", "event", "current_position" ] }, "WebhookEtaUpdateData": { "type": "object", "properties": { "shipment_status": { "type": "string", "enum": [ "IN_TRANSIT", "DELIVERED", "UNKNOWN", "STUCK" ], "example": "IN_TRANSIT" }, "route": { "$ref": "#/components/schemas/WebhookRoute" }, "eta": { "type": "string", "example": "2026-07-15T00:00:00" }, "current_position": { "$ref": "#/components/schemas/WebhookCurrentPosition" } }, "required": [ "shipment_status", "route", "eta", "current_position" ] } } }, "security": [ { "api_key": [] } ], "webhooks": { "trackingWebhookDelivery": { "post": { "summary": "Получить событие отслеживания", "tags": [ "webhooks" ], "description": "Когда происходит событие отслеживания, на которое вы подписаны, Cargotime отправляет `POST`-запрос на ваш `callback_url`.\n\nПосле получения события как можно скорее верните `200 OK`. Если обработка занимает время, сначала поставьте событие в очередь, отправьте ответ, а затем обработайте его асинхронно. Cargotime ждёт ответ 10 секунд.\n\nДоставка считается успешной при любом статусе `2xx`. Cargotime повторяет доставку после статусов `408`, `409`, `425`, `429` и `5xx`, а также при таймаутах и ошибках DNS или сети. После статусов `400`, `401`, `403`, `404` и `422` повторной попытки не будет. При статусе `429` Cargotime учитывает заголовок `Retry-After`, если он передан. Всего может быть не более пяти попыток.\n\nЧтобы проверить источник запроса, используйте секрет вебхука и заголовки `x-cargotime-timestamp` и `x-cargotime-signature`. Значение подписи — HMAC SHA-256 от строки `timestamp + '.' + rawBody` с префиксом `sha256=`. В `rawBody` должно попасть исходное тело запроса без изменений. Проверять подпись необязательно, но мы рекомендуем это делать.\n\n### Node.js / Express\n\n```ts\nimport crypto from 'node:crypto';\nimport express from 'express';\n\nconst app = express();\nconst secret = process.env.CARGOTIME_WEBHOOK_SECRET;\n\nif (!secret) {\n throw new Error('CARGOTIME_WEBHOOK_SECRET is not set');\n}\n\nfunction queueWebhook(payload: unknown): void {\n // Здесь можно поставить событие в очередь,\n // сохранить его в базе данных или передать внутреннему сервису.\n console.log('Cargotime прислал вебхук:', payload);\n}\n\napp.post('/webhooks/cargotime', express.raw({ type: 'application/json' }), (req, res) => {\n const timestamp = req.header('x-cargotime-timestamp');\n const signature = req.header('x-cargotime-signature');\n\n if (!timestamp || !signature) {\n return res.sendStatus(401);\n }\n\n const expected =\n 'sha256=' + crypto.createHmac('sha256', secret).update(timestamp).update('.').update(req.body).digest('hex');\n\n const signatureBuffer = Buffer.from(signature);\n const expectedBuffer = Buffer.from(expected);\n\n if (signatureBuffer.length !== expectedBuffer.length || !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) {\n return res.sendStatus(401);\n }\n\n const payload = JSON.parse(req.body.toString('utf8'));\n\n queueWebhook(payload);\n\n return res.sendStatus(200);\n});\n\napp.listen(3000, () => {\n console.log('Сервер вебхуков запущен на порту 3000');\n});\n```\n\n### Python / FastAPI\n\n```python\nimport hmac\nimport hashlib\nimport os\n\nfrom fastapi import FastAPI, Request, HTTPException\n\napp = FastAPI()\n\nsecret = os.environ[\"CARGOTIME_WEBHOOK_SECRET\"].encode()\n\n\ndef enqueue_webhook(payload: dict) -> None:\n # Здесь можно поставить событие в очередь,\n # сохранить его в базе данных или передать внутреннему сервису.\n print(\"Cargotime прислал вебхук:\", payload)\n\n\n@app.post(\"/webhooks/cargotime\")\nasync def cargotime_webhook(request: Request):\n body = await request.body()\n\n timestamp = request.headers.get(\"x-cargotime-timestamp\")\n signature = request.headers.get(\"x-cargotime-signature\")\n\n if not timestamp or not signature:\n raise HTTPException(status_code=401)\n\n digest = hmac.new(\n secret,\n timestamp.encode() + b\".\" + body,\n hashlib.sha256,\n ).hexdigest()\n\n expected = f\"sha256={digest}\"\n\n if not hmac.compare_digest(signature, expected):\n raise HTTPException(status_code=401)\n\n payload = await request.json()\n\n enqueue_webhook(payload)\n\n return {\"ok\": True}\n```", "parameters": [ { "name": "x-cargotime-signature", "in": "header", "required": true, "description": "HMAC SHA-256-подпись строки `timestamp + '.' + rawBody` с префиксом `sha256=`. Для `rawBody` используйте исходное тело запроса без изменений.", "schema": { "type": "string", "example": "sha256=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "example": "sha256=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "x-cargotime-timestamp", "in": "header", "required": true, "description": "Метка времени Unix, использованная для подписи", "schema": { "type": "string", "example": "1783512000" }, "example": "1783512000" }, { "name": "x-cargotime-event-id", "in": "header", "required": true, "description": "Уникальный идентификатор события, совпадающий с `payload.id`", "schema": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, { "name": "x-cargotime-delivery-id", "in": "header", "required": true, "description": "Уникальный идентификатор попытки доставки", "schema": { "type": "string", "format": "uuid", "example": "dddddddd-eeee-ffff-aaaa-bbbbbbbbbbbb" }, "example": "dddddddd-eeee-ffff-aaaa-bbbbbbbbbbbb" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebhookEtaUpdatePayload" }, { "$ref": "#/components/schemas/WebhookHistoryUpdatePayload" }, { "$ref": "#/components/schemas/WebhookInfoFoundPayload" }, { "$ref": "#/components/schemas/WebhookInfoNotFoundPayload" }, { "$ref": "#/components/schemas/WebhookAutoArchivingPayload" }, { "$ref": "#/components/schemas/WebhookDeliveredPayload" }, { "$ref": "#/components/schemas/WebhookTestPayload" } ], "discriminator": { "propertyName": "type", "mapping": { "tracking.eta_update": "#/components/schemas/WebhookEtaUpdatePayload", "tracking.history_update": "#/components/schemas/WebhookHistoryUpdatePayload", "tracking.info_found": "#/components/schemas/WebhookInfoFoundPayload", "tracking.info_not_found": "#/components/schemas/WebhookInfoNotFoundPayload", "tracking.auto_archiving": "#/components/schemas/WebhookAutoArchivingPayload", "tracking.delivered": "#/components/schemas/WebhookDeliveredPayload", "tracking.test": "#/components/schemas/WebhookTestPayload" } } }, "examples": { "tracking.eta_update": { "summary": "tracking.eta_update", "value": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.eta_update", "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": "IN_TRANSIT", "route": { "origin": "Wilmington, US", "pol": "Wilmington, US", "pod": "Long Beach, US", "destination": "Dallas, US" }, "eta": "2026-07-15T00:00:00", "current_position": { "lat": 33.74, "lng": -118.27, "updated_at": "2026-07-08T12:00:00.000Z" } }, "changes": [ { "field": "eta", "old": "2026-07-01T00:00:00", "new": "2026-07-15T00:00:00" } ] } }, "tracking.history_update": { "summary": "tracking.history_update", "value": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.history_update", "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": "IN_TRANSIT", "route": { "origin": "Wilmington, US", "pol": "Wilmington, US", "pod": "Long Beach, US", "destination": "Dallas, US" }, "event": { "location": "Long Beach, US", "status": "Vessel arrived", "status_code": "VAD", "date": "2026-07-07T00:00:00", "actual": true, "vessel": "MSC OSCAR", "voyage": "FJ123E" }, "current_position": { "lat": 33.74, "lng": -118.27, "updated_at": "2026-07-08T12:00:00.000Z" } }, "changes": [ { "field": "route.pol", "old": null, "new": "Wilmington, US" }, { "field": "route.pod", "old": null, "new": "Long Beach, US" }, { "field": "event", "old": null, "new": { "location": "Long Beach, US", "status": "Vessel arrived", "status_code": "VAD", "date": "2026-07-07T00:00:00", "actual": true, "vessel": "MSC OSCAR", "voyage": "FJ123E" } } ] } }, "tracking.info_found": { "summary": "tracking.info_found", "value": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.info_found", "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": "IN_TRANSIT", "route": { "origin": "Wilmington, US", "pol": "Wilmington, US", "pod": "Long Beach, US", "destination": "Dallas, US" }, "current_position": { "lat": 33.74, "lng": -118.27, "updated_at": "2026-07-08T12:00:00.000Z" } }, "changes": [] } }, "tracking.info_not_found": { "summary": "tracking.info_not_found", "value": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.info_not_found", "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": null, "company_scac": "MSCU" }, "data": { "tracking_status": "INFO_NOT_FOUND", "tracking_status_description": "Information not found" }, "changes": [] } }, "tracking.delivered": { "summary": "tracking.delivered", "value": { "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": [] } }, "tracking.auto_archiving": { "summary": "tracking.auto_archiving", "value": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.auto_archiving", "api_version": "2026-07-09", "created_at": "2026-07-08T13:11:22.758Z", "resource": null, "data": { "auto_renewal_agreement": true }, "changes": [] } }, "tracking.test": { "summary": "tracking.test", "value": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.test", "api_version": "2026-07-09", "created_at": "2026-07-08T13:11:22.758Z", "resource": null, "data": {}, "changes": [] } } } } } }, "responses": { "400": { "description": "Доставка не удалась: сервер вернул `400 Bad Request`. Повторной попытки не будет." }, "401": { "description": "Доставка не удалась: сервер вернул `401 Unauthorized`. Повторной попытки не будет." }, "403": { "description": "Доставка не удалась: сервер вернул `403 Forbidden`. Повторной попытки не будет." }, "404": { "description": "Доставка не удалась: сервер вернул `404 Not Found`. Повторной попытки не будет." }, "408": { "description": "Сервер вернул `408 Request Timeout`. Cargotime повторит доставку, если остались попытки." }, "409": { "description": "Сервер вернул `409 Conflict`. Cargotime повторит доставку, если остались попытки." }, "422": { "description": "Доставка не удалась: сервер вернул `422 Unprocessable Content`. Повторной попытки не будет." }, "425": { "description": "Сервер вернул `425 Too Early`. Cargotime повторит доставку, если остались попытки." }, "429": { "description": "Сервер вернул `429 Too Many Requests`. Cargotime повторит доставку и учтёт заголовок `Retry-After`, если он передан." }, "2XX": { "description": "Доставка выполнена. Любой ответ со статусом `2xx` отмечает вебхук как доставленный. Рекомендуем вернуть `200 OK` сразу после получения события." }, "5XX": { "description": "Сервер вернул статус `5xx`. Cargotime повторит доставку, если остались попытки." }, "default": { "description": "После любого другого статуса, кроме `2xx`, повторной попытки не будет. Ошибки сети, DNS и соединения, а также таймауты доставки обрабатываются отдельно: в этих случаях Cargotime повторит доставку." } } } } } }