{
  "openapi": "3.1.0",
  "info": {
    "title": "Sir William Stock API",
    "version": "1.0.0",
    "description": "API REST sicura - Fase 1. Le letture usano SIR_WILLIAM_API_KEY; le importazioni usano SIR_WILLIAM_IMPORT_API_KEY."
  },
  "servers": [{ "url": "https://sir-william-stock.pages.dev" }],
  "components": {
    "securitySchemes": {
      "inventoryKey": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" },
      "importKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Import API key" }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": { "const": false },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }
          }
        }
      },
      "Invoice": {
        "type": "object",
        "required": ["supplier", "document", "items"],
        "properties": {
          "supplier": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" } } },
          "document": {
            "type": "object",
            "required": ["number", "date"],
            "properties": {
              "type": { "type": "string", "examples": ["invoice", "ddt"] },
              "number": { "type": "string" },
              "date": { "type": "string", "format": "date" },
              "taxable": { "type": "number" },
              "vat": { "type": "number" },
              "total": { "type": "number" }
            }
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": ["description", "quantity"],
              "properties": {
                "code": { "type": "string" }, "description": { "type": "string" },
                "quantity": { "type": "number", "exclusiveMinimum": 0 }, "unit": { "type": "string" },
                "unit_price": { "type": "number", "minimum": 0 }, "line_total": { "type": "number", "minimum": 0 },
                "vat": { "type": "number", "minimum": 0 }, "warehouse": { "type": "string" }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/health": {
      "get": {
        "summary": "Controllo pubblico del servizio",
        "responses": { "200": { "description": "Servizio attivo" } }
      }
    },
    "/api/v1/inventory": {
      "get": {
        "summary": "Inventario completo paginato",
        "security": [{ "inventoryKey": [] }],
        "parameters": [
          { "name": "warehouse", "in": "query", "schema": { "type": "string" } },
          { "name": "search", "in": "query", "schema": { "type": "string" } },
          { "name": "low_stock", "in": "query", "schema": { "type": "boolean" } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }
        ],
        "responses": { "200": { "description": "Elenco prodotti" }, "401": { "description": "API key non valida" } }
      }
    },
    "/api/v1/kegs": {
      "get": { "summary": "Situazione fusti", "security": [{ "inventoryKey": [] }], "responses": { "200": { "description": "Elenco fusti" } } }
    },
    "/api/v1/kegs/low-stock": {
      "get": { "summary": "Fusti sotto scorta", "security": [{ "inventoryKey": [] }], "responses": { "200": { "description": "Fusti da ordinare" } } }
    },
    "/api/v1/assistant/summary": {
      "get": { "summary": "Riepilogo sintetico del magazzino", "security": [{ "inventoryKey": [] }], "responses": { "200": { "description": "Riepilogo" } } }
    },
    "/api/v1/import/invoice/preview": {
      "post": {
        "summary": "Valida una fattura/DDT senza modificare il magazzino",
        "security": [{ "importKey": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } },
        "responses": { "200": { "description": "Anteprima" }, "409": { "description": "Documento già importato" }, "422": { "description": "Dati da controllare" } }
      }
    },
    "/api/v1/import/invoice/confirm": {
      "post": {
        "summary": "Conferma un'anteprima valida e carica il magazzino",
        "security": [{ "importKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["preview_id"],
                "properties": { "preview_id": { "type": "string", "format": "uuid" } }
              }
            }
          }
        },
        "responses": { "201": { "description": "Importazione completata" }, "404": { "description": "Anteprima scaduta" }, "409": { "description": "Documento duplicato o anteprima non più attuale" }, "422": { "description": "Prodotti da controllare" } }
      }
    }
  }
}