{
  "openapi": "3.1.0",
  "info": {
    "title": "LOI E-Commerce API",
    "description": "Public API for LOI - Somos la Oferta Irresistible, las mejores ofertas al mejor precio de las mejores marcas y con los envíos más rápidos en tiempo récord. This API allows AI agents and developers to search products, browse categories, check prices and availability, find physical stores, and access product feeds.",
    "version": "1.0.0",
    "contact": {
      "name": "LOI Support",
      "url": "https://loi.com.uy/contacto-soporte",
      "email": "soporte@loi.com.uy"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://loi.com.uy/terminos"
    },
    "x-logo": {
      "url": "https://loi.com.uy/assets_uy/favicons/mstile-310x310.png"
    }
  },
  "servers": [
    {
      "url": "https://loi.com.uy",
      "description": "LOI Uruguay Production"
    },
    {
      "url": "https://loichile.cl",
      "description": "LOI Chile Production"
    },
    {
      "url": "https://mibelleza.uy",
      "description": "MiBelleza Production"
    }
  ],
  "paths": {
    "/index.php": {
      "get": {
        "operationId": "apiDispatcher",
        "summary": "Main API dispatcher",
        "description": "All API actions are dispatched through index.php using ctrl and act query parameters.",
        "parameters": [
          {
            "name": "ctrl",
            "in": "query",
            "required": true,
            "description": "Controller name (e.g., productos, index, buscar, colecciones, tiendas, landing)",
            "schema": { "type": "string" }
          },
          {
            "name": "act",
            "in": "query",
            "required": true,
            "description": "Action name within the controller",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/products.json": {
      "get": {
        "operationId": "getProductFeed",
        "summary": "Get machine-readable product feed",
        "description": "Returns a structured JSON feed of products for AI agents and data consumers. Supports pagination, filtering by category, brand, and search query.",
        "tags": ["Products"],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number (starts at 1)",
            "schema": { "type": "integer", "default": 1, "minimum": 1 }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Products per page (max 100)",
            "schema": { "type": "integer", "default": 24, "maximum": 100 }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by category slug",
            "schema": { "type": "string" }
          },
          {
            "name": "brand",
            "in": "query",
            "description": "Filter by brand slug",
            "schema": { "type": "string" }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Search query for full-text product search",
            "schema": { "type": "string" }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order for results",
            "schema": {
              "type": "string",
              "enum": ["relevancia", "precio-asc", "precio-desc", "novedades", "nombre-asc", "nombre-desc", "descuento"]
            }
          },
          {
            "name": "in_stock",
            "in": "query",
            "description": "Filter to only in-stock products",
            "schema": { "type": "boolean", "default": true }
          }
        ],
        "responses": {
          "200": {
            "description": "Product feed response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductFeedResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying",
                "schema": { "type": "integer" }
              }
            }
          }
        }
      }
    },
    "/ficha/{productSlug}": {
      "get": {
        "operationId": "getProductDetail",
        "summary": "Get product detail page",
        "description": "Returns the product detail page with embedded JSON-LD structured data (Schema.org Product). Parse the JSON-LD script tag for machine-readable product data including name, price, availability, brand, rating, and images.",
        "tags": ["Products"],
        "parameters": [
          {
            "name": "productSlug",
            "in": "path",
            "required": true,
            "description": "SEO-friendly product URL slug",
            "schema": { "type": "string" },
            "example": "carolina-herrera-good-girl-edp-80ml"
          }
        ],
        "responses": {
          "200": {
            "description": "Product detail page with JSON-LD structured data",
            "content": {
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          },
          "404": {
            "description": "Product not found"
          }
        }
      }
    },
    "/ver/{viewType}/{categorySlug}/{sortOrder}": {
      "get": {
        "operationId": "browseCategory",
        "summary": "Browse products by category",
        "description": "Returns product listing page for a given category with embedded structured data. Products are displayed in a grid or list view with pagination.",
        "tags": ["Categories"],
        "parameters": [
          {
            "name": "viewType",
            "in": "path",
            "required": true,
            "description": "View layout type",
            "schema": { "type": "string", "enum": ["cuadricula", "lista"] }
          },
          {
            "name": "categorySlug",
            "in": "path",
            "required": true,
            "description": "Category URL slug",
            "schema": { "type": "string" },
            "example": "perfumes-mujer"
          },
          {
            "name": "sortOrder",
            "in": "path",
            "required": true,
            "description": "Sort order",
            "schema": {
              "type": "string",
              "enum": ["relevancia", "asc", "desc", "novedades", "nombre-asc", "nombre-desc", "descuento"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Category product listing page"
          }
        }
      }
    },
    "/categorias": {
      "get": {
        "operationId": "getAllCategories",
        "summary": "Get all product categories",
        "description": "Returns a page listing all product categories with their hierarchy. Use the JSON API endpoint ctrl=index&act=categorias for machine-readable category data.",
        "tags": ["Categories"],
        "responses": {
          "200": {
            "description": "Categories listing page"
          }
        }
      }
    },
    "/colecciones": {
      "get": {
        "operationId": "getAllCollections",
        "summary": "Get all product collections",
        "description": "Returns curated product collections (seasonal, thematic, promotional). Use ctrl=index&act=colecciones for JSON data.",
        "tags": ["Collections"],
        "responses": {
          "200": {
            "description": "Collections listing page"
          }
        }
      }
    },
    "/especial/{collectionSlug}": {
      "get": {
        "operationId": "getCollection",
        "summary": "Get a specific collection",
        "description": "Returns products in a curated collection (e.g., Dia de la Madre, Black Friday, Summer Essentials).",
        "tags": ["Collections"],
        "parameters": [
          {
            "name": "collectionSlug",
            "in": "path",
            "required": true,
            "description": "Collection URL slug",
            "schema": { "type": "string" },
            "example": "dia-de-la-madre"
          }
        ],
        "responses": {
          "200": {
            "description": "Collection detail page with products"
          }
        }
      }
    },
    "/marcas-premium": {
      "get": {
        "operationId": "getAllBrands",
        "summary": "Get all premium brands",
        "description": "Returns a directory of all premium brands available on LOI.",
        "tags": ["Brands"],
        "responses": {
          "200": {
            "description": "Brands directory page"
          }
        }
      }
    },
    "/tienda/{brandSlug}": {
      "get": {
        "operationId": "getBrandStore",
        "summary": "Get brand store page",
        "description": "Returns the brand's dedicated store page with their product catalog.",
        "tags": ["Brands"],
        "parameters": [
          {
            "name": "brandSlug",
            "in": "path",
            "required": true,
            "description": "Brand URL slug",
            "schema": { "type": "string" },
            "example": "carolina-herrera"
          }
        ],
        "responses": {
          "200": {
            "description": "Brand store page"
          }
        }
      }
    },
    "/tiendas": {
      "get": {
        "operationId": "getPhysicalStores",
        "summary": "Get physical store locations",
        "description": "Returns all physical store locations with addresses, hours, and GPS coordinates. Use ctrl=index&act=tiendasOficialesJson for JSON data.",
        "tags": ["Stores"],
        "responses": {
          "200": {
            "description": "Physical stores listing with LocalBusiness schema"
          }
        }
      }
    },
    "/buscar": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search products",
        "description": "Algolia-powered full-text product search with typo tolerance, autocomplete, and faceted filtering. Append #q={search_term} for the search query.",
        "tags": ["Search"],
        "responses": {
          "200": {
            "description": "Search results page"
          }
        }
      }
    },
    "/novedades": {
      "get": {
        "operationId": "getNewArrivals",
        "summary": "Get new product arrivals",
        "description": "Returns the latest products added to the catalog.",
        "tags": ["Products"],
        "responses": {
          "200": {
            "description": "New arrivals listing page"
          }
        }
      }
    },
    "/hotsale": {
      "get": {
        "operationId": "getHotSaleProducts",
        "summary": "Get hot sale / deals",
        "description": "Returns current promotional products, flash sales, and limited-time offers.",
        "tags": ["Offers"],
        "responses": {
          "200": {
            "description": "Hot sale products listing page"
          }
        }
      }
    },
    "/rastrea-tu-compra/{orderNumber}": {
      "get": {
        "operationId": "trackOrder",
        "summary": "Track an order",
        "description": "Returns order tracking information including current status and delivery updates.",
        "tags": ["Orders"],
        "parameters": [
          {
            "name": "orderNumber",
            "in": "path",
            "required": true,
            "description": "Order number (e.g., LOI-12345)",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Order tracking page with status information"
          },
          "404": {
            "description": "Order not found"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "Get AI agent summary document",
        "description": "Returns a concise description of LOI for AI language models, including site overview, capabilities, and key endpoints.",
        "tags": ["AI Discovery"],
        "responses": {
          "200": {
            "description": "LLMs.txt content",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getLlmsFullTxt",
        "summary": "Get comprehensive AI agent reference",
        "description": "Returns the complete reference document for AI agents interacting with LOI, including detailed API documentation, data schemas, and integration guides.",
        "tags": ["AI Discovery"],
        "responses": {
          "200": {
            "description": "Full LLMs reference content",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "integer", "description": "HTTP status code" },
          "data": { "type": "object", "description": "Response payload" },
          "message": { "type": "string", "description": "Human-readable status message" }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "description": "Unique product identifier" },
          "title": { "type": "string", "description": "Product title in Spanish" },
          "slug": { "type": "string", "description": "SEO-friendly URL slug" },
          "description": { "type": "string", "description": "Product description (may contain HTML)" },
          "sku": { "type": "string", "description": "Stock Keeping Unit code" },
          "brand": { "$ref": "#/components/schemas/Brand" },
          "category": { "$ref": "#/components/schemas/Category" },
          "price": { "$ref": "#/components/schemas/Price" },
          "availability": {
            "type": "string",
            "enum": ["in_stock", "out_of_stock", "preorder"],
            "description": "Current stock status"
          },
          "images": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Image" },
            "description": "Product images"
          },
          "rating": { "$ref": "#/components/schemas/Rating" },
          "url": { "type": "string", "format": "uri", "description": "Full product page URL" },
          "condition": { "type": "string", "enum": ["new", "used", "refurbished"], "default": "new" },
          "warranty": { "type": "string", "description": "Warranty information" }
        },
        "required": ["id", "title", "slug", "price", "availability", "url"]
      },
      "Brand": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "logo_url": { "type": "string", "format": "uri" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "parent": { "type": "string", "nullable": true },
          "hierarchy": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Full category path from root"
          }
        }
      },
      "Price": {
        "type": "object",
        "properties": {
          "amount": { "type": "number", "description": "Current price" },
          "currency": { "type": "string", "description": "ISO 4217 currency code (UYU, CLP)" },
          "original_amount": { "type": "number", "nullable": true, "description": "Original price before discount" },
          "discount_percentage": { "type": "number", "nullable": true, "description": "Discount percentage if on sale" }
        },
        "required": ["amount", "currency"]
      },
      "Image": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "alt": { "type": "string" },
          "width": { "type": "integer" },
          "height": { "type": "integer" }
        }
      },
      "Rating": {
        "type": "object",
        "properties": {
          "average": { "type": "number", "minimum": 0, "maximum": 5 },
          "count": { "type": "integer", "minimum": 0 }
        }
      },
      "ProductFeedResponse": {
        "type": "object",
        "properties": {
          "version": { "type": "string", "example": "1.0" },
          "title": { "type": "string", "example": "LOI Product Feed" },
          "home_page_url": { "type": "string", "format": "uri" },
          "feed_url": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "language": { "type": "string", "example": "es" },
          "total_products": { "type": "integer" },
          "page": { "type": "integer" },
          "per_page": { "type": "integer" },
          "total_pages": { "type": "integer" },
          "products": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Product" }
          },
          "_links": {
            "type": "object",
            "properties": {
              "self": { "type": "string", "format": "uri" },
              "next": { "type": "string", "format": "uri", "nullable": true },
              "prev": { "type": "string", "format": "uri", "nullable": true },
              "first": { "type": "string", "format": "uri" },
              "last": { "type": "string", "format": "uri" }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "format": "uri", "description": "Error type URI (RFC 7807)" },
          "title": { "type": "string", "description": "Short error title" },
          "status": { "type": "integer", "description": "HTTP status code" },
          "detail": { "type": "string", "description": "Human-readable error description" },
          "instance": { "type": "string", "description": "URI of the specific request that failed" }
        },
        "required": ["type", "title", "status"]
      }
    }
  },
  "tags": [
    { "name": "Products", "description": "Product catalog operations" },
    { "name": "Categories", "description": "Product category browsing" },
    { "name": "Collections", "description": "Curated product collections" },
    { "name": "Brands", "description": "Brand directory and stores" },
    { "name": "Search", "description": "Product search" },
    { "name": "Offers", "description": "Deals, promotions, and hot sales" },
    { "name": "Stores", "description": "Physical store locations" },
    { "name": "Orders", "description": "Order tracking" },
    { "name": "AI Discovery", "description": "AI agent discovery and documentation endpoints" }
  ],
  "externalDocs": {
    "description": "Full AI Agent Reference (llms-full.txt)",
    "url": "https://loi.com.uy/llms-full.txt"
  }
}