{
  "openapi": "3.1.0",
  "info": {
    "title": "Deccan Crackers Ordering API",
    "version": "1.0.0",
    "description": "Live catalogue, prices, delivery areas and ordering for Deccan Crackers — a Diwali crackers shop on Narsingi – Puppalaguda Main Road, Hyderabad (near Manikonda), selling since 2019. Prices are INR incl. GST. An order-value discount (5% from ₹2,000, 10% from ₹5,000, 15% from ₹10,000, 20% from ₹20,000, free gift from ₹15,000) is applied automatically. Delivery charge is NOT charged online; it is paid at the door. Orders are confirmed only after the customer pays on the returned payment_url. Crackers are sold to adults (18+) only.",
    "contact": { "name": "Deccan Crackers", "email": "info@deccancrackers.com", "url": "https://www.deccancrackers.com/order-with-ai" }
  },
  "servers": [{ "url": "https://www.deccancrackers.com/api/v1" }],
  "paths": {
    "/store": {
      "get": {
        "operationId": "getStoreInfo",
        "summary": "Store facts: address, hours, season dates, delivery rules, discount ladder, order-link format.",
        "responses": { "200": { "description": "Store info", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List product categories with item counts and starting prices.",
        "responses": { "200": { "description": "Categories", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/products": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search crackers and combos. Use filters to match the user's budget, family and noise preferences.",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free text, e.g. '1000 wala', 'sparklers', 'anar', 'sky shot'" },
          { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["combo-offers", "flower-pots", "sparklers", "ground-chakkars", "rockets", "fancy-fireworks", "bombs", "garlands", "caps-guns-pop-pop", "kids-special", "gift-boxes"] } },
          { "name": "best_for", "in": "query", "schema": { "type": "string", "enum": ["kids", "family", "sky-show", "sound", "gifting", "community"] } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["single", "combo"] } },
          { "name": "sound_level", "in": "query", "schema": { "type": "string", "enum": ["none", "low", "medium", "high"] } },
          { "name": "max_price", "in": "query", "schema": { "type": "number" }, "description": "Maximum unit price in INR" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }
        ],
        "responses": { "200": { "description": "Products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } } }
      }
    },
    "/products/{slug}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Full details of one product or combo (combos include their contents).",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "404": { "description": "Not found" } }
      }
    },
    "/combos": {
      "get": {
        "operationId": "listCombos",
        "summary": "Ready-made Diwali combos (₹999 to ₹20,499), priced below the items inside.",
        "responses": { "200": { "description": "Combos", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/areas": {
      "get": {
        "operationId": "checkDeliveryArea",
        "summary": "Check whether an area or PIN code gets 30-minute express delivery or scheduled delivery.",
        "parameters": [
          { "name": "pincode", "in": "query", "schema": { "type": "string" } },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Area name, e.g. Manikonda" }
        ],
        "responses": { "200": { "description": "Areas", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/quote": {
      "post": {
        "operationId": "quoteCart",
        "summary": "Price a cart with live prices and automatic discounts. Returns an order_link the user can open to check out themselves (no API key needed).",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } },
        "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/orders": {
      "post": {
        "operationId": "createOrder",
        "summary": "Create a pending order for the user and get a secure payment_url. Only call after the user has confirmed items, name, mobile, fulfilment (express/scheduled/pickup), area and address, and confirmed they are 18+.",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } } },
        "responses": {
          "201": { "description": "Order created — give the user payment_url", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "description": "Missing / invalid API key" },
          "422": { "description": "Validation error (details explain what to ask the user)" },
          "429": { "description": "Rate limited" }
        }
      }
    },
    "/orders/{number}": {
      "get": {
        "operationId": "getOrderStatus",
        "summary": "Order status for the customer (needs the mobile number used on the order).",
        "parameters": [
          { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "phone", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found" } }
      }
    }
  },
  "components": {
    "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } },
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "category": { "type": "string" },
          "brand": { "type": ["string", "null"] }, "pack": { "type": ["string", "null"] }, "price_inr": { "type": "number" },
          "mrp_inr": { "type": ["number", "null"] }, "percent_off_mrp": { "type": ["integer", "null"] }, "sound_level": { "type": ["string", "null"] },
          "best_for": { "type": "array", "items": { "type": "string" } }, "in_stock": { "type": "boolean" }, "url": { "type": "string" }, "summary": { "type": ["string", "null"] }
        }
      },
      "ProductList": { "type": "object", "properties": { "count": { "type": "integer" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } },
      "CartItem": { "type": "object", "required": ["slug", "qty"], "properties": { "slug": { "type": "string" }, "qty": { "type": "integer", "minimum": 1, "maximum": 50 } } },
      "QuoteRequest": {
        "type": "object", "required": ["items"],
        "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } }, "code": { "type": "string", "description": "Optional code e.g. EARLYBIRD" } }
      },
      "OrderRequest": {
        "type": "object", "required": ["items", "customer", "fulfilment", "age_confirmed"],
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } },
          "code": { "type": "string" },
          "customer": { "type": "object", "required": ["name", "phone"], "properties": { "name": { "type": "string" }, "phone": { "type": "string", "description": "10-digit Indian mobile" }, "email": { "type": "string" } } },
          "fulfilment": { "type": "string", "enum": ["express", "scheduled", "pickup"], "description": "express only during store hours 1–10 Nov 10:00–01:00 and express areas" },
          "area_slug": { "type": "string", "description": "From GET /areas (required unless pickup)" },
          "delivery_date": { "type": "string", "format": "date", "description": "2026-11-01 … 2026-11-10 (scheduled / pickup)" },
          "delivery_slot": { "type": "string", "enum": ["10:00-13:00", "13:00-16:00", "16:00-19:00", "19:00-22:00", "22:00-01:00"] },
          "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "landmark": { "type": "string" }, "pincode": { "type": "string" } } },
          "note": { "type": "string" },
          "age_confirmed": { "type": "boolean", "description": "Buyer confirmed they are 18 or older" }
        }
      }
    }
  }
}