{ "openapi": "3.1.2", "paths": { "/v2/companies": { "get": { "description": "Returns supported carriers, their SCAC codes, and tracking types. Each key in `data` is a company name, and each value contains `scac`, `cn`, `bl`, and `bk`. Pass `scac` as `company`. Flags set to `true` indicate support for containers, bills of lading, and bookings respectively.", "operationId": "CompaniesV2Controller_getCompaniesList_v2", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "data": { "type": "object", "description": "Key is the full company name, value includes SCAC and supported tracking type flags.", "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": "List supported carriers", "tags": [ "companies" ] } }, "/v2/tracking/batch": { "post": { "description": "Creates a task for between 1 and 500 tracking numbers. Processing is asynchronous. The API returns a `task_id` without waiting for tracking results. Use it with `GET /v2/tracking/batch` to retrieve the task state and results later. Task data is cached for up to 6 hours.", "operationId": "MultipleTrackingPublicV2Controller_multipleContainerTracking_v2", "parameters": [ { "name": "need_route", "required": false, "in": "query", "description": "Whether to include route information", "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": "Create a batch tracking task", "tags": [ "tracking-batch" ] }, "get": { "description": "Returns the state of a task created with `POST /v2/tracking/batch`. In `data.status`, `CREATED` means queued, `HANDLING` means processing, and `PROCESSED` means complete. Once complete, read `data.results` and stop requesting the task state. Use tracking requests or webhooks for later shipment updates. Task data is cached for up to 6 hours.", "operationId": "MultipleTrackingPublicV2Controller_getContainerTrackingStatus_v2", "parameters": [ { "name": "task_id", "required": true, "in": "query", "description": "The unique identifier of the tracking task. It is obtained when creating a request via 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", "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" } } ] }, "status": "OK" } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Get batch tracking status and results", "tags": [ "tracking-batch" ] } }, "/v2/tracking": { "get": { "description": "Example request: https://tracking.timetocargo.com/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": "Automatic carrier detection" }, "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" }, "CMDU": { "value": "CMDU", "summary": "CMA CGM" }, "CXNU": { "value": "CXNU", "summary": "Container Corporation of India Ltd" }, "CAMN": { "value": "CAMN", "summary": "Crowley Maritime Corporation" }, "DMCQ": { "value": "DMCQ", "summary": "Damco Marine Management, Inc." }, "11PG": { "value": "11PG", "summary": "Dongjin Shipping Co., Ltd." }, "PCSL": { "value": "PCSL", "summary": "DONGYOUNG Shipping Co., Ltd." }, "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" }, "EGLV": { "value": "EGLV", "summary": "Evergreen Marine Corporation" }, "FESO": { "value": "FESO", "summary": "FESCO Transportation Group" }, "GSLU": { "value": "GSLU", "summary": "Gold Star Line" }, "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" }, "12AT": { "value": "12AT", "summary": "Interasia Lines Ltd." }, "KKCL": { "value": "KKCL", "summary": "Kambara Kisen Co., 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" }, "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." }, "ONEY": { "value": "ONEY", "summary": "Ocean Network Express" }, "OOLU": { "value": "OOLU", "summary": "Orient Overseas Container Line" }, "OVPU": { "value": "OVPU", "summary": "OVP Shipping" }, "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" }, "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" }, "SEAU": { "value": "SEAU", "summary": "Sealand Maersk" }, "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" }, "SKLU": { "value": "SKLU", "summary": "Sinokor Merchant Marine Co., Ltd." }, "12IH": { "value": "12IH", "summary": "Sinotrans Limited" }, "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" }, "TSJL": { "value": "TSJL", "summary": "TransContainer" }, "TJFH": { "value": "TJFH", "summary": "Transfar Shipping Pte. Ltd." }, "VSKH": { "value": "VSKH", "summary": "TT Voskhod" }, "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": "Carrier SCAC code. AUTO is available only for type=container. Use GET /v2/companies to retrieve codes and supported tracking types.", "schema": { "type": "string" } }, { "name": "type", "required": true, "in": "query", "description": "Tracking number type. Container - container, bill of lading - bl, booking - bk.", "schema": { "example": "container", "type": "string", "enum": [ "container", "bl", "bk" ] }, "example": "container" }, { "name": "value", "required": true, "in": "query", "description": "Tracking number value.", "schema": { "example": "CSNU6184414", "type": "string" }, "example": "CSNU6184414" }, { "name": "force_update", "required": false, "in": "query", "description": "Force refresh tracking data", "schema": { "default": false, "example": false, "type": "boolean" }, "example": false }, { "name": "need_route", "required": false, "in": "query", "description": "Whether to include route information", "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", "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": "Track a shipment", "tags": [ "tracking" ] } }, "/v2/shipments": { "get": { "description": "Example request: https://tracking.timetocargo.com/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": "Whether to include route information", "schema": { "default": false, "example": false, "type": "boolean" }, "example": false }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "minimum": 1, "maximum": 100000000, "default": 1, "example": 1, "type": "number" }, "example": 1 }, { "name": "limit", "required": false, "in": "query", "description": "Number of trackings per page", "schema": { "minimum": 1, "maximum": 500, "default": 50, "example": 50, "type": "number" }, "example": 50 }, { "name": "status", "required": false, "in": "query", "description": "Filter shipments by status. Available values: 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", "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": "Information found" }, "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": "Information found" } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "List tracked shipments", "tags": [ "shipments" ] }, "delete": { "description": "A non-archived tracking record created no more than 72 hours ago is deleted with a refund of one tracking credit if shipment_status is not IN_TRANSIT, including DELIVERED, UNKNOWN, and STUCK. Records with IN_TRANSIT and non-archived records older than 72 hours are archived without a refund. Records that are already archived are deleted without a refund. Deleted IDs are returned in data.deleted, and archived IDs in data.archived.", "operationId": "ShipmentPublicV2Controller_removeShipments_v2", "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": "Shipments have been successfully removed" } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Delete or archive tracked shipments", "tags": [ "shipments" ] } }, "/v2/shipments/{id}": { "patch": { "operationId": "ShipmentPublicV2Controller_updateShipment_v2", "summary": "Update a tracked shipment note", "description": "Updates the shipment note, including for archived shipments. To delete the note, send an empty string `{ \"note\": \"\" }` in the request body. Maximum length is 40 characters. Other body fields are rejected.", "tags": [ "shipments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "description": "Tracked shipment ID", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShipmentRequestDto" }, "example": { "note": "Order 123" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShipmentResponseDto" }, "example": { "success": true, "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", "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": "Information found" }, "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" }, "status": "OK", "status_description": "Information found" } } } }, "400": { "description": "Invalid ID, missing/invalid note, or unsupported body fields" }, "403": { "description": "Forbidden" }, "404": { "description": "Shipment not found or inaccessible" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } } } }, "/v2/apikey": { "get": { "operationId": "ApiKeyV2Controller_getApiKeyInfo_v2", "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 or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "null", "example": null }, "status": { "type": "string", "enum": [ "API_KEY_WRONG" ] }, "status_description": { "type": "string" } } }, "example": { "success": false, "data": null, "status": "API_KEY_WRONG" } } } }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Get API key information", "tags": [ "apikey" ], "parameters": [ { "name": "api_key", "in": "query", "required": false, "description": "API key. Provide api_key or its legacy value alias.", "schema": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "value", "in": "query", "required": false, "deprecated": true, "description": "Deprecated alias for api_key. Provide api_key or value.", "schema": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ] } }, "/v2/webhook-event-types": { "get": { "operationId": "WebhooksPublicV2Controller_getEventTypes_v2", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "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": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Status description" } } }, "example": { "success": true, "data": [ { "type": "tracking.eta_update", "group": "tracking", "description": "Estimated arrival date changed" }, { "type": "tracking.history_update", "group": "tracking", "description": "An event was added to the tracking history" }, { "type": "tracking.info_found", "group": "tracking", "description": "Tracking data was found" }, { "type": "tracking.info_not_found", "group": "tracking", "description": "Tracking data was not found" }, { "type": "tracking.auto_archiving", "group": "tracking", "description": "Subscriptions were automatically archived" }, { "type": "tracking.delivered", "group": "tracking", "description": "Shipment was delivered" } ], "status": "OK", "status_description": "Request completed successfully" } } } }, "401": { "description": "Unauthorized" } }, "summary": "List webhook event types", "tags": [ "webhooks" ] } }, "/v2/webhook-notifications": { "get": { "description": "Returns the webhook delivery history for your `callback_url` values.\n\nBy default, the response includes only failed deliveries. To select another status, pass `status=pending` or `status=delivered`. Use `webhook_id` to limit the results to one webhook.\n\nResults are paginated. The envelope `data` contains paginated `data`, `meta`, and `links`.", "operationId": "WebhooksPublicV2Controller_listNotifications_v2", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "Delivery status. Defaults to `failed`.", "schema": { "enum": [ "pending", "delivered", "failed" ], "type": "string", "default": "failed", "example": "failed" }, "example": "failed" }, { "name": "webhook_id", "required": false, "in": "query", "description": "ID of the webhook whose deliveries should be returned", "schema": { "format": "uuid", "type": "string", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "minimum": 1, "default": 1, "type": "integer", "example": 1 }, "example": 1 }, { "name": "limit", "required": false, "in": "query", "description": "Number of deliveries per page", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer", "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": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "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": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Status 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/timetocargo", "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": "Request completed successfully" } } } }, "401": { "description": "Unauthorized" } }, "summary": "List webhook deliveries", "tags": [ "webhooks" ] } }, "/v2/webhooks": { "post": { "description": "Creates a webhook for your account.\n\nThe response `data` includes a signing `secret` (22 characters from the base64url alphabet: A–Z, a–z, 0–9, `-`, `_`). The secret is shown only in this response and is not returned when the webhook is read later, so store it securely immediately.\n\nFor each delivery, TimeToCargo sends a `POST` request to your `callback_url`. The request contains a `WebhookOutgoingPayload` JSON object and these headers:\n- `x-timetocargo-signature` — HMAC SHA-256 signature of `timestamp + '.' + rawBody`, prefixed with `sha256=`;\n- `x-timetocargo-timestamp` — Unix timestamp used to generate the signature;\n- `x-timetocargo-event-id` — unique event ID matching `payload.id`;\n- `x-timetocargo-delivery-id` — unique delivery attempt ID.", "operationId": "WebhooksPublicV2Controller_create_v2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookDto" }, "example": { "callback_url": "https://example.com/webhooks/timetocargo", "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": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "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": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Status description" } } }, "example": { "success": true, "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/timetocargo", "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": "Request completed successfully" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Service Unavailable" } }, "summary": "Create webhook", "tags": [ "webhooks" ] }, "get": { "operationId": "WebhooksPublicV2Controller_list_v2", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "status", "status_description" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "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": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Status description" } } }, "example": { "success": true, "data": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/timetocargo", "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": "Request completed successfully" } } } }, "401": { "description": "Unauthorized" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "summary": "List webhooks", "tags": [ "webhooks" ] } }, "/v2/webhooks/{id}": { "get": { "operationId": "WebhooksPublicV2Controller_get_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook 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": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "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": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Status description" } } }, "example": { "success": true, "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/timetocargo", "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": "Request completed successfully" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" } }, "summary": "Get webhook", "tags": [ "webhooks" ] }, "patch": { "operationId": "WebhooksPublicV2Controller_update_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook 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": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "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": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Status description" } } }, "example": { "success": true, "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/timetocargo", "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": "Request completed successfully" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" } }, "summary": "Update webhook", "tags": [ "webhooks" ], "description": "Updates the `callback_url`, activation status, and subscribed event types. With `regenerate_secret=true`, the response `data` includes the new `secret`. It is shown only in that response and is not returned when the webhook is read later." }, "delete": { "operationId": "WebhooksPublicV2Controller_delete_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook 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": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "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": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Status description" } } }, "example": { "success": true, "data": null, "status": "OK", "status_description": "Request completed successfully" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" } }, "summary": "Delete webhook", "tags": [ "webhooks" ] } }, "/v2/webhooks/{id}/test": { "post": { "description": "Sends a `tracking.test` event to your `callback_url`.", "operationId": "WebhooksPublicV2Controller_test_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook 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": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "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": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Request completed successfully", "description": "Status description" } } }, "examples": { "success": { "value": { "success": true, "data": { "success": true, "http_status": 200 }, "status": "OK", "status_description": "Request completed successfully" } }, "failure": { "value": { "success": true, "data": { "success": false, "http_status": 500, "error_message": "fetch failed" }, "status": "OK", "status_description": "Request completed successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" } }, "summary": "Send test webhook", "tags": [ "webhooks" ] } } }, "webhooks": { "trackingWebhookDelivery": { "post": { "summary": "Receive tracking event", "tags": [ "webhooks" ], "description": "When an event you subscribed to occurs, TimeToCargo sends a `POST` request to your `callback_url`.\n\nReturn `200 OK` as soon as you receive the event. If processing takes time, enqueue the event, send the response, and then process it asynchronously. TimeToCargo waits up to 10 seconds for a response.\n\nDelivery succeeds with any `2xx` status. TimeToCargo retries after `408`, `409`, `425`, `429`, and `5xx` statuses, as well as timeouts and DNS or network errors. It does not retry after `400`, `401`, `403`, `404`, or `422`. After a `429` response, TimeToCargo honors the `Retry-After` header when present. Each delivery can have up to five attempts.\n\nTo verify the source of the request, use the webhook secret and the `x-timetocargo-timestamp` and `x-timetocargo-signature` headers. The signature is an HMAC SHA-256 digest of `timestamp + '.' + rawBody`, prefixed with `sha256=`. Use the unchanged request body as `rawBody`. Signature verification is optional, but recommended.\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.TIMETOCARGO_WEBHOOK_SECRET;\n\nif (!secret) {\n throw new Error('TIMETOCARGO_WEBHOOK_SECRET is not set');\n}\n\nfunction queueWebhook(payload: unknown): void {\n // Enqueue the event, save it to your database,\n // or pass it to another service for processing.\n console.log('Webhook received from TimeToCargo:', payload);\n}\n\napp.post('/webhooks/timetocargo', express.raw({ type: 'application/json' }), (req, res) => {\n const timestamp = req.header('x-timetocargo-timestamp');\n const signature = req.header('x-timetocargo-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('Webhook server is running on port 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[\"TIMETOCARGO_WEBHOOK_SECRET\"].encode()\n\n\ndef enqueue_webhook(payload: dict) -> None:\n # Enqueue the event, save it to your database,\n # or pass it to another service for processing.\n print(\"Webhook received from TimeToCargo:\", payload)\n\n\n@app.post(\"/webhooks/timetocargo\")\nasync def timetocargo_webhook(request: Request):\n body = await request.body()\n\n timestamp = request.headers.get(\"x-timetocargo-timestamp\")\n signature = request.headers.get(\"x-timetocargo-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-timetocargo-signature", "in": "header", "required": true, "description": "HMAC SHA-256 signature of `timestamp + '.' + rawBody`, prefixed with `sha256=`. Use the unchanged request body as `rawBody`.", "schema": { "type": "string", "example": "sha256=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "example": "sha256=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, { "name": "x-timetocargo-timestamp", "in": "header", "required": true, "description": "Unix timestamp used to generate the signature", "schema": { "type": "string", "example": "1783512000" }, "example": "1783512000" }, { "name": "x-timetocargo-event-id", "in": "header", "required": true, "description": "Unique event ID matching `payload.id`", "schema": { "type": "string", "format": "uuid", "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, "example": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa" }, { "name": "x-timetocargo-delivery-id", "in": "header", "required": true, "description": "Unique delivery attempt ID", "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": "Delivery failed: the server returned `400 Bad Request`. TimeToCargo will not retry it." }, "401": { "description": "Delivery failed: the server returned `401 Unauthorized`. TimeToCargo will not retry it." }, "403": { "description": "Delivery failed: the server returned `403 Forbidden`. TimeToCargo will not retry it." }, "404": { "description": "Delivery failed: the server returned `404 Not Found`. TimeToCargo will not retry it." }, "408": { "description": "The server returned `408 Request Timeout`. TimeToCargo will retry the delivery if attempts remain." }, "409": { "description": "The server returned `409 Conflict`. TimeToCargo will retry the delivery if attempts remain." }, "422": { "description": "Delivery failed: the server returned `422 Unprocessable Content`. TimeToCargo will not retry it." }, "425": { "description": "The server returned `425 Too Early`. TimeToCargo will retry the delivery if attempts remain." }, "429": { "description": "The server returned `429 Too Many Requests`. TimeToCargo will retry the delivery and honor the `Retry-After` header when present." }, "2XX": { "description": "Delivery succeeded. Any `2xx` response marks the webhook as delivered. Return `200 OK` as soon as you receive the event." }, "5XX": { "description": "The server returned a `5xx` status. TimeToCargo will retry the delivery if attempts remain." }, "default": { "description": "TimeToCargo will not retry after any other status except `2xx`. Network, DNS, and connection errors and delivery timeouts are handled separately and will be retried." } } } } }, "info": { "title": "API reference", "description": "Retrieve shipment data using a container, bill of lading, or booking number with the TimeToCargo API.", "version": "2.1", "contact": { "name": "TimeToCargo Team", "url": "https://timetocargo.com", "email": "info@timetocargo.com" } }, "tags": [ { "name": "companies", "x-displayName": "Companies" }, { "name": "tracking-batch", "x-displayName": "Batch tracking" }, { "name": "tracking", "x-displayName": "Single shipment tracking" }, { "name": "shipments", "x-displayName": "Shipment management" }, { "name": "apikey", "x-displayName": "API keys" }, { "name": "webhooks", "x-displayName": "Webhook management" } ], "servers": [ { "url": "https://tracking.timetocargo.com" } ], "components": { "schemas": { "ApiKey": { "type": "object", "properties": { "creation_date": { "format": "date-time", "type": "string", "description": "API-key creation date in the format YYYY-MM-DDThh:mm:ss.SSSZ", "example": "2023-03-23T21:49:43.000Z" }, "api_key": { "type": "string", "format": "uuid", "description": "API-key value", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "requests_remaining_count": { "type": [ "number", "null" ], "description": "The remaining number of shipments available to track with this API key", "example": 45 } }, "required": [ "creation_date", "api_key", "requests_remaining_count" ] }, "ApiKeyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "data": { "description": "API-key info", "allOf": [ { "$ref": "#/components/schemas/ApiKey" } ] } }, "required": [ "success", "data" ] }, "LocWithDate": { "type": "object", "properties": { "location": { "type": [ "number", "null" ], "description": "Location identifier. See locations", "example": 0 }, "terminal": { "type": [ "number", "null" ], "description": "Terminal identifier. See terminals.", "example": 0 }, "date": { "type": [ "string", "null" ], "description": "Date in the format 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": "Short company name", "example": "MSC" }, "full_name": { "type": "string", "description": "Full company name", "example": "Mediterranean Shipping Company" }, "url": { "type": "string", "description": "Link to the company website", "example": "https://www.msc.com/" }, "scacs": { "description": "Carrier SCAC codes", "example": [ "MEDU", "MSCU" ], "type": "array", "items": { "type": "string" } } }, "required": [ "name", "full_name", "url", "scacs" ] }, "Summary": { "type": "object", "properties": { "origin": { "description": "Origin", "allOf": [ { "$ref": "#/components/schemas/LocWithDate" } ] }, "pol": { "description": "Port of loading", "allOf": [ { "$ref": "#/components/schemas/LocWithDate" } ] }, "pod": { "description": "Port of discharge", "allOf": [ { "$ref": "#/components/schemas/LocWithDate" } ] }, "destination": { "description": "Destination", "allOf": [ { "$ref": "#/components/schemas/LocWithDate" } ] }, "company": { "description": "Carrier", "allOf": [ { "$ref": "#/components/schemas/CompanyInfo" } ] } }, "required": [ "origin", "pol", "pod", "destination", "company" ] }, "RouteLocation": { "type": "object", "properties": { "id": { "type": "number", "description": "Location identifier. Used in TrackingEvent and LocWithDate. Indexing starts from zero.", "example": 0 }, "name": { "type": [ "string", "null" ], "description": "Location name or city", "example": "Gothenburg" }, "state": { "type": [ "string", "null" ], "description": "State/region", "example": "Halland" }, "terminal": { "type": [ "string", "null" ], "description": "Terminal/port/warehouse", "example": "Port of Gothenburg", "deprecated": true }, "country": { "type": [ "string", "null" ], "description": "Country", "example": "Sweden" }, "lat": { "type": [ "number", "null" ], "description": "Latitude", "example": 57.70887 }, "lng": { "type": [ "number", "null" ], "description": "Longitude", "example": 11.97456 } }, "required": [ "id", "name", "state", "terminal", "country", "lat", "lng" ] }, "RouteTerminal": { "type": "object", "properties": { "id": { "type": "number", "description": "Terminal identifier. Used in TrackingEvent and LocWithDate. Indexing starts from zero.", "example": 0 }, "name": { "type": [ "string", "null" ], "description": "Terminal/port/warehouse", "example": "Port of Gothenburg" } }, "required": [ "id", "name" ] }, "TrackingEvent": { "type": "object", "properties": { "location": { "type": [ "number", "null" ], "description": "Location identifier", "example": 0 }, "terminal": { "type": [ "number", "null" ], "description": "Terminal identifier", "example": 0 }, "status": { "type": [ "string", "null" ], "description": "Event name / status", "example": "On Board" }, "status_code": { "type": [ "string", "null" ], "description": "Event status code. \n \n CEP: Container empty to shipper.\n CPS: Container pickup at shipper.\n CGI: Gate in.\n CLL: Container loaded at first port of loading.\n VDL: Vessel departure from first port of loading.\n VAT: Vessel arrival at transshipment port.\n CDT: Container discharge at transshipment port.\n TSD: Transshipment delay.\n CLT: Container loaded at transshipment port.\n VDT: Vessel departure from transshipment port.\n VAD: Vessel arrival at final port of discharge.\n CDD: Container discharge at final port of discharge.\n CGO: Gate out.\n CDC: Container delivery to consignee.\n CER: Container empty return to depot.\n LTS: Land transshipment.\n BTS: Barge transshipment.\n UNK: Unknown.\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": "Date in the format YYYY-MM-DDThh:mm:ss", "example": "2023-10-25T11:11:11" }, "actual": { "type": [ "boolean", "null" ], "description": "true: the event has occurred and date is actual. false: the event is expected and its date comes from the carrier", "example": false }, "vessel": { "type": [ "string", "null" ], "description": "Vessel name", "example": "Evergreen Teresa" }, "voyage": { "type": [ "string", "null" ], "description": "Voyage", "example": "V. 284" } }, "required": [ "location", "terminal", "status", "status_code", "date", "actual", "vessel", "voyage" ] }, "ContainerInfo": { "type": "object", "properties": { "number": { "type": "string", "description": "Container number", "example": "TCKU7858986" }, "type": { "type": [ "string", "null" ], "description": "Container type", "example": "40' Dry" }, "events": { "description": "Actual and expected shipment events. Events are ordered newest to oldest when all dates are present. If any date is missing, the carrier’s order is preserved.", "type": "array", "items": { "$ref": "#/components/schemas/TrackingEvent" } } }, "required": [ "number", "type", "events" ] }, "RouteSection": { "type": "object", "properties": { "path": { "description": "Route segment coordinates between two locations. Each point is a numeric [lat, lng] pair.", "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": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number" } } }, "type": { "type": "string", "description": "Whether the route segment is land or sea", "enum": [ "sea", "land" ], "example": "sea" } }, "required": [ "path", "type" ] }, "RouteInfo": { "type": "object", "properties": { "route": { "description": "Transportation route represented as an array of path segments between neighboring locations", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/RouteSection" } }, "current_position": { "type": [ "array", "null" ], "description": "Current container position as a [lat, lng] coordinate pair.", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "example": [ 32.284501, 31.232806 ] }, "last_updated": { "type": [ "string", "null" ], "description": "Date when the container position was last updated in the format YYYY-MM-DDThh:mm:ss", "example": "2023-10-25T11:11:11" }, "course": { "type": [ "number", "null" ], "description": "Current vessel course", "example": 247.34 } }, "required": [ "route", "current_position", "last_updated", "course" ] }, "ShipmentTrackingMetadataDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "Unique tracking identifier (UUID)" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "example": "2025-06-29T14:12:00.000Z", "description": "Tracking end date in ISO format" }, "status": { "type": "string", "example": "ACTIVE", "description": "Tracking status" }, "note": { "type": [ "string", "null" ], "example": "Order 4521", "description": "User note for the tracking (up to 40 characters)", "maxLength": 40 }, "created_at": { "type": "string", "format": "date-time", "example": "2025-06-29T14:12:00.000Z", "description": "Tracking creation date in ISO format" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-06-30T06:00:00.000Z", "description": "Tracking info update date in ISO format" } }, "required": [ "id", "end_date", "status", "note", "created_at", "updated_at" ] }, "TrackByDocumentOrContainerShipmentDto": { "type": "object", "properties": { "summary": { "description": "General transport information", "allOf": [ { "$ref": "#/components/schemas/Summary" } ] }, "locations": { "description": "Route locations", "type": "array", "items": { "$ref": "#/components/schemas/RouteLocation" } }, "terminals": { "description": "Route terminals", "type": "array", "items": { "$ref": "#/components/schemas/RouteTerminal" } }, "containers": { "description": "Containers and their shipment events", "type": "array", "items": { "$ref": "#/components/schemas/ContainerInfo" } }, "route_info": { "description": "Route information", "oneOf": [ { "$ref": "#/components/schemas/RouteInfo" }, { "type": "null" } ] }, "shipment_status": { "type": "string", "description": "Shipment status. \n \n IN_TRANSIT: Shipment in progress.\n DELIVERED: Container delivered to destination.\n UNKNOWN: Status has not been determined.\n STUCK: The shipment is delayed.\n ", "example": "IN_TRANSIT", "enum": [ "IN_TRANSIT", "DELIVERED", "UNKNOWN", "STUCK" ] }, "references": { "type": "object", "description": "Booking and bill of lading numbers related to the shipment", "properties": { "booking_numbers": { "type": "array", "description": "Booking numbers", "items": { "type": "string" }, "example": [ "2315887441" ] }, "bill_of_lading_numbers": { "type": "array", "description": "Bill of lading numbers", "items": { "type": "string" }, "example": [ "MEDUH1234567" ] } }, "required": [ "booking_numbers", "bill_of_lading_numbers" ] }, "tracking_metadata": { "description": "Tracking record details. May be null if a tracking record has not been created.", "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": "Number type used for the search" }, "value": { "type": "string", "example": "TCKU7858986", "description": "Number used for the search" } }, "required": [ "type", "value" ] }, "TrackingRequestEchoDto": { "type": "object", "properties": { "track_number": { "description": "Number and type used for the search", "allOf": [ { "$ref": "#/components/schemas/TrackingRequestTrackNumberDto" } ] }, "company": { "type": "string", "example": "MEDU", "description": "Requested company (SCAC) or AUTO" } }, "required": [ "track_number", "company" ] }, "TrackingResult": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "data": { "description": "Transportation information and tracking metadata (same as 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": "Tracking response status" }, "status_description": { "type": [ "string", "null" ], "example": "Information found", "description": "Status description" }, "request": { "description": "Original batch item: number, type, and requested company", "allOf": [ { "$ref": "#/components/schemas/TrackingRequestEchoDto" } ], "example": { "track_number": { "type": "container", "value": "TCKU7858986" }, "company": "MEDU" } } }, "required": [ "success", "data", "status", "status_description" ] }, "PublicTrackingDataDto": { "type": "object", "properties": { "summary": { "description": "General transport information", "allOf": [ { "$ref": "#/components/schemas/Summary" } ] }, "locations": { "description": "Route locations", "type": "array", "items": { "$ref": "#/components/schemas/RouteLocation" } }, "terminals": { "description": "Route terminals", "type": "array", "items": { "$ref": "#/components/schemas/RouteTerminal" } }, "containers": { "description": "Containers and their shipment events", "type": "array", "items": { "$ref": "#/components/schemas/ContainerInfo" } }, "route_info": { "description": "Route information", "oneOf": [ { "$ref": "#/components/schemas/RouteInfo" }, { "type": "null" } ] }, "shipment_status": { "type": "string", "description": "Shipment status.", "example": "IN_TRANSIT", "enum": [ "IN_TRANSIT", "DELIVERED", "UNKNOWN", "STUCK" ] }, "references": { "type": "object", "description": "Booking and bill of lading numbers related to the shipment", "properties": { "booking_numbers": { "type": "array", "description": "Booking numbers", "items": { "type": "string" }, "example": [ "2315887441" ] }, "bill_of_lading_numbers": { "type": "array", "description": "Bill of lading numbers", "items": { "type": "string" }, "example": [ "MEDUH1234567" ] } }, "required": [ "booking_numbers", "bill_of_lading_numbers" ] } }, "required": [ "summary", "locations", "terminals", "containers", "route_info", "shipment_status" ] }, "ShipmentTrackingResultDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "data": { "description": "Tracking result without subscription metadata", "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": "Tracking response status" }, "status_description": { "type": [ "string", "null" ], "example": "Information found", "description": "Status description" } }, "required": [ "success", "data", "status", "status_description" ] }, "ShipmentTrackedItemDto": { "type": "object", "properties": { "track_number": { "type": "string", "example": "MSCU1234567", "description": "Tracking number" }, "track_number_type": { "type": "string", "enum": [ "container", "bl", "bk" ], "example": "container", "description": "Number type: container, bill of lading, or booking" }, "company_id": { "type": [ "number", "null" ], "example": 60, "description": "Carrier ID, if known" }, "data": { "description": "Tracking result. In nested data on success: transportation details; containers can include one or multiple container entries (for BL/BK: multiple).", "oneOf": [ { "$ref": "#/components/schemas/ShipmentTrackingResultDto" }, { "type": "null" } ] }, "updated_at": { "format": "date-time", "type": [ "string", "null" ], "example": "2026-04-08T12:08:55.307Z" }, "checked_at": { "format": "date-time", "type": [ "string", "null" ], "example": "2026-04-08T12:08:55.307Z" }, "company_name": { "type": [ "string", "null" ], "example": "Mediterranean Shipping Company", "description": "Company name (if the company is known)" } }, "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": "Tracking identifier (shipment)" }, "tracked_item": { "description": "Tracked entity data (without balance_id / tracked_item_id / id)", "allOf": [ { "$ref": "#/components/schemas/ShipmentTrackedItemDto" } ] }, "start_date": { "format": "date-time", "type": [ "string", "null" ], "example": "2026-04-08T12:26:56.940Z" }, "end_date": { "format": "date-time", "type": [ "string", "null" ], "example": "2026-04-12T09:18:49.395Z" }, "status": { "type": "string", "example": "ACTIVE", "description": "Tracking status as string" }, "note": { "type": [ "string", "null" ], "example": "Order 4521", "description": "User note for the tracking (up to 40 characters)", "maxLength": 40 }, "created_at": { "format": "date-time", "type": "string", "example": "2026-04-08T12:08:54.569Z" }, "track_number": { "type": "string", "example": "MSCU1234567", "description": "Tracking number (duplicates tracked_item.track_number for convenience)" } }, "required": [ "id", "tracked_item", "start_date", "end_date", "status", "note", "created_at", "track_number" ] }, "GetShipmentsResponseDataDto": { "type": "object", "properties": { "data": { "description": "Shipments information", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PreviewShipmentsInfoDto" } } }, "required": [ "data" ] }, "ShipmentsPaginationMetaDto": { "type": "object", "properties": { "itemsPerPage": { "type": "number", "example": 50, "description": "Number of items per page" }, "totalItems": { "type": "number", "example": 145, "description": "Total number of items" }, "currentPage": { "type": "number", "example": 2, "description": "Current page" }, "totalPages": { "type": "number", "example": 3, "description": "Total number of pages" }, "sortBy": { "type": "array", "example": [ [ "created_at", "DESC" ], [ "id", "DESC" ] ], "description": "Applied sorting" }, "filter": { "type": "object", "example": { "status": "$eq:ACTIVE" }, "description": "Applied filters" } }, "required": [ "itemsPerPage", "totalItems", "currentPage", "totalPages", "sortBy" ] }, "ShipmentsPaginationLinksDto": { "type": "object", "properties": { "first": { "type": "string", "example": "/v2/shipments?page=1&limit=50&status=ACTIVE", "description": "Link to the first page" }, "previous": { "type": [ "string", "null" ], "example": "/v2/shipments?page=1&limit=50&status=ACTIVE", "description": "Link to the previous page" }, "current": { "type": "string", "example": "/v2/shipments?page=2&limit=50&status=ACTIVE", "description": "Link to the current page" }, "next": { "type": [ "string", "null" ], "example": "/v2/shipments?page=3&limit=50&status=ACTIVE", "description": "Link to the next page" }, "last": { "type": "string", "example": "/v2/shipments?page=3&limit=50&status=ACTIVE", "description": "Link to the last page" } }, "required": [ "current" ] }, "GetShipmentsPaginatedDataDto": { "type": "object", "properties": { "data": { "description": "Shipments information", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PreviewShipmentsInfoDto" } }, "meta": { "description": "Pagination details", "allOf": [ { "$ref": "#/components/schemas/ShipmentsPaginationMetaDto" } ] }, "links": { "description": "Page links", "allOf": [ { "$ref": "#/components/schemas/ShipmentsPaginationLinksDto" } ] } }, "required": [ "data", "meta", "links" ] }, "GetShipmentsResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "data": { "description": "Shipments information with pagination", "type": [ "object", "null" ], "allOf": [ { "$ref": "#/components/schemas/GetShipmentsPaginatedDataDto" } ] }, "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" ], "description": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Information found", "description": "Status description" } }, "required": [ "success", "data", "status", "status_description" ] }, "RemoveShipmentsRequestDto": { "type": "object", "properties": { "shipmentIds": { "example": [ "9ff48bf7-4541-49e2-947c-c269200e030f", "fb8936b9-ff16-4776-8710-d4073ab06d1e", "2305a40b-97b2-4c1b-94c4-6d9416b22bde" ], "description": "List of UUIDs of shipments that you want to delete", "type": "array", "items": { "type": "string" } } }, "required": [ "shipmentIds" ] }, "RemovedAndArchivedShipmentsData": { "type": "object", "properties": { "deleted": { "example": [ "9ff48bf7-4541-49e2-947c-c269200e030f", "fb8936b9-ff16-4776-8710-d4073ab06d1e" ], "description": "Deleted tracking record IDs", "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "archived": { "example": [ "2305a40b-97b2-4c1b-94c4-6d9416b22bde" ], "description": "Archived tracking record IDs", "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } } }, "required": [ "deleted", "archived" ] }, "RemoveShipmentsResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "data": { "description": "Information about deleted and archived shipments", "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_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE" ], "description": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Shipments have been successfully removed", "description": "Status description" } }, "required": [ "success", "data", "status", "status_description" ] }, "CompanyTrackingCapabilitiesDto": { "type": "object", "properties": { "scac": { "type": "string", "description": "Carrier SCAC code", "example": "APLU" }, "cn": { "type": "boolean", "description": "Container tracking support (CN)", "example": true }, "bl": { "type": "boolean", "description": "Bill of lading tracking support (BL)", "example": true }, "bk": { "type": "boolean", "description": "Booking tracking support (BK)", "example": true } }, "required": [ "scac", "cn", "bl", "bk" ] }, "TrackedItemRequestDto": { "type": "object", "properties": { "company": { "type": "string", "examples": [], "description": "Carrier SCAC code. AUTO is available only for type=container. Use GET /v2/companies to retrieve codes and supported tracking types." }, "track_number": { "examples": { "container": { "summary": "Container", "value": { "value": "CSNU6184414", "type": "container" } }, "bl": { "summary": "Bill of lading", "value": { "value": "AKKNEM25072638", "type": "bl" } }, "bk": { "summary": "Booking", "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": "Tracking number (container / booking / bill of lading)" } }, "required": [ "company", "track_number" ] }, "TrackMultipleItemsRequestDto": { "type": "object", "properties": { "tracked_items": { "description": "Array of tracking numbers (max 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" }, "maxItems": 500 } }, "required": [ "tracked_items" ] }, "TrackViaStatusDto": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "Task ID (UUID)" } }, "required": [ "task_id" ] }, "TrackMultipleItemsResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "data": { "description": "Details of the created task", "oneOf": [ { "$ref": "#/components/schemas/TrackViaStatusDto" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "API_KEY_WRONG", "API_KEY_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE" ], "description": "Request execution status" } }, "required": [ "success", "data", "status" ] }, "TrackingStatusDataDto": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "Batch tracking task ID" }, "status": { "type": "string", "example": "PROCESSED", "enum": [ "CREATED", "HANDLING", "PROCESSED" ], "description": "The current status of the tracking task: CREATED (task created, awaiting processing), HANDLING (currently being processed), PROCESSED (completed, results available in the results field)" }, "results": { "type": "array", "items": { "description": "Tracking results with details. Available only when processing is completed (status = PROCESSED). Structure matches GET /tracking single-tracking results. Each item is always an object: a successful result or INFO_NOT_FOUND, never null.", "$ref": "#/components/schemas/TrackingResult" }, "description": "Each number’s original request, success, status, and tracking data. Available after the task reaches PROCESSED. Check each result separately." } }, "required": [ "task_id", "status" ] }, "TrackingStatusResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "data": { "description": "Task state and tracking results, when processing is complete", "oneOf": [ { "$ref": "#/components/schemas/TrackingStatusDataDto" }, { "type": "null" } ] }, "status": { "type": "string", "example": "OK", "enum": [ "OK", "WRONG_PARAMS", "UNEXPECTED_ERROR", "API_KEY_WRONG", "API_KEY_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE" ], "description": "Request execution status" } }, "required": [ "success", "data", "status" ] }, "TrackByDocumentOrContainerResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "data": { "description": "Tracking information", "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_LIMIT_REACHED", "API_KEY_RATE_LIMIT", "LOW_BALANCE", "SERVICE_UNAVAILABLE" ], "description": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Information found", "description": "Status description" }, "request": { "description": "Original tracking request: number, type, and requested company", "allOf": [ { "$ref": "#/components/schemas/TrackingRequestEchoDto" } ], "example": { "track_number": { "type": "container", "value": "TCKU7858986" }, "company": "MEDU" } } }, "required": [ "success", "data", "status", "status_description" ] }, "CreateWebhookDto": { "type": "object", "properties": { "callback_url": { "type": "string", "format": "uri", "description": "URL where TimeToCargo will send webhooks", "example": "https://example.com/webhooks/timetocargo" }, "is_active": { "type": "boolean", "default": true, "description": "Whether the webhook receives regular events. You can send a test delivery to an inactive webhook.", "example": true }, "event_types": { "type": "array", "minItems": 1, "description": "Event types to deliver. If omitted, the webhook receives all public event types. `tracking.test` is always available for test deliveries.", "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" ] } }, "required": [ "callback_url" ] }, "UpdateWebhookDto": { "type": "object", "properties": { "callback_url": { "type": "string", "format": "uri", "description": "URL where TimeToCargo will send webhooks", "example": "https://example.com/webhooks/timetocargo" }, "is_active": { "type": "boolean", "description": "Whether the webhook receives regular events. You can send a test delivery to an inactive webhook.", "example": true }, "event_types": { "type": "array", "minItems": 1, "description": "Event types to deliver. If omitted, the event type list remains unchanged. `tracking.test` is always available for test deliveries.", "items": { "type": "string", "enum": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ] } }, "regenerate_secret": { "type": "boolean", "default": false, "description": "Whether to generate a new signing secret for webhook verification", "example": false } } }, "WebhookTrackNumber": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "container", "bl", "bk" ], "description": "Type of tracking number", "example": "container" }, "value": { "type": "string", "description": "Container, bill of lading, or booking number", "example": "MSBU6501445" } }, "required": [ "type", "value" ] }, "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" ] }, "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": "Always `null` for the account-level `tracking.auto_archiving` event", "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": [] } }, "WebhookOutgoingPayload": { "description": "JSON object sent to your `callback_url`. The shared fields are the same for every event; the contents of `data` depend on the event type.", "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" } } }, "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/timetocargo" }, "is_active": { "type": "boolean", "example": true }, "event_types": { "type": "array", "description": "Public event types subscribed to by this webhook. `tracking.test` is always available for test deliveries and is not included in this list.", "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": "Signing secret. Present only after webhook creation or when regenerate_secret=true; omitted from other responses.", "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" ] }, "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" ] }, "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" ] }, "WebhookRoute": { "type": "object", "description": "Route from the tracking summary: 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" ] }, "WebhookResource": { "type": [ "object", "null" ], "description": "Technical context for the tracked item. The value is `null` for account-level events such as `tracking.auto_archiving` and `tracking.test`.", "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" ] }, "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" ] }, "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" ] }, "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" ] }, "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" ] }, "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" ] }, "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" ] }, "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": "Last known location: the first available value from `event.location`, `route.destination`, or `route.pod`" }, "current_position": { "$ref": "#/components/schemas/WebhookCurrentPosition" }, "event": { "$ref": "#/components/schemas/WebhookTrackingEvent", "description": "Latest tracking event. Its location may differ from `final_location`." } }, "required": [ "shipment_status", "route", "final_location", "event", "current_position" ] }, "WebhookEmptyData": { "type": "object", "additionalProperties": false, "description": "Empty object used only for `tracking.test` events", "example": {} }, "WebhookAutoArchivingData": { "type": "object", "description": "Details about automatic archiving for the account.", "properties": { "auto_renewal_agreement": { "type": "boolean", "description": "Whether automatic subscription renewal is enabled for the user", "example": true } }, "required": [ "auto_renewal_agreement" ], "additionalProperties": false, "example": { "auto_renewal_agreement": true } }, "UpdateShipmentRequestDto": { "type": "object", "additionalProperties": false, "properties": { "note": { "type": "string", "maxLength": 40, "example": "Order 123", "description": "Note, limited to 40 characters including spaces and line breaks. Length is counted before trimming edges. To delete the note, send an empty string `\"note\": \"\"`. Null is not accepted as input." } }, "required": [ "note" ] }, "UpdateShipmentResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether processing succeeded. For tracking results, also check status: success=true does not mean data was found." }, "data": { "$ref": "#/components/schemas/PreviewShipmentsInfoDto", "description": "Updated shipment, including stored tracking data and route information. Does not trigger tracking." }, "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" ], "description": "Request execution status" }, "status_description": { "type": [ "string", "null" ], "example": "Information found", "description": "Status description" } }, "required": [ "success", "data", "status", "status_description" ] } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "api_key", "in": "query" } } }, "security": [ { "api_key": [] } ] }