{
  "openapi": "3.1.0",
  "info": {
    "title": "Rentsilvania Rent a Car Public API",
    "version": "1.0.3",
    "description": "Public, read-only API for locations, cars, availability and quotes.\nRequests use European date format DD-MM-YYYY in query/body fields named pick_up_date and delivery_date.\nResponses keep current field names and formats (e.g., pickup_date/return_date in ISO YYYY-MM-DD).",
    "contact": {
      "name": "API Support",
      "url": "https://rentsilvania.ro/p-contact",
      "email": "office@phprentacar.ro"
    },
    "termsOfService": "https://rentsilvania.ro/p-termeni-si-conditii"
  },
  "servers": [
    { "url": "https://rentsilvania.ro" }
  ],
  "paths": {
    "/api/v1/locations": {
      "get": {
        "summary": "List rental locations",
        "operationId": "listLocations",
        "parameters": [
          { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Optional free-text filter (city, IATA, name)" }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationList" } } } }
        }
      }
    },

    "/api/v1/cars": {
      "get": {
        "summary": "List car models with optional date-based lead pricing",
        "description": "If pick_up_date and delivery_date are provided (DD-MM-YYYY), response includes total price for that interval and an availability hint. Without them, only base per-day pricing is returned.",
        "operationId": "listCars",
        "parameters": [
          { "in": "query", "name": "car_id", "schema": { "type": "string" }, "description": "Optional filter by car/model id" },
          { "in": "query", "name": "pick_up_date", "schema": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$" }, "description": "DD-MM-YYYY" },
          { "in": "query", "name": "delivery_date", "schema": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$" }, "description": "DD-MM-YYYY" },
          { "in": "query", "name": "category", "schema": { "type": "string" }, "description": "economy|compact|suv|minivan|premium (normalized)" },
          { "in": "query", "name": "transmission", "schema": { "type": "string", "enum": ["manual","automatic"] } },
          { "in": "query", "name": "ac", "schema": { "type": "boolean" } },
          { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "in": "query", "name": "page_size", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": { "ETag": { "description": "Entity tag for caching", "schema": { "type": "string" } } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarCatalogPage" } } }
          }
        }
      }
    },

    "/api/v1/cars/{car_id}": {
      "get": {
        "summary": "Get details for a specific car model",
        "operationId": "getCar",
        "parameters": [
          { "in": "path", "name": "car_id", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarDetail" } } } },
          "404": { "description": "Not found" }
        }
      }
    },

    "/api/v1/availability": {
      "get": {
        "summary": "Check precise availability for a model in a date range",
        "description": "Returns whether the model is available and how many units remain.",
        "operationId": "checkAvailability",
        "parameters": [
          { "in": "query", "name": "car_id", "required": true, "schema": { "type": "string" } },
          { "in": "query", "name": "pick_up_date", "required": true, "schema": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$" }, "description": "DD-MM-YYYY" },
          { "in": "query", "name": "delivery_date", "required": true, "schema": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$" }, "description": "DD-MM-YYYY" }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityResponse" } } } },
          "400": { "description": "Bad request (missing or invalid dates/id)" },
          "404": { "description": "Car model not found" }
        }
      }
    },

    "/api/v1/quote": {
      "post": {
        "summary": "Get final price quote for a rental (all extras per day)",
        "description": "Calculates totals for the requested interval. Requests accept pick_up_date and delivery_date in DD-MM-YYYY; response keeps pickup_date/return_date as you currently return them.",
        "operationId": "createQuote",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/QuoteRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } },
          "400": { "description": "Bad request (missing car_id or invalid dates)" },
          "404": { "description": "Car model not found" },
          "409": { "description": "Car not available for requested interval" }
        }
      }
    }
  },

  "components": {
    "schemas": {
      "Location": {
        "type": "object",
        "required": ["id","name","address","timezone"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "iata_code": { "type": "string", "nullable": true },
          "address": {
            "type": "object",
            "properties": {
              "street": { "type": "string", "nullable": true },
              "city": { "type": "string" },
              "region": { "type": "string", "nullable": true },
              "postal_code": { "type": "string", "nullable": true },
              "country_code": { "type": "string" }
            }
          },
          "timezone": { "type": "string", "description": "IANA TZ, e.g., Europe/Bucharest" }
        }
      },
      "LocationList": {
        "type": "object",
        "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } } }
      },

      "Car": {
        "type": "object",
        "required": ["id","make","model"],
        "properties": {
          "id": { "type": "string" },
          "make": { "type": "string" },
          "model": { "type": "string" },
          "year": { "type": "integer", "nullable": true },
          "category": { "type": "string", "nullable": true, "description": "economy|compact|suv|minivan|premium" },
          "category_label_ro": { "type": "string", "nullable": true },
          "seats": { "type": "integer", "nullable": true },
          "doors": { "type": "integer", "nullable": true },
          "luggage_small": { "type": "integer", "nullable": true },
          "luggage_large": { "type": "integer", "nullable": true },
          "transmission": { "type": "string", "enum": ["manual","automatic"], "nullable": true },
          "ac": { "type": "boolean", "nullable": true },
          "fuel_type": { "type": "string", "enum": ["petrol","diesel","hybrid","electric"], "nullable": true },
          "features": { "type": "array", "items": { "type": "string" } },
          "images": {
            "type": "array",
            "items": { "type": "object", "properties": {
              "url": { "type": "string", "format": "uri" },
              "alt": { "type": "string" }
            } }
          }
        }
      },

      "LeadPrice": {
        "type": "object",
        "description": "Response pricing block (kept as currently implemented).",
        "properties": {
          "currency": { "type": "string", "default": "EUR" },
          "price_per_day": { "type": "number", "nullable": true },
          "total_price": { "type": "number", "nullable": true },
          "availability_hint": { "type": "string", "enum": ["in_stock","limited","unavailable"], "nullable": true },
          "pickup_date": { "type": "string", "format": "date", "nullable": true, "description": "YYYY-MM-DD (response field, unchanged)" },
          "return_date": { "type": "string", "format": "date", "nullable": true, "description": "YYYY-MM-DD (response field, unchanged)" }
        }
      },

      "CarCatalogItem": {
        "allOf": [
          { "$ref": "#/components/schemas/Car" },
          { "type": "object", "properties": { "lead_price": { "$ref": "#/components/schemas/LeadPrice" }, "jsonld": { "type": "object", "nullable": true } } }
        ]
      },

      "CarCatalogPage": {
        "type": "object",
        "properties": {
          "total": { "type": "integer" },
          "page": { "type": "integer", "nullable": true },
          "page_size": { "type": "integer", "nullable": true },
          "links": { "type": "object", "nullable": true, "properties": {
            "next": { "type": "string", "format": "uri", "nullable": true },
            "prev": { "type": "string", "format": "uri", "nullable": true }
          } },
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/CarCatalogItem" } }
        }
      },

      "CarDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/Car" },
          { "type": "object", "properties": {
            "description": { "type": "string", "nullable": true },
            "included": { "type": "array", "items": { "type": "string" }, "nullable": true },
            "policies": { "type": "object", "properties": {
              "mileage_policy": { "type": "string", "nullable": true },
              "fuel_policy": { "type": "string", "nullable": true },
              "deposit_amount": { "type": "number", "nullable": true },
              "age_requirement": { "type": "string", "nullable": true },
              "cancellation_policy": { "type": "string", "nullable": true },
              "terms_url": { "type": "string", "format": "uri", "nullable": true }
            } },
            "base_price": { "type": "object", "properties": {
              "currency": { "type": "string", "default": "EUR" },
              "price_per_day": { "type": "number" }
            } },
            "extras": { "type": "array", "items": { "type": "object", "properties": {
              "code": { "type": "string" },
              "label": { "type": "string" },
              "price_per_day": { "type": "number" },
              "currency": { "type": "string", "default": "EUR" },
              "max_quantity": { "type": "integer", "nullable": true }
            } }, "nullable": true },
            "links": { "type": "object", "properties": {
              "self": { "type": "string", "format": "uri" },
              "availability": { "type": "string", "format": "uri", "nullable": true },
              "quote": { "type": "string", "format": "uri", "nullable": true }
            } },
            "jsonld": { "type": "object", "nullable": true }
          } }
        ]
      },

      "AvailabilityResponse": {
        "type": "object",
        "description": "Response fields kept as implemented (ISO dates & names).",
        "required": ["car_id","pickup_date","return_date","available"],
        "properties": {
          "car_id": { "type": "string" },
          "pickup_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD (response field, unchanged)" },
          "return_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD (response field, unchanged)" },
          "available": { "type": "boolean" },
          "remaining_units": { "type": "integer", "nullable": true },
          "reasons": { "type": "array", "items": { "type": "string" }, "nullable": true },
          "notes": { "type": "string", "nullable": true },
          "jsonld": { "type": "object", "nullable": true }
        }
      },

      "PriceBreakdownLine": {
        "type": "object",
        "properties": {
          "label": { "type": "string" },
          "detail": { "type": "string" },
          "amount": { "type": "number" },
          "currency": { "type": "string" }
        }
      },

      "QuoteRequest": {
        "type": "object",
        "required": ["car_id","pick_up_date","delivery_date"],
        "properties": {
          "car_id": { "type": "string" },
          "pick_up_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-YYYY" },
          "delivery_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-YYYY" },
          "pickup_time": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "nullable": true },
          "return_time": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "nullable": true },
          "currency": { "type": "string", "default": "EUR" },
          "extras": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Optional map of extra_code -> quantity (per day)." }
        }
      },

      "QuoteResponse": {
        "type": "object",
        "description": "Response fields kept as implemented (pickup_date/return_date ISO).",
        "required": ["car_id","pickup_date","return_date","rental_days","currency","price_per_day","base_total","extras_total","total_price","breakdown"],
        "properties": {
          "car_id": { "type": "string" },
          "pickup_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD (response field, unchanged)" },
          "return_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD (response field, unchanged)" },
          "pickup_time": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "nullable": true },
          "return_time": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "nullable": true },
          "rental_days": { "type": "integer", "minimum": 1 },
          "currency": { "type": "string" },
          "price_per_day": { "type": "number" },
          "base_total": { "type": "number" },
          "extras_total": { "type": "number" },
          "total_price": { "type": "number" },
          "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/PriceBreakdownLine" } },
          "links": { "type": "object", "nullable": true, "properties": {
            "car": { "type": "string", "format": "uri" },
            "availability": { "type": "string", "format": "uri" }
          } },
          "jsonld": { "type": "object", "nullable": true }
        }
      }
    }
  }
}