{
  "openapi": "3.1.0",
  "info": {
    "title": "MPX Global Logistics API for AI Agents",
    "description": "Public machine-readable API for tracking shipments, calculating freight rates, and retrieving warehouse receiving addresses for Zimbabwe cargo logistics.",
    "version": "1.0.0",
    "contact": {
      "name": "MPX Global Operations",
      "url": "https://mpxglobal.co.zw",
      "email": "support@mpxglobal.co.zw"
    }
  },
  "servers": [
    {
      "url": "https://mpxglobal.co.zw",
      "description": "Production Edge Server"
    }
  ],
  "paths": {
    "/api/public/track": {
      "get": {
        "operationId": "trackShipment",
        "summary": "Track Consignment Status",
        "description": "Look up live shipment milestones, current status, origin hub, and collection readiness using a House Air Waybill (HAWB) or tracking number.",
        "parameters": [
          {
            "name": "hawb",
            "in": "query",
            "required": true,
            "description": "The MPX House Air Waybill number (e.g. MPX-94473-CN) or carrier tracking number.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Shipment tracking details and event timeline",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentTrackingResponse"
                }
              }
            }
          },
          "404": {
            "description": "Shipment not found"
          }
        }
      }
    },
    "/api/public/rates": {
      "get": {
        "operationId": "calculateFreightRates",
        "summary": "Calculate Freight Shipping Rates",
        "description": "Estimates air express and ocean freight rates from China, Dubai, USA, UK, and South Africa to Harare, Zimbabwe.",
        "parameters": [
          {
            "name": "origin",
            "in": "query",
            "required": true,
            "description": "Two-letter country code of origin: CN (China), AE (Dubai), US (USA), GB (UK), ZA (South Africa), IN (India).",
            "schema": {
              "type": "string",
              "enum": ["CN", "AE", "US", "GB", "ZA", "IN"]
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "Freight mode: 'air' (Express Air) or 'sea' (Ocean LCL). Default is 'air'.",
            "schema": {
              "type": "string",
              "enum": ["air", "sea"],
              "default": "air"
            }
          },
          {
            "name": "weight",
            "in": "query",
            "required": false,
            "description": "Gross weight in kilograms (kg).",
            "schema": {
              "type": "number",
              "minimum": 0.1
            }
          },
          {
            "name": "cbm",
            "in": "query",
            "required": false,
            "description": "Volume in Cubic Meters (CBM). Required for sea freight calculation.",
            "schema": {
              "type": "number",
              "minimum": 0.01
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated rate quote with fee breakdown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreightRateQuote"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/warehouses": {
      "get": {
        "operationId": "getWarehouseAddresses",
        "summary": "Get Verified Receiving Hub Addresses",
        "description": "Returns verified bilingual Chinese and English intake warehouse addresses, shipping mark guidelines, and depot contacts.",
        "responses": {
          "200": {
            "description": "Directory of active receiving hubs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WarehouseDirectoryResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ShipmentTrackingResponse": {
        "type": "object",
        "properties": {
          "found": { "type": "boolean" },
          "hawb": { "type": "string" },
          "current_status": { "type": "string" },
          "origin_hub": { "type": "string" },
          "destination_city": { "type": "string" },
          "shipment_mode": { "type": "string" },
          "is_ready_for_collection": { "type": "boolean" },
          "is_collected": { "type": "boolean" },
          "timeline": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "status": { "type": "string" },
                "location": { "type": "string" },
                "timestamp": { "type": "string", "format": "date-time" }
              }
            }
          }
        }
      },
      "FreightRateQuote": {
        "type": "object",
        "properties": {
          "origin": { "type": "string" },
          "mode": { "type": "string" },
          "chargeable_weight_kg": { "type": "number" },
          "rate_per_kg_usd": { "type": "number" },
          "rate_per_cbm_usd": { "type": "number" },
          "estimated_total_usd": { "type": "number" },
          "transit_days_estimate": { "type": "string" },
          "notes": { "type": "string" }
        }
      },
      "WarehouseDirectoryResponse": {
        "type": "object",
        "properties": {
          "warehouses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "country": { "type": "string" },
                "mode": { "type": "string" },
                "address": { "type": "string" },
                "address_zh": { "type": "string" },
                "shipping_mark_format": { "type": "string" },
                "contact_phone": { "type": "string" },
                "wechat": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}