# LOI - La Oferta Irresistible - Complete AI Agent Reference

> This is the comprehensive reference document for AI agents interacting with LOI,
> Uruguay's leading multi-brand e-commerce platform for beauty, personal care,
> fragrances, and lifestyle products.

## Table of Contents

1. [Platform Overview](#platform-overview)
2. [Product Catalog Structure](#product-catalog-structure)
3. [URL Structure & Navigation](#url-structure--navigation)
4. [API Reference](#api-reference)
5. [Structured Data Schemas](#structured-data-schemas)
6. [Search Capabilities](#search-capabilities)
7. [Pricing & Offers](#pricing--offers)
8. [Shipping & Logistics](#shipping--logistics)
9. [Payment Methods](#payment-methods)
10. [User Accounts & Loyalty](#user-accounts--loyalty)
11. [Physical Stores](#physical-stores)
12. [Multi-Brand Architecture](#multi-brand-architecture)
13. [Agent Integration Guide](#agent-integration-guide)
14. [Content Policies](#content-policies)

---

## Platform Overview

**Company:** LOI - La Oferta Irresistible S.A.
**Founded:** 2008
**Headquarters:** Montevideo, Uruguay
**Markets:** Uruguay, Chile
**Industry:** E-commerce, Beauty & Personal Care
**Languages:** Spanish (es-UY, es-CL)
**Currencies:** UYU (Uruguayan Peso), CLP (Chilean Peso)

### Brands

| Brand | Domain | Market | Focus |
|-------|--------|--------|-------|
| LOI Uruguay | loi.com.uy | Uruguay | Beauty, fragrances, lifestyle, electronics |
| LOI Chile | loi.cl | Chile | Beauty, fragrances, lifestyle |
| MiBelleza | mibelleza.uy | Uruguay | Specialized beauty & skincare |

### Platform Capabilities

- Full e-commerce with cart, checkout, and order tracking
- Algolia-powered product search with autocomplete
- Personalized recommendations (LoadStone AI)
- Customer reviews and ratings (1-5 stars)
- Wishlist and favorites
- Real-time chat support (WebSocket-based)
- WhatsApp integration for customer service
- Push notifications (Firebase)
- Progressive Web App (PWA) support
- Multi-currency and multi-country support
- Gift card and store credit system
- Loyalty gamification program (Penca)

---

## Product Catalog Structure

### Category Hierarchy

LOI organizes products in a hierarchical category tree:

```
Level 1: Department (e.g., "Fragancias", "Cuidado de la Piel")
  Level 2: Category (e.g., "Perfumes Mujer", "Hidratantes")
    Level 3: Subcategory (e.g., "Eau de Parfum", "Cremas de Dia")
```

### Main Departments

1. **Fragancias** - Perfumes, colognes, body mists, gift sets
2. **Maquillaje** - Foundation, lips, eyes, face, tools
3. **Cuidado de la Piel** - Moisturizers, serums, cleansers, masks, sunscreen
4. **Cuidado del Cabello** - Shampoo, conditioner, treatments, styling
5. **Cuidado Personal** - Body care, deodorants, oral care, shaving
6. **Bebe y Ninos** - Baby skincare, hygiene, sun protection
7. **Hogar** - Candles, diffusers, home fragrances
8. **Salud y Bienestar** - Supplements, vitamins, natural remedies
9. **Accesorios** - Beauty tools, brushes, bags, mirrors
10. **Sets y Kits** - Gift sets, curated collections, travel kits

### Product Attributes

Each product contains:
- `prod_id` - Unique product identifier
- `prod_titulo` - Product title (Spanish)
- `prod_desc` - Full HTML description
- `prod_sku` - Stock Keeping Unit code
- `prod_precio` - Current price
- `prod_precio_anterior` - Previous/original price (if discounted)
- `prod_moneda` - Currency code
- `prod_moneda_iso_alfabetico` - ISO 4217 currency code
- `prod_foto_ppal` - Main product image URL
- `prod_foto_ppal_titulo` - Image alt text
- `prod_garantia` - Warranty information
- `stock` - Current inventory availability
- `fab_nombre` - Brand/manufacturer name
- `friendly_url` - SEO-friendly URL slug
- `promedio_calificaciones` - Average rating (1-5)
- `cantidad_calificaciones` - Number of reviews

### Product Variations

Products may have variations (e.g., sizes, colors):
- Variations share the same parent product
- Each variation has its own price, stock, and SKU
- Variation attributes include: size (ml/oz), color, scent variant

---

## URL Structure & Navigation

### Page URL Patterns

| Page Type | URL Pattern | Example |
|-----------|-------------|---------|
| Homepage | `/` | `loi.com.uy/` |
| Product Detail | `/ficha/{slug}` | `/ficha/carolina-herrera-good-girl-edp-80ml` |
| Category Browse | `/ver/{type}/{category}/{sort}` | `/ver/cuadricula/perfumes-mujer/relevancia` |
| Category Landing | `/categorias/{slug}` | `/categorias/fragancias` |
| Brand Store | `/tienda/{slug}` | `/tienda/carolina-herrera` |
| Collection | `/especial/{slug}` | `/especial/dia-de-la-madre` |
| Search | `/buscar` | `/buscar#q=perfume` |
| New Arrivals | `/novedades` | `/novedades` |
| Hot Sale | `/hotsale` | `/hotsale` |
| Cart | `/carrito` | `/carrito` |
| Order Tracking | `/rastrea-tu-compra/{order}` | `/rastrea-tu-compra/LOI-12345` |
| Physical Stores | `/tiendas` | `/tiendas` |
| Contact (Sales) | `/contacto-venta` | `/contacto-venta` |
| Contact (Shipping) | `/contacto-envio` | `/contacto-envio` |
| Contact (Support) | `/contacto-soporte` | `/contacto-soporte` |
| Policies | `/politicas` | `/politicas` |
| Terms | `/terminos` | `/terminos` |
| User Account | `/panel-de-usuario` | `/panel-de-usuario` |
| Purchase History | `/compras` | `/compras` |
| All Brands | `/marcas-premium` | `/marcas-premium` |
| All Collections | `/colecciones` | `/colecciones` |
| All Categories | `/categorias` | `/categorias` |
| Recommendations | `/recomendados` | `/recomendados` |

### Breadcrumb Structure

All pages implement breadcrumb navigation:
```
Home > Department > Category > Subcategory > Product Name
```

Breadcrumbs are available as:
- Visual HTML navigation elements
- JSON-LD BreadcrumbList schema

### Sorting Options

Product listings support these sort orders:
- `relevancia` - Relevance (default)
- `asc` - Price ascending
- `desc` - Price descending
- `novedades` - Newest first
- `nombre-asc` - Name A-Z
- `nombre-desc` - Name Z-A
- `descuento` - Biggest discounts first

### Pagination

Product listings use offset-based pagination:
- Parameter: `pagina={page_number}` or `offset={offset}`
- Default page size: 24 products
- Response includes total count for calculating pages

---

## API Reference

### Base URL Pattern

All API endpoints follow: `{domain}/index.php?ctrl={controller}&act={action}&{params}`

### Public Endpoints (No Authentication Required)

#### Products

| Endpoint | Method | Description |
|----------|--------|-------------|
| `?ctrl=productos&act=buscar&q={query}` | GET | Search products by text |
| `?ctrl=productos&act=detalle&prod_urlseo={slug}` | GET | Get product detail by slug |
| `?ctrl=productos&act=lista_productos&categ_urlseo={category}` | GET | List products by category |
| `?ctrl=index&act=novedades&cantidad={limit}` | GET | Get new arrivals |
| `?ctrl=index&act=obtenerOfertas&pagina={page}&cantidad={limit}` | GET | Get current offers |
| `?ctrl=index&act=tendencias&pagina={page}&cantidad={limit}` | GET | Get trending products |

#### Categories & Navigation

| Endpoint | Method | Description |
|----------|--------|-------------|
| `?ctrl=index&act=categorias` | GET | Get all categories tree |
| `?ctrl=index&act=colecciones` | GET | Get all collections |
| `?ctrl=index&act=tiendasOficialesJson` | GET | Get all brand stores |
| `?ctrl=index&act=tiendasOficialesJson&destacadas=1` | GET | Get featured stores |
| `?ctrl=index&act=cargarListadoTarjetasJSON` | GET | Get payment methods |

#### Content

| Endpoint | Method | Description |
|----------|--------|-------------|
| `?ctrl=index&act=cargarListadoDiapositivasJSON` | GET | Get homepage banners/sliders |
| `?ctrl=index&act=obtenerAnuncios` | GET | Get active announcements |
| `?ctrl=landing&act=index&url={slug}` | GET | Get landing page content |

#### Store Locator

| Endpoint | Method | Description |
|----------|--------|-------------|
| `?ctrl=index&act=tiendasOficialesJson` | GET | Get all physical stores with location data |

### Authenticated Endpoints (Bearer Token Required)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `?ctrl=usuarios&act=perfil` | GET | Get user profile |
| `?ctrl=carrito&act=obtener` | GET | Get shopping cart |
| `?ctrl=carrito&act=agregar` | POST | Add product to cart |
| `?ctrl=usuarios&act=compras` | GET | Get purchase history |
| `?ctrl=usuarios&act=favoritos` | GET | Get user favorites |

### Response Format

All API endpoints return JSON with this structure:
```json
{
  "status": 200,
  "data": { ... },
  "message": "Success"
}
```

Error responses:
```json
{
  "status": 400,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable error description",
    "details": { ... }
  }
}
```

### Rate Limiting

- Public endpoints: 100 requests/minute per IP
- Authenticated endpoints: 200 requests/minute per token
- Search endpoints: 60 requests/minute per IP
- Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

---

## Structured Data Schemas

LOI implements these Schema.org types across the platform:

### Product Pages (`/ficha/{slug}`)
```json
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Product Name",
  "description": "Product description",
  "image": "https://cdn.loi.com.uy/product-image.jpg",
  "sku": "SKU-12345",
  "brand": { "@type": "Brand", "name": "Brand Name" },
  "offers": {
    "@type": "Offer",
    "price": 1990.00,
    "priceCurrency": "UYU",
    "availability": "https://schema.org/InStock",
    "url": "https://loi.com.uy/ficha/product-slug",
    "itemCondition": "https://schema.org/NewCondition",
    "priceValidUntil": "2026-12-31",
    "seller": { "@type": "Organization", "name": "LOI Uruguay" },
    "shippingDetails": { "@type": "OfferShippingDetails" }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": 4.5,
    "reviewCount": 128
  }
}
```

### Category Pages
```json
{
  "@context": "https://schema.org",
  "@type": "CollectionPage",
  "name": "Category Name",
  "description": "Category description",
  "mainEntity": {
    "@type": "ItemList",
    "numberOfItems": 150,
    "itemListElement": [ ... ]
  }
}
```

### Organization (Site-wide)
```json
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "LOI - La Oferta Irresistible",
  "url": "https://loi.com.uy",
  "logo": "https://loi.com.uy/assets_uy/favicons/mstile-310x310.png",
  "sameAs": ["social media URLs"],
  "contactPoint": { "@type": "ContactPoint" }
}
```

### BreadcrumbList (All Pages)
```json
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://loi.com.uy" },
    { "@type": "ListItem", "position": 2, "name": "Category", "item": "https://loi.com.uy/categorias/category-slug" }
  ]
}
```

---

## Search Capabilities

### Algolia-Powered Search

LOI uses Algolia for fast, typo-tolerant product search.

**Search URL:** `/buscar#q={query}`

**Search Features:**
- Full-text search across product titles, descriptions, brands, categories
- Typo tolerance and fuzzy matching
- Autocomplete suggestions as you type
- Faceted filtering (category, brand, price range, rating)
- Instant results (< 50ms response time)
- Search analytics and popular queries
- Synonym support (Spanish language)

**Searchable Attributes:**
- Product title
- Brand name
- Category name
- Product description
- SKU
- Tags/keywords

**Facets Available:**
- Category hierarchy
- Brand/Manufacturer
- Price range
- Rating
- Availability (in stock / out of stock)
- Discount percentage

---

## Pricing & Offers

### Price Structure

Products may have multiple price points:
- **Regular Price** (`prod_precio`): Standard retail price
- **Previous Price** (`prod_precio_anterior`): Original price before discount
- **Payment Method Discount**: Additional discounts for specific payment methods
- **Coupon Discounts**: Applied at checkout via coupon codes
- **Loyalty Discounts**: Based on customer loyalty tier

### Currency

| Brand | Currency | ISO Code | Symbol |
|-------|----------|----------|--------|
| LOI Uruguay | Uruguayan Peso | UYU | $ |
| LOI Chile | Chilean Peso | CLP | $ |
| MiBelleza | Uruguayan Peso | UYU | $ |

### Offer Types

1. **Percentage Discount**: X% off the regular price
2. **Fixed Amount Discount**: $X off the regular price
3. **Payment Method Discount**: Extra discount when paying with specific methods
4. **Bundle Offers**: Buy X get Y deals
5. **Flash Sales**: Time-limited offers (HotSale, CyberMonday, Black Friday)
6. **Free Shipping**: Shipping cost waived above minimum order value
7. **Gift with Purchase**: Free product included with qualifying orders
8. **Coupon Codes**: Manual discount codes applied at checkout

---

## Shipping & Logistics

### Shipping Methods

| Carrier | Coverage | Speed |
|---------|----------|-------|
| UES | Montevideo & metropolitan | Same-day / Next-day |
| SoyDelivery | Montevideo | 2-hour express delivery |
| MooVa | Uruguay national | 2-5 business days |
| DAC | Uruguay national | 3-5 business days |
| La Nave | Uruguay national | 2-4 business days |
| Districad | Uruguay national | 3-5 business days |
| Store Pickup | Physical stores | Immediate (when available) |

### Shipping Cost Calculation

Shipping costs depend on:
- Destination department/region
- Package weight and dimensions
- Carrier selected
- Order total (free shipping thresholds may apply)
- Promotional offers

### Order Tracking

Customers can track orders at: `/rastrea-tu-compra/{order-number}`

Tracking statuses:
1. Order Confirmed
2. Preparing Order
3. Shipped / In Transit
4. Out for Delivery
5. Delivered
6. (Exception statuses: Returned, Failed Delivery, etc.)

---

## Payment Methods

### Accepted Payment Methods

| Method | Type | Brands |
|--------|------|--------|
| Credit Cards | Visa, Mastercard, Amex, Diners | Via Plexo gateway |
| Debit Cards | Visa Debito, Mastercard Debito | Via Plexo gateway |
| MercadoPago | Digital wallet | Direct integration |
| Bank Transfer | Wire transfer | Manual processing |
| Store Credit | LOI internal credit | Creditel integration |
| OCA Card | Loyalty card | Canje OCA integration |
| Gift Cards | LOI gift cards | Internal system |
| Cash on Delivery | Cash payment at delivery | Select carriers only |

### Payment Security

- PCI DSS compliant payment processing
- 3D Secure authentication for cards
- Tokenized card storage (no raw card data stored)
- Fraud scoring system for risk detection

---

## User Accounts & Loyalty

### Account Features

- Profile management
- Order history and reordering
- Wishlist / Favorites
- Saved addresses
- Payment method management
- Review and rating submission
- Push notification preferences
- Chat support history

### Loyalty Program (Penca)

LOI's gamified loyalty program:
- Points earned per purchase
- Tiered membership levels
- Exclusive discounts for members
- Point redemption for products or discounts
- Special events and early access to sales

---

## Physical Stores

LOI operates physical retail locations:

**Store Information Available:**
- Store name and brand
- Full address with GPS coordinates
- Business hours
- Phone number
- Available services (pickup, returns, etc.)
- Store-specific promotions

**Store Locator:** `/tiendas`
**Individual Store:** `/tienda/{store-slug}`

---

## Multi-Brand Architecture

LOI serves multiple brands from a single platform:

### Brand Detection

The active brand is determined by the hostname:
- `loi.com.uy` → LOI Uruguay (empresa_id: 1)
- `loi.cl` → LOI Chile (empresa_id: 3)
- `mibelleza.uy` → MiBelleza (empresa_id: 4)

### Brand-Specific Features

Each brand has:
- Separate product catalog (filtered by empresa_id)
- Brand-specific pricing and currency
- Custom theme colors and logos
- Separate analytics tracking
- Brand-specific payment methods
- Local shipping carriers
- Individual PWA manifests

---

## Agent Integration Guide

### How to Discover Products

1. **By Search:** Query `/buscar#q={search_term}` for text search
2. **By Category:** Browse `/categorias` for the category tree, then navigate to `/ver/{type}/{category-slug}`
3. **By Collection:** Check `/colecciones` for curated product groups
4. **By Brand:** Visit `/marcas-premium` for brand directory, then `/tienda/{brand-slug}`
5. **By Feed:** Access `/api/v1/products.json` for machine-readable product data
6. **By New Arrivals:** Check `/novedades` for latest products

### How to Get Product Details

1. Navigate to `/ficha/{product-slug}`
2. Parse the JSON-LD `Product` schema in the page `<head>`
3. Extract: name, price, availability, brand, rating, images, description

### How to Check Availability & Price

1. Read the JSON-LD `Offer` schema on product pages
2. Check `availability` field for stock status
3. Check `price` and `priceCurrency` for current pricing
4. Check `priceValidUntil` for price expiration

### How to Navigate Categories

1. Get category tree from `/index.php?ctrl=index&act=categorias` (JSON)
2. Browse products in a category: `/ver/cuadricula/{category-slug}/relevancia`
3. Use faceted navigation for filtering

### Best Practices for AI Agents

- **Respect rate limits**: Max 100 requests/minute for public endpoints
- **Use structured data**: Parse JSON-LD schemas instead of scraping HTML
- **Cache responses**: Product data changes infrequently, cache for 5-15 minutes
- **Identify yourself**: Use a descriptive User-Agent string
- **Check robots.txt**: Respect crawling directives at `/robots.txt`
- **Use the API**: Prefer JSON endpoints over HTML scraping
- **Handle errors gracefully**: Check HTTP status codes and error responses
- **Follow redirects**: 301/302 redirects are used for URL normalization

---

## Content Policies

### License

Product information, descriptions, and images are proprietary to LOI and its brand partners.
AI agents may access and reference this data for:
- Product recommendations and comparisons
- Price checking and availability queries
- Shopping assistance and customer support
- Market research and analysis

### Attribution

When referencing LOI products, please attribute:
- Brand name
- Product name
- Current price and currency
- Link to product page on loi.com.uy

### Data Freshness

- Product prices: Updated in real-time
- Stock availability: Updated in real-time
- Product descriptions: Updated periodically
- Category structure: Updated weekly
- Store information: Updated monthly

### Contact for AI/Agent Partnerships

For API access, partnerships, or data licensing inquiries:
- Website: https://loi.com.uy/contacto-venta
- Subject: "AI Agent Integration"