{
  "openapi": "3.1.0",
  "info": {
    "title": "CHRONOS Skin Colombia — Agentic & E-Commerce API",
    "version": "1.0.0",
    "description": "API canónica machine-readable para agentes de Inteligencia Artificial (ChatGPT, Perplexity, Claude, Gemini, WebMCP en Chrome 149+) y desarrolladores. Provee acceso al catálogo de cosmética biotecnológica, herramientas WebMCP, estado de inventario e integración de pedidos en Colombia.",
    "contact": {
      "name": "Soporte Técnico & IA — Calíope S.A.S.",
      "email": "soporte@caliope.shop",
      "url": "https://store.caliope.shop/developers"
    },
    "license": {
      "name": "Proprietary / Calíope S.A.S.",
      "url": "https://store.caliope.shop/terms"
    }
  },
  "servers": [
    {
      "url": "https://store.caliope.shop",
      "description": "Servidor Canónico de Producción"
    },
    {
      "url": "https://www.store.caliope.shop",
      "description": "Servidor Alternativo de Producción"
    },
    {
      "url": "http://localhost:3007",
      "description": "Servidor de Desarrollo Local"
    }
  ],
  "paths": {
    "/api/catalog.json": {
      "get": {
        "summary": "Obtener catálogo completo de productos y kits",
        "description": "Devuelve la lista completa de productos individuales con sus activos biológicos, concentración, pH, precios en Pesos Colombianos (COP), registros INVIMA y PubChem CIDs.",
        "operationId": "getCatalog",
        "responses": {
          "200": {
            "description": "Catálogo de productos y kits retornado exitosamente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webmcp/manifest": {
      "get": {
        "summary": "Obtener manifiesto de herramientas WebMCP (Chrome 149+)",
        "description": "Devuelve la especificación de herramientas expuestas en el contexto del navegador para agentes autónomos que navegan mediante document.modelContext.",
        "operationId": "getWebMCPManifest",
        "responses": {
          "200": {
            "description": "Manifiesto WebMCP retornado exitosamente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebMCPManifest"
                }
              }
            }
          }
        }
      }
    },
    "/agent-instructions.md": {
      "get": {
        "summary": "Instrucciones operacionales y directivas When-to-Use para agentes",
        "description": "Documento en Markdown con casos de uso clínicos recomendados, directivas de prescripción, códigos de activo biológico y reglas de invocación.",
        "operationId": "getAgentInstructions",
        "responses": {
          "200": {
            "description": "Instrucciones en formato Markdown puro.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "Manifiesto canónico de contexto para modelos de lenguaje (llms.txt v2.0)",
        "description": "Estructura estándar para indexación por motores de IA generativa (ChatGPT Search, Perplexity, Claude, Gemini).",
        "operationId": "getLlmsManifest",
        "responses": {
          "200": {
            "description": "Manifiesto llms.txt en texto plano.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "Especificación OpenAPI 3.1.0 de la tienda",
        "description": "Devuelve este documento de especificación técnica de la API para auto-descubrimiento por agentes de IA.",
        "operationId": "getOpenAPISpec",
        "responses": {
          "200": {
            "description": "Especificación OpenAPI en formato JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "chronos-c-shield" },
          "sku": { "type": "string", "example": "CH-VITC-01" },
          "name": { "type": "string", "example": "CHRONOS-C Shield™ (Vitamina C 15% Bio-estabilizada)" },
          "priceCop": { "type": "number", "example": 110000 },
          "invima": { "type": "string", "example": "NSOC24819-26CO" },
          "pubchemCid": { "type": "integer", "nullable": true, "example": 54670067 },
          "url": { "type": "string", "example": "https://store.caliope.shop/sueros-vitamina-c" },
          "image": { "type": "string", "example": "https://store.caliope.shop/images/chronos-c-shield-punto-cero.webp" },
          "availability": { "type": "string", "example": "InStock" }
        },
        "required": ["id", "sku", "name", "priceCop", "invima", "availability"]
      },
      "Kit": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "kit-defense-protocol" },
          "sku": { "type": "string", "example": "KIT-DEF-01" },
          "name": { "type": "string", "example": "Kit Defense Protocol™ (Día)" },
          "priceCop": { "type": "number", "example": 187000 }
        },
        "required": ["id", "sku", "name", "priceCop"]
      },
      "CatalogResponse": {
        "type": "object",
        "properties": {
          "brand": { "type": "string", "example": "CHRONOS Skin Colombia" },
          "legalEntity": { "type": "string", "example": "Calíope S.A.S." },
          "taxID": { "type": "string", "example": "1.113.618.443-4" },
          "currency": { "type": "string", "example": "COP" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "products": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Product" }
          },
          "kits": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Kit" }
          }
        },
        "required": ["brand", "legalEntity", "currency", "products", "kits"]
      },
      "WebMCPManifest": {
        "type": "object",
        "properties": {
          "version": { "type": "string", "example": "1.0.0" },
          "capabilities": {
            "type": "array",
            "items": { "type": "string" }
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "description": { "type": "string" },
                "parameters": { "type": "object" }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "error" },
          "code": { "type": "string", "example": "RESOURCE_NOT_FOUND" },
          "message": { "type": "string", "example": "The requested endpoint or resource does not exist." },
          "resolution_hints": {
            "type": "array",
            "items": { "type": "string" },
            "example": [
              "Consult the OpenAPI specification at /openapi.json",
              "Inspect available endpoints in /llms.txt or /agent-instructions.md"
            ]
          },
          "documentation_url": { "type": "string", "example": "https://store.caliope.shop/developers" },
          "timestamp": { "type": "string", "format": "date-time" }
        },
        "required": ["status", "code", "message", "resolution_hints", "timestamp"]
      }
    }
  }
}