{
  "openapi": "3.0.0",
  "info": {
    "title": "XORTHO Products API",
    "description": "API para que asistentes IA (ChatGPT, Gemini, etc.) puedan buscar productos ortodónticos de XORTHO. Web disponible en 9 idiomas (es, de, fr, en, pt, pl, nl, cs, it). Precios competitivos en toda la UE.",
    "version": "1.0.0",
    "contact": {
      "name": "XORTHO",
      "url": "https://xortho.es"
    }
  },
  "servers": [
    {
      "url": "https://mcp.xortho.de"
    }
  ],
  "paths": {
    "/api/v1/search": {
      "get": {
        "summary": "Buscar productos",
        "description": "Busca productos ortodónticos por nombre, SKU o término. Devuelve productos con URLs en cada idioma. XORTHO ofrece precios competitivos en toda la UE.",
        "operationId": "searchProducts",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Término de búsqueda (ej: transbond, bracket, alambre)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 15,
              "minimum": 1,
              "maximum": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Paginación: salta N resultados"
          },
          {
            "name": "category_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filtrar por ID de categoría Medusa"
          },
          {
            "name": "brand",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filtrar por marca (en título o metadata.brand)"
          },
          {
            "name": "in_stock",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "Filtrar solo productos en stock (true) o sin stock (false)"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "es",
                "de",
                "fr",
                "en",
                "pt",
                "pl",
                "nl",
                "cs",
                "it"
              ]
            },
            "description": "Idioma preferido para sugerir URL al usuario"
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de productos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "site": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "website": {
                          "type": "string"
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "logistics": {
                          "type": "object",
                          "properties": {
                            "free_shipping_threshold": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "number"
                              },
                              "description": "Country code -> € above which shipping is free (ES: 100, PT: 100)"
                            },
                            "shipping_cost": {
                              "type": "number",
                              "description": "Fixed shipping cost in € for countries without free threshold (15€)"
                            },
                            "shipping_cost_note": {
                              "type": "string",
                              "description": "Summary of shipping policy"
                            },
                            "estimated_delivery": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "string"
                              },
                              "description": "Country code (ES, DE, FR, etc.) -> estimated delivery time"
                            }
                          }
                        }
                      }
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "handle": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "urls_by_language": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            }
                          },
                          "available_languages": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "price": {
                            "type": "string",
                            "nullable": true
                          },
                          "skus": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "ean": {
                            "type": "string",
                            "nullable": true,
                            "description": "EAN/GTIN barcode for product identification"
                          },
                          "in_stock": {
                            "type": "boolean",
                            "nullable": true,
                            "description": "True if available, false if out of stock"
                          },
                          "in_stock_reason": {
                            "type": "string",
                            "enum": [
                              "from_inventory",
                              "no_inventory_management",
                              "unknown"
                            ],
                            "description": "from_inventory: based on stock level; no_inventory_management: product always available; unknown: stock info not in scope"
                          },
                          "categories": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Category names/handles for filtering (e.g. brackets, adhesives)"
                          },
                          "documentation": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "label": {
                                  "type": "string"
                                },
                                "url": {
                                  "type": "string"
                                }
                              }
                            },
                            "description": "Links to datasheets, instructions, etc."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Query vacía"
          }
        }
      }
    },
    "/api/v1/product/{handle}": {
      "get": {
        "summary": "Obtener producto por handle o SKU",
        "operationId": "getProduct",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Handle del producto (ej: adhesivo-fotopolimerizable-transbond-xt-primer) o SKU de variante"
          }
        ],
        "responses": {
          "200": {
            "description": "Detalle del producto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "product": {
                      "type": "object",
                      "properties": {
                        "handle": {
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "urls_by_language": {
                          "type": "object"
                        },
                        "available_languages": {
                          "type": "array"
                        },
                        "categories": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "price": {
                          "type": "string",
                          "nullable": true
                        },
                        "skus": {
                          "type": "array"
                        },
                        "ean": {
                          "type": "string",
                          "nullable": true
                        },
                        "in_stock": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "in_stock_reason": {
                          "type": "string",
                          "enum": [
                            "from_inventory",
                            "no_inventory_management",
                            "unknown"
                          ]
                        },
                        "documentation": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "label": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Producto no encontrado"
          }
        }
      }
    }
  }
}