{ "openapi": "3.0.1", "info": { "version": "0.0.1", "title": "Tracking Microservice", "description": "API for tracking containers, and managing webhooks for shipping events" }, "servers": [ { "url": "https://api.tracking.cif-consulting.co.uk", "description": "Production server" } ], "tags": [ { "name": "Account", "description": "Identity and usage-plan info for the calling API key." }, { "name": "Carrier Credentials", "description": "Store, verify, and clear your own carrier API credentials." }, { "name": "Webhooks", "description": "Configure and activate push delivery of tracking events to your own endpoint." }, { "name": "Subscriptions", "description": "Subscribe shipments for tracking and pull tracking data back." }, { "name": "Events", "description": "DCSA-standard event ingestion: how carriers push tracking events into the platform." }, { "name": "Metrics", "description": "Per-client carrier polling metrics." } ], "paths": { "/webhook/configure": { "get": { "operationId": "getWebhookConfig", "tags": [ "Webhooks" ], "summary": "Get current webhook configuration", "responses": { "200": { "description": "Webhook configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "targetUrl": { "type": "string" }, "activated": { "type": "boolean" }, "env": { "type": "string", "description": "Which credential environment the account is on (live or sandbox)." } } }, "examples": { "webhookConfigured": { "summary": "Webhook configured and active", "value": { "targetUrl": "https://domain.com/v1/tracking", "activated": true, "env": "live" } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] }, "post": { "operationId": "configureWebhook", "tags": [ "Webhooks" ], "summary": "Setup a webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureWebhook" }, "examples": { "setTargetUrl": { "summary": "Point the webhook at your endpoint", "value": { "targetUrl": "https://domain.com/v1/tracking" } } } } }, "required": true }, "responses": { "200": { "description": "Webhook configured successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "configured": { "summary": "Webhook configured", "value": { "message": "Successful Configuration" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "missingTargetUrl": { "summary": "targetUrl missing from the body", "value": { "message": "Missing Parameter 'targetUrl'" } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "callbacks": { "trackingEvent": { "{$request.body#/targetUrl}": { "post": { "summary": "Webhook notification payload sent when tracking events are received", "description": "When new tracking events are received for a subscription, this payload is POSTed to the configured webhook URL. The request includes an X-Hook-Signature header containing an HMAC-SHA256 signature for verification.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } } } }, "security": [ { "api_key": [] } ] } }, "/webhook/activate": { "post": { "operationId": "activateWebhook", "tags": [ "Webhooks" ], "summary": "Confirm a Webhook is operational", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateWebhook" }, "examples": { "confirmSecret": { "summary": "Confirm the webhook with your secret", "value": { "secret": "a1b2c3d4e5" } } } } }, "required": true }, "responses": { "200": { "description": "Webhook activated (or already active)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "activated": { "summary": "Webhook activated", "value": { "message": "Successful Activation" } }, "alreadyActive": { "summary": "Webhook was already active", "value": { "message": "Webhook already activated" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "missingSecret": { "summary": "secret missing from the body", "value": { "message": "Missing Parameter 'secret'" } }, "noWebhookConfigured": { "summary": "No webhook to activate", "value": { "message": "No Web-hook Configured" } }, "incorrectSecret": { "summary": "Secret does not match", "value": { "message": "Incorrect Secret" } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] } }, "/carrier/credentials": { "get": { "operationId": "getCarrierCredentials", "tags": [ "Carrier Credentials" ], "summary": "Get stored carrier credentials", "description": "Returns the carrier credentials stored against your account, keyed by SCAC code.", "responses": { "200": { "description": "Stored carrier credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "env": { "type": "string", "description": "Which credential environment the account is on (live or sandbox)." }, "carrierCredentials": { "$ref": "#/components/schemas/CarrierCredentials" } } }, "examples": { "twoCarriersConfigured": { "summary": "Credentials held for two carriers", "value": { "env": "live", "carrierCredentials": { "MAEU": { "clientId": "your-maersk-client-id", "clientSecret": "your-maersk-client-secret" }, "CMAU": { "apiKey": "your-cma-cgm-api-key" } } } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] }, "post": { "operationId": "saveCarrierCredentials", "tags": [ "Carrier Credentials" ], "summary": "Store or update your carrier API credentials", "description": "Upserts credentials per carrier: posting credentials for one SCAC leaves other carriers' stored credentials untouched, and re-posting a carrier replaces that carrier's set.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierCredentials" }, "examples": { "singleCarrier": { "summary": "Store Maersk credentials", "value": { "MAEU": { "clientId": "your-client-id", "clientSecret": "your-client-secret" } } }, "multipleCarriers": { "summary": "Store two carriers in one call", "value": { "MAEU": { "clientId": "your-client-id", "clientSecret": "your-client-secret" }, "CMAU": { "apiKey": "your-api-key" } } } } } }, "required": true }, "responses": { "200": { "description": "Credentials stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "stored": { "summary": "Credentials stored", "value": { "message": "Successful Configuration" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "notAnObject": { "summary": "Body is not per-carrier credentials", "value": { "message": "Body must be an object of per-carrier credentials" } }, "missingField": { "summary": "A carrier is missing a required field", "value": { "message": "Incomplete credentials for MAEU. Missing 'clientSecret'." } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] }, "delete": { "operationId": "deleteCarrierCredentials", "tags": [ "Carrier Credentials" ], "summary": "Clear carrier credentials", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "carriers" ], "properties": { "carriers": { "type": "array", "items": { "type": "string" }, "description": "List of SCAC codes to clear credentials for" } } }, "examples": { "clearOneCarrier": { "summary": "Clear stored Maersk credentials", "value": { "carriers": [ "MAEU" ] } } } } }, "required": true }, "responses": { "200": { "description": "Credentials cleared", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "cleared": { "summary": "Credentials removed", "value": { "message": "Credentials cleared" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "invalidList": { "summary": "carriers list missing or invalid", "value": { "message": "Missing or invalid 'carriers' list" } }, "unsupportedCarrier": { "summary": "Unknown SCAC code", "value": { "message": "Unsupported carrier 'ABCD'" } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] } }, "/carrier/health-check": { "post": { "operationId": "carrierHealthCheck", "tags": [ "Carrier Credentials" ], "summary": "Test connectivity to a carrier API using your own credentials", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "scacCode" ], "properties": { "scacCode": { "type": "string", "description": "SCAC code of the carrier to test" } } }, "examples": { "checkMaersk": { "summary": "Test connectivity to Maersk", "value": { "scacCode": "MAEU" } } } } }, "required": true }, "responses": { "200": { "description": "Health check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "scacCode": { "type": "string" }, "status": { "type": "string" }, "httpCode": { "type": "integer" } } }, "examples": { "connected": { "summary": "Carrier reachable with your credentials", "value": { "scacCode": "MAEU", "status": "OK", "httpCode": 200 } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "missingScac": { "summary": "scacCode missing or unsupported", "value": { "message": "Missing or unsupported 'scacCode'" } }, "noCredentials": { "summary": "No credentials stored for this carrier", "value": { "message": "No credentials configured for MAEU. Save your credentials first." } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] } }, "/subscriptions": { "get": { "operationId": "listSubscriptions", "tags": [ "Subscriptions" ], "summary": "Get all subscriptions", "parameters": [ { "name": "subscriptionStatus", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Status of subscriptions to be retrieved" }, { "name": "referencePrefix", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Prefix search on subscriptionReference (begins_with on the reference). Case-sensitive, left-anchored. Spans all statuses, so CLOSED/deleted subscriptions are also returned." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Opt-in pagination: maximum number of subscriptions to return per page (default 50, max 200). Omit limit and nextToken to return all subscriptions in one response." }, { "name": "nextToken", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from a previous response's nextToken; returns the next page of subscriptions." } ], "responses": { "200": { "description": "Subscription tracking data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionRecord" } }, "nextToken": { "type": "string", "description": "Present only when more pages exist; pass back as the nextToken query parameter to fetch the next page." } } }, "examples": { "allSubscriptions": { "summary": "Everything in one response (no pagination)", "value": { "subscriptions": [ { "subscriptionReference": "REF12345", "equipmentNumber": "ABCU1234567", "bookingNumber": "BN12345", "billNumber": "BL12345", "scacCode": "MAEU", "subscriptionCreationDate": "2023-06-01T09:00:00Z", "subscriptionExpiryDate": "2023-09-01T09:00:00Z", "subscriptionStatus": "OPEN", "connectionStatus": "CONNECTED" } ] } }, "pagedResponse": { "summary": "A page with more results to fetch", "value": { "subscriptions": [ { "subscriptionReference": "REF12345", "equipmentNumber": "ABCU1234567", "bookingNumber": "BN12345", "billNumber": "BL12345", "scacCode": "MAEU", "subscriptionCreationDate": "2023-06-01T09:00:00Z", "subscriptionExpiryDate": "2023-09-01T09:00:00Z", "subscriptionStatus": "OPEN", "connectionStatus": "CONNECTED" } ], "nextToken": "eyJwayI6ICJDT05TVU1FUiNhY21lIn0" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "invalidLimit": { "summary": "limit is not an integer", "value": { "message": "Query parameter 'limit' must be an integer" } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ], "description": "Returns every subscription on your account, with optional subscriptionStatus and referencePrefix filters and opt-in pagination." } }, "/subscription/{subscription_id}": { "get": { "operationId": "getSubscriptionByReference", "tags": [ "Subscriptions" ], "summary": "Get Subscription", "description": "Returns the subscription identified by the path reference, scoped to the calling consumer's API key.", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The subscription reference to retrieve" } ], "responses": { "200": { "description": "Subscription retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionRecord" }, "examples": { "openSubscription": { "summary": "An open, connected subscription", "value": { "subscriptionReference": "REF12345", "equipmentNumber": "ABCU1234567", "bookingNumber": "BN12345", "billNumber": "BL12345", "scacCode": "MAEU", "subscriptionCreationDate": "2023-06-01T09:00:00Z", "subscriptionExpiryDate": "2023-09-01T09:00:00Z", "subscriptionStatus": "OPEN", "connectionStatus": "CONNECTED" } } } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "notFound": { "summary": "No subscription with that reference", "value": { "message": "Subscription not found" } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] }, "delete": { "operationId": "deleteSubscriptionByReference", "tags": [ "Subscriptions" ], "summary": "Close a subscription", "description": "Marks the subscription CLOSED and stops carrier polling when no other open subscription shares the same shipment. The record is retained for audit and no longer blocks re-subscribing the same shipment.", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The subscription reference to delete" } ], "responses": { "200": { "description": "Subscription deleted (or already closed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "subscriptionReference": { "type": "string" }, "stoppedTracking": { "type": "boolean", "description": "True when carrier polling stopped; false when another open subscription still shares the shipment." }, "dateOfRequest": { "type": "string", "format": "date-time" } } }, "examples": { "deleted": { "summary": "Subscription closed, polling stopped", "value": { "message": "Subscription deleted", "subscriptionReference": "REF12345", "stoppedTracking": true, "dateOfRequest": "2023-06-15T10:30:00Z" } }, "alreadyClosed": { "summary": "Subscription was already closed", "value": { "message": "Subscription already closed", "subscriptionReference": "REF12345", "dateOfRequest": "2023-06-15T10:30:00Z" } } } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "dateOfRequest": { "type": "string", "format": "date-time" } } }, "examples": { "notFound": { "summary": "No subscription with that reference", "value": { "message": "Subscription not found", "dateOfRequest": "2023-06-15T10:30:00Z" } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] } }, "/subscription/equipment": { "post": { "operationId": "createEquipmentSubscription", "tags": [ "Subscriptions" ], "summary": "Create a tracking subscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "byContainer": { "summary": "Track by container number", "value": { "scacCode": "MAEU", "containerNumber": "ABCU1234567", "subscriptionReference": "REF12345" } }, "byBooking": { "summary": "Track by booking reference", "value": { "scacCode": "MAEU", "bookingNumber": "BN12345", "subscriptionReference": "REF12346" } }, "byBill": { "summary": "Track by bill of lading", "value": { "scacCode": "MAEU", "billNumber": "BL12345", "subscriptionReference": "REF12347" } } } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "dateOfRequest": { "type": "string", "format": "date-time" } } }, "examples": { "duplicateReference": { "summary": "Reference already in use", "value": { "message": "Subscription Reference Already Exists", "dateOfRequest": "2023-06-15T10:30:00Z" } } } } } }, "200": { "description": "Subscription created", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "subscriptionReference": { "type": "string" }, "dateOfRequest": { "type": "string", "format": "date-time" } } }, "examples": { "subscribed": { "summary": "Tracking started", "value": { "message": "Successfully Subscribed", "subscriptionReference": "REF12345", "dateOfRequest": "2023-06-15T10:30:00Z" } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] }, "get": { "operationId": "getEquipmentSubscriptions", "tags": [ "Subscriptions" ], "summary": "Get tracking data for a subscription", "parameters": [ { "name": "equipmentNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Container number to narrow the journey lookup." }, { "name": "bookingNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Booking reference of journey. Provide this or billNumber, not both." }, { "name": "billNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bill of lading of journey. Provide this or bookingNumber, not both." } ], "responses": { "200": { "description": "Journeys matching the reference, with their tracking events", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "equipmentNumber": { "type": "string" }, "scacCode": { "type": "string" }, "trackingStatus": { "type": "string" }, "lastLocation": { "type": "string" }, "POL": { "type": "string", "description": "Port of loading (UN/LOCODE)." }, "POD": { "type": "string", "description": "Port of discharge (UN/LOCODE)." }, "sourceEvents": { "type": "array", "items": { "$ref": "#/components/schemas/equipmentEvent" }, "description": "DCSA events as received from the carrier." }, "enhancedEvents": { "type": "array", "items": { "type": "object" }, "description": "Derived events added by the platform." }, "vesselEvents": { "type": "array", "items": { "type": "object" }, "description": "Vessel port-call events for the journey, where tracked." } } } }, "count": { "type": "integer" }, "dateOfRequest": { "type": "string", "format": "date-time" } } }, "examples": { "oneJourney": { "summary": "One container journey with its events", "value": { "results": [ { "equipmentNumber": "ABCU1234567", "scacCode": "MAEU", "trackingStatus": "OPEN", "lastLocation": "DEHAM", "POL": "CNSHA", "POD": "DEHAM", "sourceEvents": [ { "eventType": "EQUIPMENT", "eventClassifierCode": "ACT", "eventDateTime": "2023-06-15T10:30:00Z", "equipmentEventTypeCode": "LOAD", "equipmentReference": "ABCU1234567", "ISOEquipmentCode": "45G1", "emptyIndicatorCode": "LADEN", "carrierCode": "ABCU", "eventLocation": { "locationName": "Port of Hamburg", "UNLocationCode": "DEHAM" }, "transportCall": { "carrierVoyageNumber": "123W", "UNLocationCode": "DEHAM", "vessel": { "vesselIMONumber": "9321483", "vesselName": "MSC GULSUN" } }, "documentReferences": [ { "documentReferenceType": "BKG", "documentReferenceValue": "BN12345" }, { "documentReferenceType": "TRD", "documentReferenceValue": "BL12345" } ] } ], "enhancedEvents": [] } ], "count": 1, "dateOfRequest": "2023-06-15T10:30:00Z" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "dateOfRequest": { "type": "string", "format": "date-time" } } }, "examples": { "missingIdentifier": { "summary": "No reference provided", "value": { "message": "Must provide at least one of: equipmentNumber, bookingNumber, billNumber", "dateOfRequest": "2023-06-15T10:30:00Z" } }, "bothReferences": { "summary": "Booking and bill both provided", "value": { "message": "Cannot provide both bookingNumber and billNumber please provide one", "dateOfRequest": "2023-06-15T10:30:00Z" } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] } }, "/events": { "post": { "operationId": "createEvent", "tags": [ "Events" ], "summary": "Post a tracking event", "description": "Carrier Endpoint to Provide a DCSA EVENT_DOMAIN 2.0.2 equipment or transport event.", "externalDocs": { "description": "DCSA EVENT_DOMAIN 2.0.2 spec", "url": "https://app.swaggerhub.com/domains/dcsaorg/EVENT_DOMAIN/2.0.2" }, "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/equipmentEvent" }, { "$ref": "#/components/schemas/transportEvent" } ] }, "examples": { "equipmentEvent": { "summary": "Container loaded onto vessel", "value": { "eventType": "EQUIPMENT", "eventClassifierCode": "ACT", "eventDateTime": "2023-06-15T10:30:00Z", "equipmentEventTypeCode": "LOAD", "equipmentReference": "ABCU1234567", "ISOEquipmentCode": "45G1", "emptyIndicatorCode": "LADEN", "carrierCode": "ABCU", "eventLocation": { "locationName": "Port of Hamburg", "UNLocationCode": "DEHAM" }, "transportCall": { "carrierVoyageNumber": "123W", "UNLocationCode": "DEHAM", "vessel": { "vesselIMONumber": "9321483", "vesselName": "MSC GULSUN" } }, "documentReferences": [ { "documentReferenceType": "BKG", "documentReferenceValue": "BN12345" }, { "documentReferenceType": "TRD", "documentReferenceValue": "BL12345" } ] } }, "transportEvent": { "summary": "Vessel arrival", "value": { "eventType": "TRANSPORT", "eventClassifierCode": "ACT", "eventDateTime": "2023-06-16T04:00:00Z", "transportEventTypeCode": "ARRI", "equipmentReference": "ABCU1234567", "carrierCode": "ABCU", "transportCall": { "carrierVoyageNumber": "123W", "UNLocationCode": "DEHAM", "vessel": { "vesselIMONumber": "9321483", "vesselName": "MSC GULSUN" }, "location": { "locationName": "Port of Hamburg", "UNLocationCode": "DEHAM" } }, "documentReferences": [ { "documentReferenceType": "BKG", "documentReferenceValue": "BN12345" } ] } } } } }, "required": true }, "responses": { "200": { "description": "Event accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "accepted": { "summary": "Event stored", "value": { "message": "Successfully Added Event" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "noBody": { "summary": "Empty request body", "value": { "message": "No event body" } }, "wrongEventType": { "summary": "eventType is not EQUIPMENT or TRANSPORT", "value": { "message": "No equipment or transport event provided" } }, "missingEquipmentReference": { "summary": "equipmentReference missing", "value": { "message": "equipmentReference is required" } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] } }, "/account": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "Get Account Information", "responses": { "200": { "description": "Account info for the calling key", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientName": { "type": "string", "nullable": true, "description": "Canonical client slug parsed from the key name" }, "displayName": { "type": "string", "description": "Human-readable account name" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "authMethod": { "type": "string", "enum": [ "api-key" ] }, "usagePlan": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "displayName": { "type": "string", "description": "Friendly name, e.g. 'Client', 'Carrier'" } } } } }, "examples": { "liveClientKey": { "summary": "A live client key on the Client usage plan", "value": { "clientName": "acme", "displayName": "Acme Logistics", "environment": "live", "authMethod": "api-key", "usagePlan": { "id": "a1b2c3", "name": "prod-tms-backend-client-usage-plan", "displayName": "Client" } } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] } }, "/carrier/metrics": { "get": { "operationId": "getCarrierMetrics", "tags": [ "Metrics" ], "summary": "Per-client carrier polling metrics", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90 }, "description": "Number of days to aggregate over (default 7, clamped 1-90)." } ], "responses": { "200": { "description": "Carrier polling metrics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "integer" }, "carriers": { "type": "array", "items": { "type": "object" }, "description": "Per-carrier rollups, sorted worst-first. Empty where polling metrics are not collected." } } }, "examples": { "sevenDayWindow": { "summary": "Seven-day rollup for one carrier", "value": { "window": 7, "carriers": [ { "scacCode": "MAEU", "attempts": 342, "success": 305, "noData": 20, "errors": 17, "successRate": 0.89, "state": "degraded", "lastPolledAt": "2023-06-15T10:30:00Z", "lastOutcome": "success", "series": [ { "date": "2023-06-14", "attempts": 48, "success": 44, "errors": 4 }, { "date": "2023-06-15", "attempts": 51, "success": 47, "errors": 4 } ] } ] } } } } } }, "403": { "description": "Forbidden: the x-api-key header is missing or the key is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessage" }, "examples": { "missingOrInvalidKey": { "summary": "Missing or invalid API key", "value": { "message": "Forbidden" } } } } } } }, "security": [ { "api_key": [] } ] } } }, "components": { "schemas": { "ActivateWebhook": { "title": "Activate Webhook Data", "description": "Data needed to activate a webhook.", "type": "object", "properties": { "secret": { "type": "string" } }, "example": { "secret": "a1b2c3d4e5" } }, "ConfigureWebhook": { "title": "Configure Webhook Data", "description": "Data to configure a webhook.", "type": "object", "properties": { "targetUrl": { "type": "string", "description": "HTTPS endpoint that webhook events will be POSTed to.", "pattern": "https?:\\/\\/(www\\.)?[-a-zA-Z0-9@:%._\\+~#=]{2,256}\\.[a-z]{2,4}\\b([-a-zA-Z0-9@:%_\\+.~#?&//=]*)" } }, "example": { "targetUrl": "https://domain.com/v1/tracking" }, "required": [ "targetUrl" ] }, "Subscription": { "type": "object", "required": [ "scacCode" ], "properties": { "containerNumber": { "title": "Container Number", "description": "Equipment unique identifier", "type": "string", "pattern": "^[A-Z]{4}[0-9]{7}$" }, "bookingNumber": { "title": "Booking Reference", "description": "Booking reference for a journey", "type": "string", "maxLength": 20, "minLength": 3 }, "billNumber": { "title": "Bill Of Lading", "description": "Bill of lading for a journey", "type": "string", "maxLength": 20, "minLength": 3 }, "scacCode": { "title": "Carrier SCAC", "description": "Carrier unique SCAC identifier", "type": "string", "pattern": "^[A-Z]{4}$" }, "subscriptionReference": { "title": "Subscription Unique Identifier", "description": "Unique identifier for a subscription", "type": "string", "maxLength": 20, "minLength": 3 } }, "example": { "containerNumber": "ABCU1234567", "bookingNumber": "BN12345", "billNumber": "BL12345", "scacCode": "ABCU", "subscriptionReference": "REF12345" } }, "location": { "type": "object", "description": "DCSA location (LOCATION_DOMAIN 2.0.2). Where an event or transport call takes place.", "properties": { "locationName": { "type": "string" }, "latitude": { "type": "string" }, "longitude": { "type": "string" }, "UNLocationCode": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}$" }, "facilityCode": { "type": "string" }, "facilityCodeListProvider": { "type": "string", "enum": [ "BIC", "SMDG" ] }, "address": { "type": "object", "properties": { "name": { "type": "string" }, "street": { "type": "string" }, "streetNumber": { "type": "string" }, "floor": { "type": "string" }, "postCode": { "type": "string" }, "city": { "type": "string" }, "stateRegion": { "type": "string" }, "country": { "type": "string" } } } } }, "transportCall": { "type": "object", "description": "DCSA transport call: vessel, voyage and location context for the event. NB: current producers send numeric modeOfTransport codes (e.g. \"1\") and may omit transportCallID, so neither is enum-constrained nor required here.", "properties": { "transportCallID": { "type": "string", "description": "DCSA transport call identifier. Often omitted by current producers." }, "transportCallReference": { "type": "string" }, "modeOfTransport": { "type": "string", "description": "Mode of transport. DCSA text codes (VESSEL/RAIL/TRUCK/BARGE) or carrier-specific numeric codes." }, "carrierServiceCode": { "type": "string" }, "carrierVoyageNumber": { "type": "string" }, "carrierExportVoyageNumber": { "type": "string" }, "carrierImportVoyageNumber": { "type": "string" }, "UNLocationCode": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}$" }, "vessel": { "type": "object", "properties": { "vesselIMONumber": { "type": "string", "pattern": "^[0-9]{7}$" }, "vesselName": { "type": "string" }, "vesselFlag": { "type": "string" }, "vesselCallSignNumber": { "type": "string" }, "vesselOperatorCarrierCode": { "type": "string" } } }, "location": { "$ref": "#/components/schemas/location" } } }, "equipmentEvent": { "type": "object", "description": "DCSA EVENT_DOMAIN 2.0.2 equipment event", "externalDocs": { "description": "DCSA EVENT_DOMAIN 2.0.2 equipmentEvent schema", "url": "https://app.swaggerhub.com/domains/dcsaorg/EVENT_DOMAIN/2.0.2#/components/schemas/equipmentEvent" }, "required": [ "eventType", "eventClassifierCode", "eventDateTime", "equipmentEventTypeCode", "equipmentReference" ], "properties": { "eventType": { "type": "string", "enum": [ "EQUIPMENT" ] }, "eventClassifierCode": { "type": "string", "enum": [ "ACT", "PLN", "EST" ] }, "eventDateTime": { "type": "string", "format": "date-time" }, "eventCreatedDateTime": { "type": "string", "format": "date-time", "description": "Timestamp of when the event was created (metadata). Usually stamped server-side." }, "equipmentEventTypeCode": { "type": "string", "enum": [ "LOAD", "DISC", "GTIN", "GTOT", "STUF", "STRP", "PICK", "DROP", "INSP", "RSEA", "RMVD" ] }, "equipmentReference": { "type": "string", "description": "Container number" }, "ISOEquipmentCode": { "type": "string", "description": "ISO 6346 equipment size/type code" }, "emptyIndicatorCode": { "type": "string", "enum": [ "LADEN", "EMPTY" ] }, "carrierCode": { "type": "string", "description": "SCAC. Non-DCSA; inferred/stored on ingest." }, "facilityTypeCode": { "type": "string" }, "eventLocation": { "$ref": "#/components/schemas/location" }, "transportCall": { "$ref": "#/components/schemas/transportCall" }, "documentReferences": { "type": "array", "description": "DCSA document references. Supported types: BKG (Booking), CBR (Carrier Booking Reference), TRD (Transport Document / Bill of Lading), SHI (Shipping Instruction).", "items": { "type": "object", "required": [ "documentReferenceType", "documentReferenceValue" ], "properties": { "documentReferenceType": { "type": "string", "enum": [ "BKG", "CBR", "TRD", "SHI" ] }, "documentReferenceValue": { "type": "string" } } } }, "references": { "type": "object" }, "seals": { "type": "array" } }, "example": { "eventType": "EQUIPMENT", "eventClassifierCode": "ACT", "eventDateTime": "2023-06-15T10:30:00Z", "equipmentEventTypeCode": "LOAD", "equipmentReference": "ABCU1234567", "ISOEquipmentCode": "45G1", "emptyIndicatorCode": "LADEN", "carrierCode": "ABCU", "eventLocation": { "locationName": "Port of Hamburg", "UNLocationCode": "DEHAM" }, "transportCall": { "carrierVoyageNumber": "123W", "UNLocationCode": "DEHAM", "vessel": { "vesselIMONumber": "9321483", "vesselName": "MSC GULSUN" } }, "documentReferences": [ { "documentReferenceType": "BKG", "documentReferenceValue": "BN12345" }, { "documentReferenceType": "TRD", "documentReferenceValue": "BL12345" } ] } }, "transportEvent": { "type": "object", "description": "DCSA EVENT_DOMAIN 2.0.2 transport event. Location lives in transportCall.location, not eventLocation.", "externalDocs": { "description": "DCSA EVENT_DOMAIN 2.0.2 transportEvent schema", "url": "https://app.swaggerhub.com/domains/dcsaorg/EVENT_DOMAIN/2.0.2#/components/schemas/transportEvent" }, "required": [ "eventType", "eventClassifierCode", "eventDateTime", "transportEventTypeCode", "transportCall", "equipmentReference" ], "properties": { "eventType": { "type": "string", "enum": [ "TRANSPORT" ] }, "eventClassifierCode": { "type": "string", "enum": [ "ACT", "PLN", "EST" ] }, "eventDateTime": { "type": "string", "format": "date-time" }, "eventCreatedDateTime": { "type": "string", "format": "date-time", "description": "Timestamp of when the event was created (metadata). Usually stamped server-side." }, "transportEventTypeCode": { "type": "string", "enum": [ "ARRI", "DEPA" ] }, "equipmentReference": { "type": "string" }, "carrierCode": { "type": "string" }, "facilityTypeCode": { "type": "string" }, "transportCall": { "$ref": "#/components/schemas/transportCall" }, "documentReferences": { "type": "array", "items": { "type": "object", "required": [ "documentReferenceType", "documentReferenceValue" ], "properties": { "documentReferenceType": { "type": "string", "enum": [ "BKG", "CBR", "TRD", "SHI" ] }, "documentReferenceValue": { "type": "string" } } } }, "references": { "type": "object" } }, "example": { "eventType": "TRANSPORT", "eventClassifierCode": "ACT", "eventDateTime": "2023-06-16T04:00:00Z", "transportEventTypeCode": "ARRI", "equipmentReference": "ABCU1234567", "carrierCode": "ABCU", "transportCall": { "carrierVoyageNumber": "123W", "UNLocationCode": "DEHAM", "vessel": { "vesselIMONumber": "9321483", "vesselName": "MSC GULSUN" }, "location": { "locationName": "Port of Hamburg", "UNLocationCode": "DEHAM" } }, "documentReferences": [ { "documentReferenceType": "BKG", "documentReferenceValue": "BN12345" } ] } }, "WebhookPayload": { "type": "object", "description": "Payload delivered to the subscriber's webhook URL when tracking events are received.", "required": [ "references", "events" ], "properties": { "references": { "type": "object", "description": "Subscription and shipment identifiers associated with the tracking events", "properties": { "subscriptionReference": { "type": "string", "description": "Unique identifier for the subscription", "readOnly": true }, "equipmentNumber": { "type": "string", "description": "Container/equipment number", "readOnly": true }, "billNumber": { "type": "string", "description": "Bill of lading number", "readOnly": true }, "bookingNumber": { "type": "string", "description": "Booking reference number", "readOnly": true }, "scacCode": { "type": "string", "description": "Carrier SCAC code", "readOnly": true } } }, "events": { "type": "array", "description": "DCSA-standardized tracking events", "items": { "$ref": "#/components/schemas/equipmentEvent" } } }, "example": { "references": { "subscriptionReference": "REF12345", "equipmentNumber": "ABCU1234567", "billNumber": "BL12345", "bookingNumber": "BN12345", "scacCode": "ABCU" }, "events": [ { "eventType": "EQUIPMENT", "eventClassifierCode": "ACT", "eventDateTime": "2023-06-15T10:30:00Z", "equipmentEventTypeCode": "LOAD", "equipmentReference": "ABCU1234567", "ISOEquipmentCode": "45G1", "emptyIndicatorCode": "LADEN", "carrierCode": "ABCU", "eventLocation": { "locationName": "Port of Hamburg", "UNLocationCode": "DEHAM" }, "transportCall": { "carrierVoyageNumber": "123W", "UNLocationCode": "DEHAM", "vessel": { "vesselIMONumber": "9321483", "vesselName": "MSC GULSUN" } }, "documentReferences": [ { "documentReferenceType": "BKG", "documentReferenceValue": "BN12345" }, { "documentReferenceType": "TRD", "documentReferenceValue": "BL12345" } ] } ] } }, "CarrierCredentials": { "title": "Carrier Credentials", "type": "object", "description": "Your own carrier API credentials, keyed by SCAC code. Each carrier requires its full field set (all fields listed for it below), except MSCU where the API and Service Bus groups are independent. Credentials are merged per carrier: posting credentials for one SCAC leaves other carriers' stored credentials untouched, and re-posting a carrier replaces that carrier's set.", "properties": { "OOLU": { "type": "object", "description": "OOCL", "required": [ "apiKey", "clientId" ], "properties": { "apiKey": { "type": "string" }, "clientId": { "type": "string" } } }, "COSU": { "type": "object", "description": "COSCO", "required": [ "apiKey", "clientId" ], "properties": { "apiKey": { "type": "string" }, "clientId": { "type": "string" } } }, "MAEU": { "type": "object", "description": "Maersk", "required": [ "clientId", "clientSecret" ], "properties": { "clientId": { "type": "string" }, "clientSecret": { "type": "string" } } }, "ONEY": { "type": "object", "description": "Ocean Network Express", "required": [ "username", "password" ], "properties": { "username": { "type": "string" }, "password": { "type": "string" } } }, "YMLU": { "type": "object", "description": "Yang Ming", "required": [ "apiKey" ], "properties": { "apiKey": { "type": "string" } } }, "CMAU": { "type": "object", "description": "CMA CGM", "required": [ "apiKey" ], "properties": { "apiKey": { "type": "string" } } }, "MSCU": { "type": "object", "description": "MSC. Two independent credential groups, provide either or both as complete sets: the Track & Trace API (clientId, certificate, privateKey) and the Azure Service Bus queue MSC provisions for push subscriptions (the four serviceBus* fields).", "properties": { "clientId": { "type": "string" }, "certificate": { "type": "string", "description": "Base64-encoded PEM certificate." }, "privateKey": { "type": "string", "description": "Base64-encoded PEM private key." }, "serviceBusEndpoint": { "type": "string" }, "serviceBusQueueName": { "type": "string" }, "serviceBusSasPolicyName": { "type": "string" }, "serviceBusSasKey": { "type": "string" } } }, "HDMU": { "type": "object", "description": "HMM", "required": [ "apiKey" ], "properties": { "apiKey": { "type": "string" } } }, "EGLV": { "type": "object", "description": "Evergreen", "required": [ "apiKey" ], "properties": { "apiKey": { "type": "string" } } }, "ZIMU": { "type": "object", "description": "ZIM", "required": [ "subscriptionKey", "clientId", "clientSecret", "scope" ], "properties": { "subscriptionKey": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scope": { "type": "string" } } }, "HLCU": { "type": "object", "description": "Hapag-Lloyd", "required": [ "clientId", "clientSecret" ], "properties": { "clientId": { "type": "string" }, "clientSecret": { "type": "string" } } } }, "example": { "MAEU": { "clientId": "your-client-id", "clientSecret": "your-client-secret" } } }, "Message": { "title": "Message", "type": "object", "description": "Standard response envelope: a human-readable message.", "properties": { "message": { "type": "string" } }, "example": { "message": "Successful Configuration" } }, "GatewayMessage": { "type": "object", "title": "GatewayMessage", "description": "Error shape returned directly by API Gateway (authentication and throttling).", "properties": { "message": { "type": "string" } } }, "SubscriptionRecord": { "title": "Subscription Record", "type": "object", "description": "A subscription as returned by the subscription lookup endpoints.", "properties": { "subscriptionReference": { "type": "string" }, "equipmentNumber": { "type": "string", "description": "Container number, empty if not subscribed by container." }, "bookingNumber": { "type": "string", "description": "Booking reference, empty if not subscribed by booking." }, "billNumber": { "type": "string", "description": "Bill of lading, empty if not subscribed by bill." }, "scacCode": { "type": "string" }, "subscriptionCreationDate": { "type": "string", "format": "date-time" }, "subscriptionExpiryDate": { "type": "string", "format": "date-time" }, "subscriptionStatus": { "type": "string", "description": "OPEN while tracking, CLOSED after deletion." }, "connectionStatus": { "type": "string", "description": "Carrier connection state, e.g. CONNECTED or DISCONNECTED." }, "closureReason": { "type": "string", "description": "Present on CLOSED subscriptions, e.g. USER_DELETED." } } } }, "securitySchemes": { "api_key": { "in": "header", "name": "x-api-key", "type": "apiKey" } } }, "x-amazon-apigateway-request-validators": { "Validate body": { "validateRequestBody": true, "validateRequestParameters": false } } }