{
  "openapi": "3.1.0",
  "info": {
    "title": "Magic Lupa Price Search API",
    "version": "1.0.0",
    "description": "Returns a single verified lowest-price result per product query. Combines real-time store comparison, coupon validation, cashback platforms and shipping/tax calculation across Argentina, Spain and the United States, expanding.",
    "contact": {
      "name": "Magic Lupa",
      "url": "https://magiclupa.com/api-business",
      "email": "hola@magiclupa.com"
    },
    "license": {
      "name": "Commercial — request API key at hola@magiclupa.com"
    }
  },
  "servers": [
    {
      "url": "https://magiclupa.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/search": {
      "post": {
        "summary": "Find lowest verified price",
        "description": "Submit a product query plus country/mode and receive one recommended store with verified total price, descontable coupons, applicable cashback, and exact purchase steps.",
        "operationId": "findLowestPrice",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "example": {
                "query": "Samsung Galaxy S26 Ultra 256GB",
                "country": "es",
                "mode": "consumer",
                "quantity": 1,
                "city": "Madrid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful lookup",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Engine overloaded (try again later)"
          }
        }
      },
      "get": {
        "summary": "Endpoint info and version",
        "responses": {
          "200": {
            "description": "Endpoint metadata"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "ml_live_..."
      }
    },
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "required": [
          "query",
          "country"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Product name (any language)"
          },
          "country": {
            "type": "string",
            "description": "ISO-3166-1 alpha-2 country code (es, ar, mx, us, ...)",
            "example": "es"
          },
          "customCountry": {
            "type": "string",
            "description": "Free-form country name when country is 'other'"
          },
          "subregion": {
            "type": "string",
            "description": "Sub-region id the buyer is in: a Spanish province (madrid, barcelona, las_palmas, …) or a US state code (ca, ny, tx, …). The fiscal treatment (IVA/IGIC/IPSI or sales tax) is derived from it server-side. `province`/`region` are accepted as legacy aliases."
          },
          "mode": {
            "type": "string",
            "enum": [
              "consumer",
              "business"
            ],
            "default": "consumer"
          },
          "quantity": {
            "type": "integer",
            "default": 1,
            "minimum": 1,
            "maximum": 10000
          },
          "city": {
            "type": "string",
            "description": "User city for hyper-local store recommendations"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "producto": {
            "type": "string"
          },
          "imagen_url": {
            "type": "string",
            "nullable": true
          },
          "tienda_recomendada": {
            "type": "string"
          },
          "tienda_verificada": {
            "type": "boolean"
          },
          "confianza": {
            "type": "string",
            "enum": [
              "alta",
              "media",
              "baja"
            ]
          },
          "precio_pvp": {
            "type": "number",
            "description": "Strikethrough/list price. Derived server-side from page extraction or Google baseline."
          },
          "precio_producto": {
            "type": "number",
            "description": "Derived = precio_final − precio_envio."
          },
          "precio_envio": {
            "type": "number"
          },
          "precio_envio_nota": {
            "type": "string",
            "enum": [
              "gratis",
              "condicional",
              "pagado",
              "desconocido"
            ]
          },
          "precio_final": {
            "type": "number",
            "description": "What the user pays at checkout, in this currency."
          },
          "precio_sin_iva": {
            "type": "number",
            "nullable": true
          },
          "ahorro": {
            "type": "number",
            "description": "Derived = max(0, precio_pvp − precio_final)."
          },
          "ahorro_porcentaje": {
            "type": "number"
          },
          "region": {
            "type": "string",
            "nullable": true,
            "description": "Sub-region id the result was computed for (province/state), forced server-side."
          },
          "region_nombre": {
            "type": "string",
            "nullable": true,
            "description": "Display name of the sub-region (e.g. Madrid, California)."
          },
          "aviso_region": {
            "type": "string",
            "nullable": true,
            "description": "Deterministic fiscal/shipping notice for the sub-region (IGIC/IPSI/Baleares surcharge, US sales tax). null when none."
          },
          "precio_estimado_region": {
            "type": "number",
            "nullable": true,
            "description": "Estimated price for the sub-region (ES Canarias: ex-VAT + IGIC; US: + state sales tax). Always an estimate, never replaces precio_final. null when not applicable."
          },
          "divisa": {
            "type": "string",
            "description": "ISO 4217"
          },
          "url_directa": {
            "type": "string",
            "format": "uri"
          },
          "tiempo_entrega": {
            "type": "string",
            "enum": [
              "rapido",
              "normal",
              "lento",
              "desconocido"
            ]
          },
          "descuentos_aplicados": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Discount"
            }
          },
          "pasos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Step"
            }
          },
          "meta_oferta": {
            "type": "object",
            "nullable": true,
            "description": "Structured offer metadata. Only set when verified.",
            "properties": {
              "caduca": {
                "type": "string",
                "format": "date",
                "description": "ISO date YYYY-MM-DD, always ≥ today."
              },
              "stock_bajo": {
                "type": "boolean"
              }
            }
          },
          "alternativa_segunda_mano": {
            "type": "object",
            "nullable": true,
            "properties": {
              "disponible": {
                "type": "boolean"
              },
              "precio_estimado": {
                "type": "number"
              },
              "fuente": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "_meta": {
            "type": "object",
            "properties": {
              "cached": {
                "type": "boolean"
              },
              "cachedAt": {
                "type": "integer",
                "description": "Unix ms timestamp of cache write"
              },
              "tier": {
                "type": "string"
              }
            }
          }
        }
      },
      "Discount": {
        "type": "object",
        "properties": {
          "tipo": {
            "type": "string",
            "description": "cupón | cashback | promo | etc"
          },
          "descripcion": {
            "type": "string"
          },
          "importe": {
            "type": "number"
          }
        }
      },
      "Step": {
        "type": "object",
        "properties": {
          "numero": {
            "type": "integer"
          },
          "accion": {
            "type": "string"
          },
          "link": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "codigo": {
            "type": "string",
            "nullable": true
          }
        }
      }
    }
  }
}