{
  "openapi": "3.0.3",
  "info": {
    "title": "City Courier Services public tracking API",
    "description": "Look up a City Courier consignment by tracking number. This is the same endpoint the website Track form uses. It does not book pickups, list customers, or expose staff accounts.",
    "version": "1.0.0",
    "contact": {
      "name": "City Courier Services",
      "email": "query@citycourierservices.in",
      "url": "https://citycourierservices.in/"
    }
  },
  "servers": [
    {
      "url": "https://api.citycourierservices.in",
      "description": "Production tracking API"
    }
  ],
  "paths": {
    "/api/v1/tracking/{consignmentNo}": {
      "get": {
        "operationId": "getConsignmentTracking",
        "summary": "Get scan history for a City Courier consignment",
        "description": "Returns booked-on time, latest status, and scan events for a City Courier tracking number. Numbers from other courier brands will not resolve.",
        "tags": ["Tracking"],
        "parameters": [
          {
            "name": "consignmentNo",
            "in": "path",
            "required": true,
            "description": "City Courier consignment / tracking number as printed on the receipt.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "example": "CCS123456789"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tracking found, or a JSON error payload when the number is unknown.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackingResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TrackingScan": {
        "type": "object",
        "description": "One scan event on the consignment journey.",
        "properties": {
          "status": {
            "type": "string",
            "description": "Scan status label from operations."
          },
          "scannedOn": {
            "type": "string",
            "description": "When this scan was recorded."
          }
        }
      },
      "Tracking": {
        "type": "object",
        "description": "Consignment tracking details shown on the public website.",
        "properties": {
          "consignmentNo": {
            "type": "string"
          },
          "bookedOn": {
            "type": "string",
            "description": "When the shipment was booked."
          },
          "bookedStatus": {
            "type": "string",
            "description": "Status at booking, usually BOOKED."
          },
          "scans": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrackingScan"
            }
          }
        }
      },
      "TrackingResponse": {
        "type": "object",
        "required": ["success"],
        "properties": {
          "success": {
            "type": "boolean",
            "description": "true when tracking was found."
          },
          "message": {
            "type": "string",
            "description": "Human-readable error when success is false."
          },
          "tracking": {
            "$ref": "#/components/schemas/Tracking"
          }
        }
      }
    }
  }
}