{ "openapi": "3.0.3", "info": { "title": "Shipment API", "description": "The Shipment API provides programmatic access to Cosmo Cargo's interstellar logistics network. Create shipments, calculate rates, track packages in real-time, and manage customs documentation for cross-border deliveries.\n\n## Getting Started\n\nTo start shipping, create a shipment with origin and destination addresses, then calculate rates for your preferred service level. Once confirmed, use the tracking endpoints to monitor delivery progress.\n\n```sh\ncurl -X POST https://api.cosmocargo.com/v1/shipments \\\n -H \"X-API-Key: your_api_key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"recipientAddress\": {...}, \"senderAddress\": {...}, \"packages\": [...]}'\n```\n\n## Rate Limits\n\n| Plan | Requests/min | Burst |\n|------------|-------------|-------|\n| Free | 60 | 10 |\n| Pro | 600 | 50 |\n| Enterprise | Custom | Custom|\n\nRate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`) are included in every response.\n\n## Idempotency\n\nPOST and PUT endpoints support idempotency keys via the `Idempotency-Key` header. Sending the same key within 24 hours returns the original response without creating duplicates.\n\n## Versioning\n\nThe API is versioned via the `X-API-Version` header. The current stable version is `2024-01`. Omitting the header defaults to the latest stable version.\n", "version": "1.0.0", "contact": { "name": "Cosmo Cargo API Support", "email": "api@sh.example.com", "url": "https://developers.sh.example.com" }, "license": { "name": "MIT License", "url": "https://opensource.org/licenses/MIT" }, "termsOfService": "https://example.com" }, "externalDocs": { "url": "https://example.com" }, "x-tagGroups": [ { "name": "Shipment", "tags": ["Shipment Management", "Tracking & Notifications"] }, { "name": "Billing & International", "tags": ["Rates & Billing", "International Shipping"] } ], "tags": [ { "name": "Shipment Management", "description": "Endpoints for creating, tracking, updating, and managing shipments." }, { "name": "Rates & Billing", "description": "Endpoints related to calculating shipping rates, billing, and insurance." }, { "name": "International Shipping", "description": "Operations for managing customs documentation, duties, and international shipment processes.\n\n\nInterstellar customs regulations were updated in Stardate 2025.3. All shipments crossing the Outer Rim must include a Quantum Manifest.\n" }, { "name": "Documentation", "description": "Endpoints for generating and retrieving shipment-related documents." }, { "name": "Tracking & Notifications", "description": "Endpoints for tracking shipments and configuring notifications for shipment status updates.", "x-displayName": "Notifications" }, { "name": "System", "description": "Endpoints for system health checks and retrieving API version information." }, { "name": "Schemas", "description": "Endpoints for retrieving and validating data schemas used across the Cosmo Cargo platform.", "x-zudoku-collapsed": false } ], "servers": [ { "url": "https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io/", "description": "Production environment" }, { "url": "https://api.sh.example.com/v1", "description": "Production environment" }, { "url": "https://api.staging.sh.example.com/v1", "description": "Staging environment" }, { "url": "https://api.dev.sh.example.com/v1", "description": "Development environment" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "components": { "parameters": { "CorrelationId": { "name": "X-Correlation-ID", "in": "header", "description": "Unique identifier for tracking requests across multiple services", "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Unique key to ensure idempotency of the request", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "ApiVersion": { "name": "X-API-Version", "in": "header", "description": "API version requested by the client", "schema": { "type": "string", "nullable": true, "enum": ["2024-01", "2023-12"], "default": "2024-01" } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key passed via the `X-API-Key` header. Get your key from the [developer portal](https://developers.sh.example.com)." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT bearer token obtained from the authentication service." } }, "schemas": { "Shipment": { "type": "object", "required": ["recipientAddress", "senderAddress", "packages"], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "recipientEmail": { "type": "string", "format": "email", "example": "recipient@example.com" }, "notes": { "type": "array", "description": "Notes about the shipment", "items": { "$ref": "#/components/schemas/Comment" } }, "recipientAddress": { "$ref": "#/components/schemas/Address" }, "senderAddress": { "$ref": "#/components/schemas/Address" }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/Package" }, "minItems": 1, "maxItems": 50, "uniqueItems": true }, "status": { "type": "string", "enum": ["CREATED", "IN_TRANSIT", "DELIVERED", "EXCEPTION"], "nullable": true }, "trackingNumber": { "type": "string", "pattern": "^[A-Z0-9]{10,20}$", "deprecated": true, "description": "Use the `tracking` endpoint instead. This field will be removed in a future version." }, "createdAt": { "type": "string", "format": "date-time" }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" }, "maxItems": 100 }, "tags": { "type": "array", "items": { "type": "string", "enum": [ "FRAGILE", "EXPRESS", "INTERNATIONAL", "CUSTOMS_REQUIRED" ] } }, "facilities": { "type": "array", "items": { "type": "string", "enum": ["LAX1", "JFK2", "ORD3", "DFW4", "SEA5"] } }, "customData": { "type": "array", "description": "Array of custom data items that can be of any type", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "metadata": { "type": "object", "description": "Empty object for future extensibility", "properties": {} }, "legacyId": { "deprecated": true, "description": "Legacy identifier from the old system. Use `id` instead." }, "customFields": { "type": "object", "description": "Dictionary of custom string fields that can be added to the shipment", "additionalProperties": { "type": "string" }, "example": { "customerReference": "CUST-123", "internalNotes": "Handle with care", "specialInstructions": "Leave at front desk" } }, "facilityCapabilities": { "type": "object", "description": "Dictionary of facility capabilities and their status", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the capability is enabled" }, "lastChecked": { "type": "string", "format": "date-time", "description": "When the capability was last verified" } } }, "example": { "temperatureControl": { "enabled": true, "lastChecked": "2024-03-15T10:30:00Z" }, "hazardousMaterials": { "enabled": false, "lastChecked": "2024-03-14T15:45:00Z" } } }, "tracking": { "$ref": "#/components/schemas/TrackingDetails", "description": "Real-time tracking information for this shipment" }, "returnTracking": { "oneOf": [ { "$ref": "#/components/schemas/TrackingDetails" }, { "type": "null" } ], "description": "Tracking details for return shipment if applicable" } }, "additionalProperties": true }, "Address": { "type": "object", "required": ["street", "city", "country", "postalCode"], "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code" }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 20 } } }, "Package": { "type": "object", "required": ["weight", "dimensions"], "properties": { "weight": { "type": "number", "format": "float", "description": "Weight in kilograms", "minimum": 0.1, "maximum": 1000 }, "dimensions": { "$ref": "#/components/schemas/Dimensions" } } }, "Dimensions": { "type": "object", "required": ["length", "width", "height"], "properties": { "length": { "type": "number", "format": "float", "description": "Length in centimeters", "minimum": 1, "maximum": 300 }, "width": { "type": "number", "format": "float", "description": "Width in centimeters", "minimum": 1, "maximum": 300 }, "height": { "type": "number", "format": "float", "description": "Height in centimeters", "minimum": 1, "maximum": 300 } } }, "Error": { "type": "object", "required": ["code", "message"], "example": { "code": "SHIPMENT_NOT_FOUND", "message": "The requested shipment could not be found" }, "properties": { "code": { "type": "string", "pattern": "^[A-Z_]+$", "minLength": 1, "maxLength": 50, "example": "SHIPMENT_NOT_FOUND" }, "message": { "type": "string", "minLength": 1, "maxLength": 500, "example": "The requested shipment could not be found" } } }, "HTTPValidationError": { "type": "object", "required": ["detail"], "properties": { "detail": { "type": "array", "items": { "type": "object", "required": ["loc", "msg", "type"], "properties": { "loc": { "type": "array", "items": { "type": "string" }, "description": "Field location" }, "msg": { "type": "string", "description": "Error message" }, "type": { "type": "string", "description": "Error type" } } } } }, "description": "HTTP validation error details" }, "ShipmentValidationError": { "type": "object", "required": ["code", "message", "field"], "properties": { "code": { "type": "string", "enum": [ "INVALID_ADDRESS", "INVALID_PACKAGE", "INVALID_WEIGHT", "MISSING_FIELD" ], "description": "Specific validation error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "field": { "type": "string", "description": "Field that failed validation" }, "suggestion": { "type": "string", "description": "Suggested fix for the error" } }, "description": "Shipment-specific validation error" }, "TrackingDetails": { "type": "object", "description": "Detailed tracking information for a shipment", "properties": { "currentLocation": { "type": "string", "description": "Current location of the shipment", "example": "Distribution Center - Los Angeles, CA" }, "estimatedDelivery": { "type": "string", "format": "date-time", "description": "Estimated delivery date and time" }, "lastUpdate": { "type": "string", "format": "date-time", "description": "Last tracking update timestamp" }, "carrier": { "type": "string", "description": "Carrier handling the shipment", "enum": ["FEDEX", "UPS", "USPS", "DHL"], "example": "FEDEX" }, "deliveryConfirmation": { "type": "object", "properties": { "signedBy": { "type": "string", "description": "Name of person who signed for delivery" }, "signatureImage": { "type": "string", "format": "uri", "description": "URL to signature image" } } } }, "required": ["currentLocation", "lastUpdate"] }, "ShipmentHistory": { "type": "object", "properties": { "currentShipment": { "$ref": "#/components/schemas/Shipment" }, "previousShipment": { "$ref": "#/components/schemas/ShipmentHistory" }, "transferredAt": { "type": "string", "format": "date-time", "description": "When the shipment was transferred" } }, "minProperties": 1, "maxProperties": 3 }, "Comment": { "type": "object", "required": ["id", "author", "text", "timestamp"], "description": "A comment on a shipment that can have nested replies", "properties": { "id": { "type": "string", "description": "Unique identifier for the comment", "pattern": "^[a-zA-Z0-9-]+$" }, "author": { "type": "string", "description": "Name of the person who wrote the comment" }, "text": { "type": "string", "description": "Content of the comment" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the comment was posted" }, "replies": { "type": "array", "description": "Nested replies to this comment", "items": { "$ref": "#/components/schemas/Comment" } } } }, "Organization": { "type": "object", "description": "A shipping organization that can have sub-organizations (e.g. regional offices)", "required": ["id", "name"], "properties": { "id": { "type": "string", "description": "Unique identifier for the organization", "pattern": "^[a-zA-Z0-9-]+$" }, "name": { "type": "string", "description": "Name of the organization", "minLength": 1, "maxLength": 200 }, "parent": { "$ref": "#/components/schemas/Organization", "description": "The parent organization (direct object circular reference)" }, "sub": { "type": "array", "description": "Child organizations (array circular reference)", "maxItems": 100, "items": { "$ref": "#/components/schemas/Organization" } } } }, "LinkedShipment": { "type": "object", "description": "A shipment that's part of a chain (e.g. multi-leg delivery)", "required": ["id", "status"], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the shipment" }, "status": { "type": "string", "enum": ["PENDING", "IN_TRANSIT", "DELIVERED"] }, "next": { "$ref": "#/components/schemas/LinkedShipment", "nullable": true }, "previous": { "$ref": "#/components/schemas/LinkedShipment", "nullable": true } }, "additionalProperties": false }, "SchemaValidationRequest": { "type": "object", "description": "Request to validate data against a specific schema", "required": ["data"], "properties": { "data": { "type": "object", "description": "The data to validate against the schema" }, "options": { "type": "object", "properties": { "strictMode": { "type": "boolean", "description": "Whether to validate in strict mode", "default": false }, "allowAdditionalProperties": { "type": "boolean", "description": "Whether to allow properties not defined in the schema", "default": true } } } } }, "SchemaValidationResponse": { "type": "object", "description": "Response from schema validation", "required": ["valid"], "properties": { "valid": { "type": "boolean", "description": "Whether the data is valid according to the schema" }, "errors": { "type": "array", "description": "Validation errors if any", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path to the invalid property" }, "message": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code", "enum": [ "REQUIRED", "TYPE_MISMATCH", "ENUM_VIOLATION", "FORMAT_VIOLATION", "CONSTRAINT_VIOLATION" ] } } } }, "schemaId": { "type": "string", "description": "Identifier of the schema used for validation" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the validation was performed" } } }, "SchemaMetadata": { "type": "object", "description": "Metadata about a schema", "required": ["id", "name", "version"], "properties": { "id": { "type": "string", "description": "Unique identifier for the schema" }, "name": { "type": "string", "description": "Human-readable name of the schema" }, "version": { "type": "string", "description": "Version of the schema", "pattern": "^\\d+\\.\\d+\\.\\d+$" }, "description": { "type": "string", "description": "Description of the schema" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the schema was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the schema was last updated" }, "spaceEntityType": { "type": "string", "description": "The type of space entity this schema represents", "enum": [ "CARGO", "VESSEL", "CREW", "ROUTE", "STATION", "PLANET", "ASTEROID", "SATELLITE" ] } } } } }, "paths": { "/shipments": { "post": { "tags": ["Shipment Management"], "summary": "Create a new shipment", "description": "Creates a new shipment with the provided details.\n\nThis endpoint allows you to **create and register** a new shipment in the Cosmo Cargo platform. The shipment will be assigned a unique `trackingNumber` and will enter the `CREATED` status.\n\n### How to use with SDK\n\nHere's how to create a shipment using `@cosmo-cargo/sdk{:sh}`:\n\n```ts\nimport { CosmoCargoClient } from '@cosmo-cargo/sdk';\n\nconst client = new CosmoCargoClient({ key: process.env.COSMO_API_KEY });\n\nconst shipment = await client.shipments.create(config);\nconsole.log(`Shipment created: ${shipment.trackingNumber}`);\n```\n\n**Note:** Use the `X-Request-Priority` header to expedite processing for urgent shipments.", "operationId": "createShipment", "x-code-samples": [ { "lang": "shell", "label": "cURL", "source": "curl -X POST https://api.cosmocargo.com/v1/shipments \\\n -H 'Content-Type: application/json' \\\n -H 'X-API-Key: YOUR_API_KEY' \\\n -d '{\n \"recipientAddress\": {\n \"name\": \"Zara Nebula\",\n \"planet\": \"Mars\",\n \"station\": \"Olympus Mons Hub\"\n },\n \"packages\": [{ \"weight\": 2.5, \"dimensions\": \"30x20x15\" }]\n }'" }, { "lang": "js", "label": "JavaScript", "source": "const response = await fetch(\n 'https://api.cosmocargo.com/v1/shipments',\n {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'X-API-Key': 'YOUR_API_KEY',\n },\n body: JSON.stringify({\n recipientAddress: {\n name: 'Zara Nebula',\n planet: 'Mars',\n station: 'Olympus Mons Hub',\n },\n packages: [{ weight: 2.5, dimensions: '30x20x15' }],\n }),\n },\n);\n\nconst shipment = await response.json();" }, { "lang": "python", "label": "Python", "source": "import requests\n\nresponse = requests.post(\n 'https://api.cosmocargo.com/v1/shipments',\n headers={\n 'Content-Type': 'application/json',\n 'X-API-Key': 'YOUR_API_KEY',\n },\n json={\n 'recipientAddress': {\n 'name': 'Zara Nebula',\n 'planet': 'Mars',\n 'station': 'Olympus Mons Hub',\n },\n 'packages': [{'weight': 2.5, 'dimensions': '30x20x15'}],\n },\n)\n\nshipment = response.json()" } ], "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }], "parameters": [ { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" }, { "name": "X-Request-Priority", "in": "header", "description": "Priority level for processing the shipment request", "schema": { "type": "string", "enum": ["high", "normal", "low"], "default": "normal" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" }, "examples": { "simple": { "summary": "Simple domestic shipment", "value": { "recipientEmail": "test@example.com", "recipientAddress": { "street": "123 Delivery St", "city": "Shiptown", "state": "ST", "country": "US", "postalCode": "12345" }, "senderAddress": { "street": "456 Sender Ave", "city": "Packageville", "state": "ST", "country": "US", "postalCode": "67890" }, "packages": [ { "weight": 2.5, "dimensions": { "length": 30, "width": 20, "height": 15 } } ] } }, "international": { "summary": "International multi-package shipment", "value": { "recipientAddress": { "street": "789 Global Road", "city": "London", "country": "GB", "postalCode": "SW1A 1AA" }, "senderAddress": { "street": "321 Export Blvd", "city": "Los Angeles", "state": "CA", "country": "US", "postalCode": "90001" }, "packages": [ { "weight": 1.2, "dimensions": { "length": 25, "width": 15, "height": 10 } }, { "weight": 3.8, "dimensions": { "length": 40, "width": 30, "height": 20 } } ] } } } } } }, "responses": { "201": { "description": "Shipment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" }, "examples": { "domestic": { "summary": "Domestic shipment response", "value": { "id": "123e4567-e89b-12d3-a456-426614174000", "recipientEmail": "test@example.com", "recipientAddress": { "street": "123 Delivery St", "city": "Shiptown", "state": "ST", "country": "US", "postalCode": "12345" }, "senderAddress": { "street": "456 Sender Ave", "city": "Packageville", "state": "ST", "country": "US", "postalCode": "67890" }, "packages": [ { "weight": 2.5, "dimensions": { "length": 30, "width": 20, "height": 15 } } ], "status": "CREATED", "trackingNumber": "SH123456789", "createdAt": "2025-01-09T12:00:00Z" } }, "international": { "summary": "International shipment response", "value": { "id": "987fcdeb-a654-3210-9876-543210987654", "recipientAddress": { "street": "789 Global Road", "city": "London", "country": "GB", "postalCode": "SW1A 1AA" }, "senderAddress": { "street": "321 Export Blvd", "city": "Los Angeles", "state": "CA", "country": "US", "postalCode": "90001" }, "packages": [ { "weight": 1.2, "dimensions": { "length": 25, "width": 15, "height": 10 } }, { "weight": 3.8, "dimensions": { "length": 40, "width": 30, "height": 20 } } ], "status": "CREATED", "trackingNumber": "SH987654321", "createdAt": "2025-01-09T14:30:00Z" } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Shipment" }, "example": "\n\n 123e4567-e89b-12d3-a456-426614174000\n \n 123 Delivery St\n Shiptown\n ST\n US\n 12345\n \n \n 456 Sender Ave\n Packageville\n ST\n US\n 67890\n \n \n \n 2.5\n \n 30\n 20\n 15\n \n \n \n CREATED\n SH123456789\n 2025-01-09T12:00:00Z\n" } } }, "400": { "description": "Invalid input - returns either HTTP validation error or shipment-specific validation error", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HTTPValidationError" }, { "$ref": "#/components/schemas/ShipmentValidationError" } ] }, "examples": { "http_validation_error": { "summary": "HTTP Validation Error", "value": { "detail": [ { "loc": ["body", "recipientAddress", "postalCode"], "msg": "String should match pattern '^[0-9]{5}$'", "type": "string_pattern_mismatch" } ] } }, "shipment_validation_error": { "summary": "Shipment Validation Error", "value": { "code": "INVALID_ADDRESS", "message": "The recipient address is not valid for the selected shipping service", "field": "recipientAddress", "suggestion": "Please verify the postal code format for the destination country" } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ShipmentValidationError" }, "example": "\n\n 123e4567-e89b-12d3-a456-426614174000\n \n 123 Delivery St\n Shiptown\n ST\n US\n 12345\n \n \n 456 Sender Ave\n Packageville\n ST\n US\n 67890\n \n \n \n 2.5\n \n 30\n 20\n 15\n \n \n \n CREATED\n SH123456789\n 2025-01-09T12:00:00Z\n" } } }, "500": { "description": "Error code", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "get": { "tags": ["Shipment Management"], "summary": "Filter shipments", "description": "Search and filter shipments using various criteria", "operationId": "filterShipments", "parameters": [ { "name": "status", "in": "query", "required": true, "description": "Filter by shipment status", "schema": { "type": "array", "items": { "type": "string", "enum": ["CREATED", "IN_TRANSIT", "DELIVERED", "EXCEPTION"] } }, "style": "form", "explode": true }, { "name": "tags", "in": "query", "description": "Filter by tags", "schema": { "type": "array", "items": { "type": "string", "enum": [ "FRAGILE", "EXPRESS", "INTERNATIONAL", "CUSTOMS_REQUIRED" ] } } }, { "name": "dateRange", "in": "query", "description": "Filter by creation date range", "schema": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "description": "Start date for filtering" }, "end": { "type": "string", "format": "date-time", "description": "End date for filtering" } } }, "style": "deepObject", "explode": true }, { "name": "addressFilter", "in": "query", "description": "Filter by address criteria", "schema": { "type": "object", "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code" }, "city": { "type": "string", "description": "City name" }, "postalCode": { "type": "string", "description": "Postal code" } } } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Shipments retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipments": { "type": "array", "items": { "$ref": "#/components/schemas/Shipment" } }, "total": { "type": "integer", "description": "Total number of shipments matching the filter" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } } }, "/shipments/{trackingNumber}": { "get": { "tags": ["Shipment Management"], "summary": "Track a shipment", "description": "Get the current status and tracking information for a shipment", "operationId": "trackShipment", "parameters": [ { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/ApiVersion" }, { "name": "X-Cache-Control", "in": "header", "description": "Caching behavior for the tracking response", "schema": { "type": "string", "enum": ["no-cache", "max-age=60"], "default": "max-age=60" } }, { "name": "trackingNumber", "in": "path", "required": true, "schema": { "default": "SH123456789", "type": "string" }, "example": "SH123456789" }, { "name": "includeHistory", "in": "query", "description": "Include detailed tracking history and events in the response", "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "Shipment tracking information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" }, "example": { "id": "123e4567-e89b-12d3-a456-426614174000", "recipientEmail": "test@example.com", "recipientAddress": { "street": "123 Delivery St", "city": "Shiptown", "state": "ST", "country": "US", "postalCode": "12345" }, "senderAddress": { "street": "456 Sender Ave", "city": "Packageville", "state": "ST", "country": "US", "postalCode": "67890" }, "packages": [ { "weight": 2.5, "dimensions": { "length": 30, "width": 20, "height": 15 } } ], "status": "IN_TRANSIT", "trackingNumber": "SH123456789", "createdAt": "2025-01-09T12:00:00Z" } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Shipment with tracking number SH123456789 not found" } } } } } }, "delete": { "tags": ["Shipment Management"], "summary": "Cancel shipment", "description": "Cancel a shipment that hasn't been picked up yet.", "operationId": "cancelShipment", "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }], "parameters": [ { "name": "trackingNumber", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Shipment cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["CANCELLED"] }, "refundAmount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "examples": { "full_refund": { "summary": "Full refund issued", "value": { "status": "CANCELLED", "refundAmount": 116.74, "currency": "USD" } } } } } } } } }, "/shipments/{shipmentId}/hold": { "put": { "tags": ["Shipment Management"], "summary": "Hold shipment", "description": "Place a shipment on hold at a facility", "operationId": "holdShipment", "parameters": [ { "name": "X-Hold-Operator", "in": "header", "description": "Operator requesting the hold", "schema": { "type": "string", "enum": ["SYSTEM", "ADMIN", "CUSTOMER", "AGENT"] } }, { "name": "holdDuration", "in": "query", "description": "Duration to hold the shipment", "schema": { "type": "string", "format": "date-time" } }, { "name": "preferredLocation", "in": "cookie", "description": "User's preferred facility location", "schema": { "type": "string" } }, { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["holdUntil"], "properties": { "holdUntil": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "enum": [ "RECIPIENT_REQUEST", "CUSTOMS_HOLD", "WEATHER_DELAY", "ADDRESS_VERIFICATION", "PAYMENT_PENDING" ] }, "facilityId": { "type": "string", "enum": ["LAX1", "JFK2", "ORD3", "DFW4", "SEA5"] } } }, "examples": { "recipient_request": { "summary": "Hold at facility per recipient request", "value": { "holdUntil": "2025-01-15T17:00:00Z", "reason": "RECIPIENT_REQUEST", "facilityId": "LAX1" } } } } } }, "responses": { "200": { "description": "Shipment placed on hold successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ON_HOLD", "HOLD_PENDING", "HOLD_REJECTED"] }, "holdLocation": { "type": "string", "enum": [ "LAX1 - Los Angeles Hub", "JFK2 - New York Hub", "ORD3 - Chicago Hub", "DFW4 - Dallas Hub", "SEA5 - Seattle Hub" ] }, "holdUntil": { "type": "string", "format": "date-time", "enum": [ "2025-01-15T17:00:00Z", "2025-01-16T09:00:00Z", "2025-01-17T14:00:00Z" ] } } }, "example": { "status": "ON_HOLD", "holdLocation": "LAX1 - Los Angeles Hub", "holdUntil": "2025-01-15T17:00:00Z" } } } } } } }, "/shipments/{shipmentId}/rates": { "post": { "tags": ["Rates & Billing"], "summary": "Calculate shipping rates", "description": "Calculate available shipping rates for a shipment based on service level, destination, and package details", "operationId": "calculateRates", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["serviceLevel"], "properties": { "serviceLevel": { "type": "string", "enum": ["ECONOMY", "STANDARD", "EXPRESS", "SAME_DAY"] }, "insurance": { "type": "object", "properties": { "value": { "type": "number", "format": "float", "description": "Declared value for insurance in USD" }, "description": { "type": "string", "description": "Description of insured items" } } } } }, "examples": { "basic": { "summary": "Basic service level", "value": { "serviceLevel": "STANDARD" } }, "insured": { "summary": "Express with insurance", "description": "Express shipping with insurance for high-value electronics", "value": { "serviceLevel": "EXPRESS", "insurance": { "value": 1500.0, "description": "Gaming laptop with accessories" } } } } } } }, "responses": { "200": { "description": "Rates calculated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "baseRate": { "type": "number", "format": "float" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "amount": { "type": "number", "format": "float" }, "description": { "type": "string" } } } }, "totalRate": { "type": "number", "format": "float" }, "currency": { "type": "string" }, "transitTime": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "unit": { "type": "string", "enum": ["HOURS", "DAYS"] } } } } }, "examples": { "domestic_ground": { "summary": "Domestic ground shipping", "value": { "baseRate": 15.99, "fees": [ { "type": "FUEL_SURCHARGE", "amount": 1.2, "description": "Current fuel surcharge" } ], "totalRate": 17.19, "currency": "USD", "transitTime": { "min": 3, "max": 5, "unit": "DAYS" } } }, "international_express": { "summary": "International express with insurance", "value": { "baseRate": 89.99, "fees": [ { "type": "FUEL_SURCHARGE", "amount": 6.75, "description": "Current fuel surcharge" }, { "type": "INSURANCE", "amount": 15.0, "description": "Insurance for declared value of $1,500.00" }, { "type": "REMOTE_AREA", "amount": 5.0, "description": "Remote area delivery fee" } ], "totalRate": 116.74, "currency": "USD", "transitTime": { "min": 24, "max": 48, "unit": "HOURS" } } } } } } } } } }, "/shipments/{shipmentId}/insurance": { "post": { "tags": ["Rates & Billing"], "summary": "Add insurance", "x-explorer-enabled": false, "description": "Add or modify insurance coverage for a shipment", "operationId": "addInsurance", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["coverage"], "properties": { "coverage": { "type": "number", "format": "float" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "value": { "type": "number", "format": "float" } } } } } }, "examples": { "electronics": { "summary": "Insurance for electronics", "value": { "coverage": 2500.0, "items": [ { "description": "MacBook Pro 16\"", "value": 2000.0 }, { "description": "Apple Magic Keyboard", "value": 300.0 }, { "description": "Apple Magic Mouse", "value": 200.0 } ] } } } } } }, "responses": { "200": { "description": "Insurance added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "premium": { "type": "number", "format": "float" }, "coverage": { "type": "number", "format": "float" }, "policyNumber": { "type": "string" } } }, "example": { "premium": 75.0, "coverage": 2500.0, "policyNumber": "INS-123456" } } } } } } }, "/shipments/{shipmentId}/customs": { "put": { "tags": ["International Shipping"], "summary": "Update customs documentation", "description": "Update or add customs documentation for international shipments", "operationId": "updateCustoms", "parameters": [ { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "X-Customs-Region", "in": "header", "description": "Customs processing region for the shipment", "schema": { "type": "string", "enum": ["EU", "NA", "APAC"], "default": "NA" } }, { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["items"], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "description", "quantity", "value", "hsCode", "originCountry" ], "properties": { "description": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "value": { "type": "number", "format": "float" }, "weight": { "type": "number", "format": "float" }, "hsCode": { "type": "string", "pattern": "^[0-9]{6,10}$" }, "originCountry": { "type": "string", "pattern": "^[A-Z]{2}$" } } } }, "purpose": { "type": "string", "enum": [ "COMMERCIAL", "PERSONAL", "GIFT", "RETURN", "REPAIR" ] }, "incoterm": { "type": "string", "enum": ["DAP", "DDP", "FCA", "EXW"] } } }, "examples": { "commercial": { "summary": "Commercial electronics shipment", "value": { "items": [ { "description": "Smartphone", "quantity": 10, "value": 399.99, "weight": 0.18, "hsCode": "851712", "originCountry": "CN" }, { "description": "Protective Cases", "quantity": 10, "value": 9.99, "weight": 0.05, "hsCode": "392690", "originCountry": "CN" } ], "purpose": "COMMERCIAL", "incoterm": "DDP" } }, "gift": { "summary": "Personal gift shipment", "description": "Handmade items sent as a gift", "value": { "items": [ { "description": "Handmade Wool Sweater", "quantity": 1, "value": 75.0, "weight": 0.5, "hsCode": "611010", "originCountry": "IE" }, { "description": "Local Chocolate Assortment", "quantity": 2, "value": 25.0, "weight": 0.3, "hsCode": "180632", "originCountry": "IE" } ], "purpose": "GIFT", "incoterm": "DAP" } } } } } }, "responses": { "200": { "description": "Customs documentation updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["PENDING", "APPROVED", "REJECTED"] }, "customsValue": { "type": "number", "format": "float" }, "currency": { "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COMMERCIAL_INVOICE", "DECLARATION", "CERTIFICATE_ORIGIN" ] }, "url": { "type": "string", "format": "uri" } } } } } }, "examples": { "commercial_approved": { "summary": "Approved commercial shipment", "value": { "id": "a1b2c3d4-e5f6-4a5b-9c8d-1a2b3c4d5e6f", "status": "APPROVED", "customsValue": 4099.8, "currency": "USD", "documents": [ { "type": "COMMERCIAL_INVOICE", "url": "https://api.sh.example.com/v1/customs/docs/invoice_12345.pdf" }, { "type": "DECLARATION", "url": "https://api.sh.example.com/v1/customs/docs/declaration_12345.pdf" } ] } }, "gift_pending": { "summary": "Pending gift shipment", "value": { "id": "f6e5d4c3-b2a1-4c5d-8e9f-2b3a4c5d6e7f", "status": "PENDING", "customsValue": 125.0, "currency": "USD", "documents": [ { "type": "DECLARATION", "url": "https://api.sh.example.com/v1/customs/docs/declaration_67890.pdf" } ] } } } } } } } } }, "/shipments/{shipmentId}/customs/duties": { "post": { "tags": ["International Shipping"], "summary": "Pay import duties", "description": "Pay import duties and taxes for an international shipment. Requires both an API key **and** a bearer token.", "operationId": "payDuties", "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }], "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["paymentMethod"], "properties": { "paymentMethod": { "type": "string", "enum": ["CREDIT_CARD", "BANK_TRANSFER", "ACCOUNT_BALANCE"] }, "paymentDetails": { "type": "object", "additionalProperties": true } } }, "examples": { "credit_card": { "summary": "Pay with credit card", "value": { "paymentMethod": "CREDIT_CARD", "paymentDetails": { "last4": "4242", "brand": "visa" } } } } } } }, "responses": { "200": { "description": "Duties paid successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" }, "receipt": { "type": "string", "format": "uri" } } }, "example": { "amount": 125.5, "currency": "GBP", "receipt": "https://api.sh.example.com/v1/receipts/duty_123456.pdf" } } } } } } }, "/schemas": { "get": { "tags": ["Schemas"], "summary": "List available schemas", "description": "Retrieve a list of all available data schemas in the Cosmo Cargo platform", "operationId": "listSchemas", "parameters": [ { "name": "entityType", "in": "query", "description": "Filter schemas by space entity type", "schema": { "type": "string", "enum": [ "CARGO", "VESSEL", "CREW", "ROUTE", "STATION", "PLANET", "ASTEROID", "SATELLITE" ] } }, { "name": "version", "in": "query", "description": "Filter schemas by version", "schema": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" } } ], "responses": { "200": { "description": "List of schemas retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "$ref": "#/components/schemas/SchemaMetadata" } }, "count": { "type": "integer", "description": "Total number of schemas returned" } } }, "example": { "schemas": [ { "id": "cargo-manifest-v1", "name": "Cargo Manifest", "version": "1.0.0", "description": "Schema for interplanetary cargo manifests", "createdAt": "2024-06-15T08:00:00Z", "updatedAt": "2024-06-15T08:00:00Z", "spaceEntityType": "CARGO" }, { "id": "vessel-specs-v2", "name": "Vessel Specifications", "version": "2.1.0", "description": "Technical specifications for space vessels", "createdAt": "2024-05-10T14:30:00Z", "updatedAt": "2024-07-22T09:15:00Z", "spaceEntityType": "VESSEL" }, { "id": "route-plan-v3", "name": "Route Planning", "version": "3.0.2", "description": "Interplanetary route planning and navigation", "createdAt": "2024-04-01T11:45:00Z", "updatedAt": "2024-07-15T16:20:00Z", "spaceEntityType": "ROUTE" } ], "count": 3 } } } } } } }, "/schemas/{schemaId}": { "get": { "tags": ["Schemas"], "summary": "Get schema details", "description": "Retrieve detailed information about a specific schema, including its structure", "operationId": "getSchema", "parameters": [ { "name": "schemaId", "in": "path", "required": true, "description": "Unique identifier of the schema", "schema": { "type": "string" }, "example": "cargo-manifest-v1" }, { "name": "includeStructure", "in": "query", "description": "Whether to include the full schema structure", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Schema details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/SchemaMetadata" }, "structure": { "type": "object", "description": "The JSON Schema structure" } } }, "example": { "metadata": { "id": "cargo-manifest-v1", "name": "Cargo Manifest", "version": "1.0.0", "description": "Schema for interplanetary cargo manifests", "createdAt": "2024-06-15T08:00:00Z", "updatedAt": "2024-06-15T08:00:00Z", "spaceEntityType": "CARGO" }, "structure": { "type": "object", "required": ["manifestId", "vesselId", "items"], "properties": { "manifestId": { "type": "string", "description": "Unique identifier for the cargo manifest" }, "vesselId": { "type": "string", "description": "ID of the vessel carrying the cargo" }, "departureDate": { "type": "string", "format": "date-time", "description": "When the vessel departs" }, "items": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "weight": { "type": "number" }, "hazardClass": { "type": "string", "enum": ["NONE", "CLASS_1", "CLASS_2", "CLASS_3"] } } } } } } } } } }, "404": { "description": "Schema not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "SCHEMA_NOT_FOUND", "message": "Schema with ID 'cargo-manifest-v1' not found" } } } } } } }, "/shipments/{shipmentId}/label": { "get": { "tags": ["Documentation"], "summary": "Get shipping label", "description": "Get the shipping label for a shipment in various formats. Supports both JSON and XML responses. XML format follows the EDIFACT D96A standard for shipping label interchange, while JSON is provided for modern API integrations.", "operationId": "getLabel", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["PDF", "PNG", "ZPL"] }, "description": "Label format" }, { "name": "Accept", "in": "header", "schema": { "type": "string", "enum": ["application/json", "application/xml"], "default": "application/json" }, "description": "Response format. Use application/xml for EDI-compliant responses following EDIFACT D96A standard." } ], "responses": { "200": { "description": "Label generated successfully", "content": { "application/json": { "schema": { "type": "object", "required": ["shipmentId", "format"], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "shipmentId": { "type": "string", "format": "uuid" }, "format": { "type": "string", "enum": ["PDF", "PNG", "ZPL"] }, "url": { "type": "string", "format": "uri", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "expiresAt": { "type": "string", "format": "date-time", "readOnly": true } } }, "examples": { "pdf": { "summary": "PDF Label", "value": { "id": "550e8400-e29b-41d4-a716-446655440000", "shipmentId": "123e4567-e89b-12d3-a456-426614174000", "format": "PDF", "url": "https://api.sh.example.com/v1/labels/550e8400-e29b-41d4-a716-446655440000", "createdAt": "2025-01-09T12:00:00Z", "expiresAt": "2025-01-16T12:00:00Z" } }, "png": { "summary": "PNG Label", "value": { "id": "661f9511-f3ac-52e5-b827-557766551111", "shipmentId": "123e4567-e89b-12d3-a456-426614174000", "format": "PNG", "url": "https://api.sh.example.com/v1/labels/661f9511-f3ac-52e5-b827-557766551111", "createdAt": "2025-01-09T12:05:00Z", "expiresAt": "2025-01-16T12:05:00Z" } }, "zpl": { "summary": "ZPL Label (Thermal Printer)", "description": "Label in ZPL format for direct thermal printing", "value": { "id": "772f0622-g4bd-63f6-c938-668877662222", "shipmentId": "123e4567-e89b-12d3-a456-426614174000", "format": "ZPL", "url": "https://api.sh.example.com/v1/labels/772f0622-g4bd-63f6-c938-668877662222", "createdAt": "2025-01-09T12:10:00Z", "expiresAt": "2025-01-16T12:10:00Z" } } } }, "application/xml": { "schema": { "type": "object", "required": ["shipmentId", "format"], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "shipmentId": { "type": "string", "format": "uuid" }, "format": { "type": "string", "enum": ["PDF", "PNG", "ZPL"] }, "url": { "type": "string", "format": "uri", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "expiresAt": { "type": "string", "format": "date-time", "readOnly": true } } }, "examples": { "pdf": { "summary": "PDF Label (EDIFACT D96A)", "description": "Label response in EDIFACT D96A XML format for EDI compliance", "value": "\n\n \n UNOC\n SHIPHAPPENS\n CARRIER123\n 2025010912000\n \n \n" }, "png": { "summary": "PNG Label (EDIFACT D96A)", "description": "Label response in EDIFACT D96A XML format for EDI compliance", "value": "\n\n \n UNOC\n SHIPHAPPENS\n CARRIER123\n 2025010912050\n \n \n" }, "zpl": { "summary": "ZPL Label (EDIFACT D96A)", "description": "Label response in EDIFACT D96A XML format for EDI compliance, suitable for thermal printers", "value": "\n\n \n UNOC\n SHIPHAPPENS\n CARRIER123\n 2025010912100\n \n \n" } } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Shipment not found" } } } } } } }, "/shipments/{shipmentId}/documents/v2/commercial-invoice": { "get": { "tags": ["Documentation"], "summary": "Get commercial invoice", "description": "Generate an enhanced commercial invoice with digital signatures, multiple format support, and customs pre-clearance capabilities. Supports both standard formats and country-specific templates.", "operationId": "getCommercialInvoiceV2", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["PDF", "DOCX", "XML", "JSON", "EDI"] }, "description": "Document format. XML/EDI formats follow international customs standards." }, { "name": "template", "in": "query", "schema": { "type": "string", "enum": ["STANDARD", "EU", "US", "CN", "UK"] }, "description": "Country-specific template to use" }, { "name": "include", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "digital_signature", "customs_preclearance", "packing_list", "certificate_origin" ] } }, "description": "Additional documents to include" } ], "responses": { "200": { "description": "Commercial invoice generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COMMERCIAL_INVOICE", "PACKING_LIST", "CERTIFICATE_ORIGIN", "CUSTOMS_PRECLEARANCE" ] }, "url": { "type": "string", "format": "uri" }, "format": { "type": "string" }, "template": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "digitalSignature": { "type": "object", "properties": { "signedBy": { "type": "string" }, "signedAt": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time" }, "certificateId": { "type": "string" } } } } } }, "customsStatus": { "type": "string", "enum": ["PENDING", "PRE_CLEARED", "CLEARED"] } } }, "example": { "documents": [ { "type": "COMMERCIAL_INVOICE", "url": "https://api.sh.example.com/v2/documents/invoice_123456.pdf", "format": "PDF", "template": "EU", "expiresAt": "2025-01-16T12:00:00Z", "digitalSignature": { "signedBy": "John Doe", "signedAt": "2025-01-09T12:00:00Z", "validUntil": "2026-01-09T12:00:00Z", "certificateId": "CERT-123456" } }, { "type": "CUSTOMS_PRECLEARANCE", "url": "https://api.sh.example.com/v2/documents/preclearance_123456.pdf", "format": "PDF", "expiresAt": "2025-01-16T12:00:00Z" } ], "customsStatus": "PRE_CLEARED" } } } } } } }, "/shipments/{shipmentId}/documents/commercial-invoice": { "get": { "tags": ["Documentation"], "summary": "Get commercial invoice (legacy)", "description": "Generate a basic commercial invoice for an international shipment. This endpoint is deprecated, please use [`/shipments/{shipmentId}/documents/v2/commercial-invoice`](#get-commercial-invoice) for enhanced features including digital signatures, multiple formats, and customs pre-clearance.", "deprecated": true, "operationId": "getCommercialInvoice", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["PDF", "DOCX"] } } ], "responses": { "200": { "description": "Commercial invoice generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "example": { "url": "https://api.sh.example.com/v1/documents/invoice_123456.pdf", "expiresAt": "2025-01-16T12:00:00Z" } } } } } } }, "/shipments/{shipmentId}/events": { "get": { "tags": ["Tracking & Notifications"], "summary": "Get shipment tracking events", "description": "Retrieve detailed tracking events for a shipment", "operationId": "getTrackingEvents", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tracking events retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipmentId": { "type": "string", "format": "uuid" }, "events": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "location": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } } } } }, "description": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "examples": { "domestic_delivery": { "summary": "Successful domestic delivery", "value": { "shipmentId": "123e4567-e89b-12d3-a456-426614174000", "events": [ { "timestamp": "2025-01-09T16:30:00Z", "status": "DELIVERED", "location": { "city": "Shiptown", "state": "ST", "country": "US", "coordinates": { "latitude": 37.7749, "longitude": -122.4194 } }, "description": "Package delivered to recipient", "details": { "signedBy": "John Smith", "deliveryLocation": "Front Door" } }, { "timestamp": "2025-01-09T09:15:00Z", "status": "OUT_FOR_DELIVERY", "location": { "city": "Shiptown", "state": "ST", "country": "US", "coordinates": { "latitude": 37.7749, "longitude": -122.4194 } }, "description": "Package is out for delivery", "details": { "vehicleId": "VAN123", "estimatedDelivery": "2025-01-09T17:00:00Z" } }, { "timestamp": "2025-01-09T02:30:00Z", "status": "ARRIVED_AT_FACILITY", "location": { "city": "Shiptown", "state": "ST", "country": "US", "coordinates": { "latitude": 37.7749, "longitude": -122.4194 } }, "description": "Package arrived at local facility", "details": { "facilityId": "ST123" } } ] } }, "international_exception": { "summary": "International shipment with customs delay", "value": { "shipmentId": "987fcdeb-a654-3210-9876-543210987654", "events": [ { "timestamp": "2025-01-09T14:20:00Z", "status": "EXCEPTION", "location": { "city": "London", "country": "GB", "coordinates": { "latitude": 51.5074, "longitude": -0.1278 } }, "description": "Customs clearance delay", "details": { "reason": "Additional documentation required", "requiredDocs": [ "Commercial Invoice", "Certificate of Origin" ], "contactEmail": "customs@sh.example.com" } }, { "timestamp": "2025-01-09T08:45:00Z", "status": "ARRIVED_AT_CUSTOMS", "location": { "city": "London", "country": "GB", "coordinates": { "latitude": 51.5074, "longitude": -0.1278 } }, "description": "Package arrived at customs", "details": { "customsOffice": "LHR1", "declarationNumber": "GB123456789" } }, { "timestamp": "2025-01-08T22:15:00Z", "status": "DEPARTED", "location": { "city": "Los Angeles", "state": "CA", "country": "US", "coordinates": { "latitude": 34.0522, "longitude": -118.2437 } }, "description": "Package departed origin facility", "details": { "flightNumber": "BA282", "destination": "LHR" } } ] } } } } } } } } }, "/shipments/{shipmentId}/notifications": { "post": { "tags": ["Tracking & Notifications"], "summary": "Set up notifications", "description": "Configure notification preferences for shipment status updates", "operationId": "setupNotifications", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "array", "items": { "type": "string", "format": "email" } }, "sms": { "type": "array", "items": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" } }, "webhooks": { "type": "array", "items": { "type": "string", "format": "uri" } }, "events": { "type": "array", "items": { "type": "string", "enum": [ "PICKUP_SCHEDULED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "EXCEPTION" ] } } } } } } } } }, "/shipments/{shipmentId}/priority": { "put": { "tags": ["Shipment Management"], "summary": "Update shipment priority", "description": "Update the priority level of a shipment", "operationId": "updatePriority", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["priority"], "properties": { "priority": { "type": "string", "enum": ["URGENT", "HIGH", "NORMAL", "LOW"], "description": "New priority level for the shipment" } } } } } } } }, "/shipments/{shipmentId}/service-levels": { "get": { "tags": ["Shipment Management"], "summary": "Get available service levels", "description": "Get all available service levels for a shipment with their details", "operationId": "getServiceLevels", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Available service levels", "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceLevels": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SAME_DAY", "NEXT_DAY", "EXPRESS", "STANDARD", "ECONOMY", "GROUND", "INTERNATIONAL_EXPRESS", "INTERNATIONAL_STANDARD", "INTERNATIONAL_ECONOMY", "INTERNATIONAL_GROUND", "INTERNATIONAL_AIR", "INTERNATIONAL_SEA", "INTERNATIONAL_RAIL", "INTERNATIONAL_COMBINED", "INTERNATIONAL_SPECIALIZED" ] }, "name": { "type": "string" }, "description": { "type": "string" } } } } } } } } } } } }, "/shipments/{shipmentId}/claims": { "post": { "tags": ["Shipment Management"], "summary": "Create a lost shipment claim", "description": "Submit a claim for a lost or damaged shipment. This endpoint accepts multipart/form-data to allow uploading photos and other evidence files along with the claim details.\n\n### Supported File Types\n- Images: JPEG, PNG, GIF, WebP (max 10MB each)\n- Documents: PDF (max 25MB each)\n\n### Maximum Files\nYou can upload up to 10 files per claim.", "operationId": "createShipmentClaim", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "description": "The unique identifier of the shipment", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["claimType", "description", "claimantEmail"], "properties": { "claimType": { "type": "string", "enum": ["LOST", "DAMAGED", "DELAYED", "MISSING_CONTENTS"], "description": "The type of claim being filed" }, "description": { "type": "string", "minLength": 20, "maxLength": 5000, "description": "Detailed description of the issue and circumstances" }, "claimantEmail": { "type": "string", "format": "email", "description": "Email address for claim correspondence" }, "claimantPhone": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "Phone number for claim correspondence (E.164 format)" }, "declaredValue": { "type": "number", "format": "float", "minimum": 0, "description": "Declared value of the shipment contents in USD" }, "incidentDate": { "type": "string", "format": "date", "description": "Date when the incident was discovered" }, "photos": { "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 10, "description": "Photos of damaged package or contents (JPEG, PNG, GIF, WebP)" }, "documents": { "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 5, "description": "Supporting documents such as receipts, invoices, or police reports (PDF only)" } } }, "encoding": { "photos": { "contentType": "image/jpeg, image/png, image/gif, image/webp" }, "documents": { "contentType": "application/pdf" } } } } }, "responses": { "201": { "description": "Claim created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "claimId": { "type": "string", "format": "uuid", "description": "Unique identifier for the claim" }, "shipmentId": { "type": "string", "format": "uuid", "description": "The shipment this claim is associated with" }, "claimNumber": { "type": "string", "pattern": "^CLM-[A-Z0-9]{8}$", "description": "Human-readable claim reference number" }, "claimType": { "type": "string", "enum": ["LOST", "DAMAGED", "DELAYED", "MISSING_CONTENTS"] }, "status": { "type": "string", "enum": [ "SUBMITTED", "UNDER_REVIEW", "ADDITIONAL_INFO_REQUIRED", "APPROVED", "DENIED", "SETTLED" ], "description": "Current status of the claim" }, "declaredValue": { "type": "number", "format": "float" }, "uploadedFiles": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "fileName": { "type": "string" }, "fileType": { "type": "string", "enum": ["PHOTO", "DOCUMENT"] }, "uploadedAt": { "type": "string", "format": "date-time" } } } }, "createdAt": { "type": "string", "format": "date-time" }, "estimatedResolutionDate": { "type": "string", "format": "date", "description": "Expected date for claim resolution" } } }, "example": { "claimId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "shipmentId": "123e4567-e89b-12d3-a456-426614174000", "claimNumber": "CLM-XK7M9P2Q", "claimType": "DAMAGED", "status": "SUBMITTED", "declaredValue": 299.99, "uploadedFiles": [ { "fileId": "f1e2d3c4-b5a6-7890-1234-567890abcdef", "fileName": "damaged_box.jpg", "fileType": "PHOTO", "uploadedAt": "2025-01-15T10:30:00Z" }, { "fileId": "a9b8c7d6-e5f4-3210-9876-543210fedcba", "fileName": "purchase_receipt.pdf", "fileType": "DOCUMENT", "uploadedAt": "2025-01-15T10:30:00Z" } ], "createdAt": "2025-01-15T10:30:00Z", "estimatedResolutionDate": "2025-01-29" } } } }, "400": { "description": "Invalid request - missing required fields or invalid file types", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "error": "Validation failed", "details": [ { "field": "description", "message": "Description must be at least 20 characters" }, { "field": "photos[2]", "message": "File type not supported. Allowed: JPEG, PNG, GIF, WebP" } ] } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "Shipment with ID 123e4567-e89b-12d3-a456-426614174000 not found" } } } }, "413": { "description": "File too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "maxSizeBytes": { "type": "integer" } } }, "example": { "error": "File exceeds maximum allowed size", "maxSizeBytes": 26214400 } } } }, "409": { "description": "Claim already exists for this shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "existingClaimId": { "type": "string", "format": "uuid" } } }, "example": { "error": "A claim already exists for this shipment", "existingClaimId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } }, "/organizations": { "get": { "tags": ["Organization Management"], "summary": "List all organizations", "description": "Returns a list of all organizations in the hierarchy", "operationId": "listOrganizations", "responses": { "200": { "description": "List of organizations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" }, "examples": { "headquarters": { "summary": "Global headquarters with regional offices", "externalValue": "https://raw.githubusercontent.com/zuplo/zudoku/main/examples/cosmo-cargo/data/organizations-example.json" } } } } } } }, "post": { "tags": ["Organization Management"], "summary": "Create a new organization", "description": "Creates a new organization, optionally as part of an existing hierarchy", "operationId": "createOrganization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "responses": { "201": { "description": "Organization created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } } } } }, "/routes/{originFacilityId}/{destinationFacilityId}/{serviceLevel}/estimate": { "get": { "tags": ["Route Planning"], "summary": "Get estimated delivery time", "description": "Get estimated delivery time between two facilities for a specific service level", "operationId": "getRouteEstimate", "parameters": [ { "name": "serviceLevel", "in": "path", "required": true, "schema": { "default": "STANDARD", "type": "string", "enum": ["ECONOMY", "STANDARD", "EXPRESS", "SAME_DAY"] }, "description": "Service level for the route" }, { "name": "destinationFacilityId", "in": "path", "required": true, "schema": { "type": "string", "example": "JFK1" }, "description": "ID of the destination facility" }, { "name": "originFacilityId", "in": "path", "required": true, "schema": { "type": "string", "example": "LAX1" }, "description": "ID of the origin facility" } ], "responses": { "200": { "description": "Route estimate retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "estimatedDeliveryTime": { "type": "object", "properties": { "min": { "type": "integer", "description": "Minimum delivery time" }, "max": { "type": "integer", "description": "Maximum delivery time" }, "unit": { "type": "string", "enum": ["HOURS", "DAYS"] } } }, "distance": { "type": "object", "properties": { "value": { "type": "number", "format": "float" }, "unit": { "type": "string", "enum": ["KM", "MI"] } } }, "route": { "type": "object", "properties": { "transitHubs": { "type": "array", "items": { "type": "string" } }, "transportModes": { "type": "array", "items": { "type": "string", "enum": ["AIR", "GROUND", "SEA"] } } } } } }, "examples": { "domestic_ground": { "summary": "Domestic ground shipping estimate", "value": { "estimatedDeliveryTime": { "min": 2, "max": 3, "unit": "DAYS" }, "distance": { "value": 2789.4, "unit": "MI" }, "route": { "transitHubs": ["DEN1", "CHI1"], "transportModes": ["GROUND"] } } }, "express_air": { "summary": "Express air shipping estimate", "value": { "estimatedDeliveryTime": { "min": 8, "max": 12, "unit": "HOURS" }, "distance": { "value": 2789.4, "unit": "MI" }, "route": { "transitHubs": [], "transportModes": ["AIR"] } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "INVALID_FACILITY", "message": "Invalid facility ID format" } } } }, "404": { "description": "Route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "ROUTE_NOT_FOUND", "message": "No route found between specified facilities" } } } } } } }, "/schemas/facility-capabilities": { "get": { "tags": ["Schemas"], "summary": "Get facility capabilities", "description": "Retrieve detailed capability information for space cargo facilities, including their operational status and supported features", "operationId": "getFacilityCapabilities", "parameters": [ { "name": "facilityIds", "in": "query", "description": "Array of facility IDs to test", "schema": { "type": ["array", "null"], "items": { "type": "string", "enum": ["LAX1", "JFK2", "ORD3", "DFW4", "SEA5"] } } }, { "name": "statuses", "in": "query", "description": "Array of status configurations", "schema": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["CARGO", "PASSENGER", "MAINTENANCE"] }, "status": { "type": "string", "enum": ["PENDING", "APPROVED", "REJECTED"] }, "facilityId": { "type": "string", "enum": ["LAX1", "JFK2", "ORD3", "DFW4", "SEA5"] } } } } } ], "responses": { "200": { "description": "Test response with array and nullable types", "content": { "application/json": { "schema": { "type": "object", "properties": { "facilities": { "type": ["array", "null"], "items": { "type": "object", "properties": { "id": { "type": "string", "enum": ["LAX1", "JFK2", "ORD3", "DFW4", "SEA5"] }, "status": { "type": ["string", "null"], "enum": ["ACTIVE", "MAINTENANCE", "CLOSED"] }, "capabilities": { "type": ["array", "null"], "items": { "type": "string", "enum": [ "CARGO", "PASSENGER", "MAINTENANCE", "STORAGE" ] } } } } }, "metadata": { "type": "object", "properties": { "tags": { "type": ["array", "null"], "items": { "type": "string" } }, "coordinates": { "type": ["array", "null"], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "examples": { "active_facilities": { "summary": "Active facilities with capabilities", "value": { "facilities": [ { "id": "LAX1", "status": "ACTIVE", "capabilities": ["CARGO", "MAINTENANCE"] }, { "id": "JFK2", "status": null, "capabilities": ["CARGO", "PASSENGER", "STORAGE"] } ], "metadata": { "tags": ["SPACE", "INTERNATIONAL"], "coordinates": [34.0522, -118.2437] } } }, "empty_response": { "summary": "Empty response with null arrays", "value": { "facilities": null, "metadata": { "tags": null, "coordinates": null } } } } } } } } } }, "/health": { "get": { "summary": "Health check", "description": "Check if the API is up and running. This endpoint is public and requires no authentication.", "operationId": "healthCheck", "security": [], "responses": { "200": { "description": "API is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["healthy"] }, "timestamp": { "type": "string", "format": "date-time" } } }, "example": { "status": "healthy", "timestamp": "2025-01-09T12:00:00Z" } } } } } } }, "/version": { "get": { "summary": "Get API version", "description": "Get information about the current API version. This endpoint is public.", "operationId": "getVersion", "security": [], "responses": { "200": { "description": "Version information", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "releaseDate": { "type": "string", "format": "date" }, "environment": { "type": "string", "enum": ["production", "staging", "development"] } } }, "example": { "version": "1.0.0", "releaseDate": "2025-01-01", "environment": "production" } } } } } } } } }