{
  "openapi": "3.0.3",
  "info": {
    "title": "SwitchAI — Energy Tariff Comparison API",
    "description": "AI agent per confronto tariffe Luce e Gas nel mercato libero italiano. 5.600+ offerte ARERA da tutti i fornitori. WebMCP e MCP compatibile. Reindirizza al fornitore per l'attivazione.",
    "version": "2.2.0",
    "contact": { "email": "info@switchai.it", "url": "https://www.switchai.it" },
    "license": { "name": "Proprietary", "url": "https://www.switchai.it/privacy" }
  },
  "servers": [{ "url": "https://www.switchai.it/api", "description": "SwitchAI Production API" }],
  "tags": [
    { "name": "Tariffs", "description": "Offerte e confronto tariffe" },
    { "name": "Bills", "description": "Analisi bollette" },
    { "name": "Market", "description": "Dati di mercato (PUN/PSV)" },
    { "name": "System", "description": "Health, stats, auth" }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["System"],
        "summary": "Health check",
        "operationId": "healthCheck",
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }
          }
        }
      }
    },
    "/status": {
      "get": {
        "tags": ["System"],
        "summary": "Statistiche tariffe (conteggio offerte, fornitori)",
        "operationId": "getStatus",
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }
          }
        }
      }
    },
    "/tariffe/luce": {
      "get": {
        "tags": ["Tariffs"],
        "summary": "Lista completa offerte LUCE (3.196+)",
        "description": "Restituisce tutte le offerte di energia elettrica disponibili con prezzi, tipo contratto, quota fissa, spread, PUN e campi extra. Dati ARERA aggiornati ogni notte.",
        "operationId": "getLuceOffers",
        "responses": {
          "200": {
            "description": "Lista offerte LUCE",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferList" } } }
          }
        }
      }
    },
    "/tariffe/gas": {
      "get": {
        "tags": ["Tariffs"],
        "summary": "Lista completa offerte GAS (2.411+)",
        "description": "Restituisce tutte le offerte di gas naturale disponibili con prezzi, tipo contratto, quota fissa, spread, PSV e campi extra. Dati ARERA aggiornati ogni notte.",
        "operationId": "getGasOffers",
        "responses": {
          "200": {
            "description": "Lista offerte GAS",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferList" } } }
          }
        }
      }
    },
    "/fornitori": {
      "get": {
        "tags": ["Tariffs"],
        "summary": "Lista fornitori disponibili",
        "operationId": "getSuppliers",
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Supplier" } } } }
          }
        }
      }
    },
    "/analyze": {
      "post": {
        "tags": ["Tariffs"],
        "summary": "Endpoint unificato V2 — analizza bolletta e confronta tariffe in una chiamata",
        "description": "Sostituisce parse_energy_bill + calculate_energy_savings. Una chiamata restituisce profile, top3, why_better, cost_breakdown, bill_attualization, risk, e agent_summary. Sistema di onestà integrato: consiglia il cambio solo se c'è un vantaggio reale (>50€/anno e >5%).",
        "operationId": "analyzeEnergyBill",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Analisi completa con honesty system",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeResponse" } } }
          },
          "400": { "description": "Parametri mancanti" }
        }
      }
    },
    "/webmcp-endpoint": {
      "post": {
        "tags": ["Tariffs"],
        "deprecated": true,
        "summary": "DEPRECATO — usa /analyze. Confronta tariffe e calcola risparmio (legacy)",
        "description": "Endpoint legacy senza honesty system. Usare /analyze per il confronto completo con sistema di onestà, cost_breakdown e bill_attualization.",
        "operationId": "calculateEnergySavings",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavingsRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Top 3 offerte con risparmio e agent_summary",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavingsResponse" } } }
          },
          "400": { "description": "Parametri non validi" }
        }
      }
    },
    "/calculate-savings": {
      "post": {
        "tags": ["Tariffs"],
        "summary": "Calcola risparmio (versione web)",
        "operationId": "calculateSavingsWeb",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavingsRequest" } } }
        },
        "responses": {
          "200": { "description": "Risultati confronto" }
        }
      }
    },
    "/parse-bill-text": {
      "post": {
        "tags": ["Bills"],
        "summary": "Analizza testo bolletta italiana",
        "description": "Estrae dati strutturati da una bolletta: fornitore, POD/PDR, consumo annuo, spesa annua stimata, zona tariffaria. Usare come primo step prima di calculate_energy_savings.",
        "operationId": "parseEnergyBill",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillParseRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Dati bolletta estratti",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillData" } } }
          },
          "400": { "description": "Testo bolletta non valido" }
        }
      }
    },
    "/analyze-bill": {
      "post": {
        "tags": ["Bills"],
        "summary": "Upload PDF bolletta + calcolo risparmio",
        "operationId": "analyzeBill",
        "responses": {
          "200": { "description": "Dati bolletta + offerte migliori" }
        }
      }
    },
    "/market-indices": {
      "get": {
        "tags": ["Market"],
        "summary": "PUN e PSV correnti",
        "description": "Prezzo Unico Nazionale (energia elettrica) e Punto di Scambio Virtuale (gas) aggiornati. Cache 1 ora.",
        "operationId": "getMarketIndices",
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketIndices" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Health": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "ok" },
          "version": { "type": "string", "example": "2.0.0" },
          "server": { "type": "string", "example": "PHP 8.5.0" },
          "db_mode": { "type": "string", "example": "json_remote" }
        }
      },
      "Status": {
        "type": "object",
        "properties": {
          "luce_tariffs": { "type": "integer", "example": 3196 },
          "gas_tariffs": { "type": "integer", "example": 2411 },
          "suppliers": { "type": "integer", "example": 38 }
        }
      },
      "OfferList": {
        "type": "object",
        "properties": {
          "commodity": { "type": "string", "example": "LUCE" },
          "count": { "type": "integer", "example": 3196 },
          "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }
        }
      },
      "Offer": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "supplier_name": { "type": "string", "example": "Edison" },
          "name": { "type": "string", "example": "DINAMYC" },
          "type": { "type": "string", "enum": ["FISSO", "VARIABILE"] },
          "price_mono_kwh": { "type": "number", "nullable": true },
          "price_smc": { "type": "number", "nullable": true },
          "fixed_fee_monthly": { "type": "number" },
          "fixed_fee_annual": { "type": "number", "nullable": true },
          "spread": { "type": "number", "nullable": true },
          "pun": { "type": "number", "nullable": true, "description": "PUN di riferimento" },
          "psv": { "type": "number", "nullable": true, "description": "PSV di riferimento" },
          "promo_active": { "type": "boolean" },
          "brand": { "type": "string" },
          "logo": { "type": "string", "nullable": true },
          "extra": { "$ref": "#/components/schemas/OfferExtra" }
        }
      },
      "OfferExtra": {
        "type": "object",
        "properties": {
          "prezzo_bloccato_mesi": { "type": "string", "description": "Mesi di prezzo bloccato" },
          "modalita_pagamento": { "type": "string", "example": "SDD" },
          "vantaggi": { "type": "string" },
          "note": { "type": "string" },
          "validita_offerta": { "type": "string" },
          "costo_profili": { "type": "object", "description": "Costo per profilo basso/medio/alto" }
        }
      },
      "Supplier": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string", "example": "Edison" },
          "slug": { "type": "string", "example": "edison" },
          "logo": { "type": "string", "nullable": true }
        }
      },
      "SavingsRequest": {
        "type": "object",
        "required": ["commodity"],
        "properties": {
          "commodity": { "type": "string", "enum": ["LUCE", "GAS"], "description": "Tipo fornitura" },
          "yearly_consumption_kwh": { "type": "number", "description": "Consumo annuo kWh (LUCE). Tipico: 2500-3500" },
          "yearly_consumption_smc": { "type": "number", "description": "Consumo annuo Smc (GAS). Tipico: 700-1200" },
          "zone": { "type": "string", "enum": ["NORD", "CENTRO", "SUD"], "description": "Zona tariffaria" },
          "current_supplier": { "type": "string", "description": "Fornitore attuale" },
          "current_annual_spend": { "type": "number", "description": "Spesa annua attuale in €" }
        }
      },
      "AnalyzeRequest": {
        "type": "object",
        "description": "Accetta sia nomi italiani (consumo_annuo_kwh, spesa_annua_eur, zona) sia alias inglesi (yearly_consumption_kwh, current_annual_spend, zone). current_supplier è l'alias inglese di fornitore.",
        "properties": {
          "bill_text": { "type": "string", "description": "Testo della bolletta italiana" },
          "commodity": { "type": "string", "enum": ["LUCE", "GAS"] },
          "consumo_annuo_kwh": { "type": "number", "description": "Consumo annuo kWh (LUCE). Alias inglese: yearly_consumption_kwh" },
          "consumo_annuo_smc": { "type": "number", "description": "Consumo annuo Smc (GAS). Alias inglese: yearly_consumption_smc" },
          "spesa_annua_eur": { "type": "number", "description": "Spesa annua attuale in €. Alias inglese: current_annual_spend" },
          "zona": { "type": "string", "enum": ["NORD", "CENTRO", "SUD"], "description": "Zona tariffaria. Alias inglese: zone" },
          "fornitore": { "type": "string", "description": "Fornitore attuale. Alias inglese: current_supplier" },
          "tariff_type": { "type": "string", "enum": ["fisso", "variabile"] },
          "options": { "type": "object", "properties": { "response_format": { "type": "string", "enum": ["compact", "full"] } } }
        }
      },
      "AnalyzeResponse": {
        "type": "object",
        "properties": {
          "bill_token": { "type": "string", "description": "SHA256 fingerprint per caching" },
          "profile": { "$ref": "#/components/schemas/BillData" },
          "top3": { "type": "array", "items": { "$ref": "#/components/schemas/SavingsResult" } },
          "why_better": { "type": "object", "description": "Spiegazione strutturata del perché conviene cambiare" },
          "cost_breakdown": { "type": "object", "description": "Scomposizione costi in 4 componenti con chart_data per grafici" },
          "bill_attualization": { "type": "object", "description": "Ricalcolo spesa con PUN/PSV odierno per bollette variabili" },
          "risk": { "$ref": "#/components/schemas/MarketRisk" },
          "honesty": { "type": "object", "description": "Raccomandazione etica: switch/evaluate/stay con badge", "properties": { "recommendation": { "type": "string", "enum": ["switch", "evaluate", "stay"] }, "badge": { "type": "string" } } },
          "agent_summary": { "type": "string", "description": "Riepilogo in italiano pronto per l'utente" }
        }
      },
      "MarketRisk": {
        "type": "object",
        "properties": {
          "indice": { "type": "string", "enum": ["PUN", "PSV"] },
          "volatilita_pct": { "type": "number" },
          "level": { "type": "string", "enum": ["alta", "moderata", "bassa"] },
          "raccomandazione": { "type": "string", "enum": ["fisso", "variabile"] },
          "motivazione": { "type": "string" }
        }
      },
      "SavingsResponse": {
        "type": "object",
        "properties": {
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/SavingsResult" } },
          "comparison_id": { "type": "string" },
          "current_spend_estimated": { "type": "number" },
          "agent_summary": { "type": "string", "description": "Riepilogo in italiano per l'utente finale" }
        }
      },
      "SavingsResult": {
        "type": "object",
        "properties": {
          "tariff_id": { "type": "string" },
          "supplier": { "type": "string" },
          "tariff_name": { "type": "string" },
          "annual_cost_eur": { "type": "number" },
          "savings_eur": { "type": "number" },
          "savings_pct": { "type": "number" },
          "type": { "type": "string", "enum": ["FISSO", "VARIABILE"] },
          "activation_url": { "type": "string" },
          "breakdown": { "type": "object" }
        }
      },
      "BillParseRequest": {
        "type": "object",
        "required": ["bill_text"],
        "properties": {
          "bill_text": { "type": "string", "description": "Testo completo della bolletta italiana" }
        }
      },
      "BillData": {
        "type": "object",
        "properties": {
          "commodity": { "type": "string", "enum": ["LUCE", "GAS"] },
          "current_supplier": { "type": "string", "example": "Enel Energia" },
          "pod_pdr": { "type": "string", "example": "IT001E123456789" },
          "yearly_consumption_kwh": { "type": "number" },
          "yearly_consumption_smc": { "type": "number" },
          "current_annual_spend": { "type": "number" },
          "zone": { "type": "string", "enum": ["NORD", "CENTRO", "SUD"] }
        }
      },
      "MarketIndices": {
        "type": "object",
        "properties": {
          "pun": { "type": "number", "description": "PUN in €/kWh" },
          "psv": { "type": "number", "description": "PSV in €/Smc" },
          "pun_display": { "type": "string", "example": "125,0 €/MWh (0,1250 €/kWh)" },
          "psv_display": { "type": "string", "example": "0,5000 €/Smc" },
          "source": { "type": "string", "example": "GME" },
          "updated": { "type": "string", "format": "date-time" }
        }
      }

    }
  }
}