{"openapi":"3.1.0","info":{"title":"Solematica Public API","version":"1.0.0","description":"API pubblica di Solematica per stime fotovoltaiche (Google Solar API + PVGIS), confronto offerte luce/gas di operatori italiani, prezzi energia e contenuti del blog. Lead generation per efficienza energetica residenziale in Italia.","contact":{"name":"Solematica","email":"info@solematica.it","url":"https://www.solematica.it"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.solematica.it/api/v1","description":"Produzione"}],"externalDocs":{"description":"Documentazione sviluppatori","url":"https://www.solematica.it/sviluppatori"},"paths":{"/stima":{"post":{"operationId":"creaStima","summary":"Genera una stima del potenziale fotovoltaico per un indirizzo italiano","description":"Analizza il tetto via satellite (Google Solar API) e calcola potenza consigliata, produzione annua, risparmio, ROI con e senza detrazione 50%, dimensionamento accumulo. Richiede coordinate o indirizzo.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["indirizzo"],"properties":{"indirizzo":{"type":"string","description":"Indirizzo completo in Italia, es. 'Via Roma 1, 20100 Milano MI'"},"lat":{"type":"number","description":"Latitudine (alternativa al geocoding indirizzo)"},"lng":{"type":"number","description":"Longitudine"},"consumo_annuo_kwh":{"type":"number","default":3500,"description":"Consumo elettrico annuo in kWh"},"tipo_abitazione":{"type":"string","enum":["indipendente","bifamiliare","schiera","condominio"]},"superficie_tetto_mq":{"type":"number","description":"Superficie tetto in mq (calcolata da satellite se omessa)"},"orientamento":{"type":"string","description":"Orientamento tetto: nord, sud, est, ovest"},"interessi":{"type":"array","items":{"type":"string"},"description":"Addon: accumulo, pompa_calore, caldaia, vmc, colonnina_ricarica"}}}}}},"responses":{"200":{"description":"Stima generata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stima"}}}},"400":{"description":"Dati non validi"},"429":{"description":"Rate limit superato"}}}},"/stima/prezzi-energia":{"get":{"operationId":"getPrezziEnergia","summary":"Prezzi correnti energia elettrica in Italia (PUN, ARERA)","description":"Prezzi aggiornati mensilmente, usati per i calcoli di risparmio. Nessuna autenticazione.","responses":{"200":{"description":"Prezzi energia con data di aggiornamento"}}}},"/leads":{"post":{"operationId":"creaLead","summary":"Crea un lead (richiesta di contatto) per preventivo fotovoltaico","description":"Registra una richiesta utente con consensi GDPR. I dati personali sono crittografati AES-256-GCM. Innesca il dispatch verso installatori partner.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nome","cognome","email","telefono","consenso_privacy"],"properties":{"nome":{"type":"string"},"cognome":{"type":"string"},"email":{"type":"string","format":"email"},"telefono":{"type":"string"},"indirizzo":{"type":"string"},"citta":{"type":"string"},"provincia":{"type":"string"},"consenso_privacy":{"type":"boolean"},"consenso_partner":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Lead creato","content":{"application/json":{"schema":{"type":"object","properties":{"codice_tracking":{"type":"string"}}}}}}}}},"/tracking/{codice}":{"get":{"operationId":"getTracking","summary":"Stato di avanzamento di un lead tramite codice tracking","parameters":[{"name":"codice","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stato lead"},"404":{"description":"Codice non trovato"}}}},"/providers":{"get":{"operationId":"listProviders","summary":"Confronto offerte fotovoltaico operatori italiani","description":"Lista degli operatori (Enel, Iren, Plenitude, Otovo, E.ON, Hera, A2A, Edison, Engie, Sorgenia, Bluenergy) con prezzi, componenti, garanzie, indice di trasparenza. Nessuna autenticazione.","responses":{"200":{"description":"Lista provider"}}}},"/blog":{"get":{"operationId":"listArticoli","summary":"Articoli pubblicati del blog Solematica","parameters":[{"name":"categoria","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":200}}],"responses":{"200":{"description":"Lista articoli paginata"}}}},"/blog/{slug}":{"get":{"operationId":"getArticolo","summary":"Singolo articolo del blog per slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Articolo"},"404":{"description":"Non trovato"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key partner (richiesta solo per /stima). Emessa dall admin Solematica."}},"schemas":{"Stima":{"type":"object","properties":{"kwp_consigliato":{"type":"number","description":"Potenza consigliata in kWp"},"produzione_annua_kwh":{"type":"number"},"risparmio_annuo_euro":{"type":"number"},"costo_totale_euro":{"type":"number"},"roi_anni":{"type":"number","description":"Payback lordo in anni"},"accumulo_consigliato":{"type":"boolean"},"accumulo_kwh":{"type":"number"}}}}}}