Developer Docs

API & MCP per Sviluppatori

Integra le stime solari di Solematica nelle tue applicazioni. REST API tradizionale o Model Context Protocol per agenti AI.

Due modalità di accesso

Scegli il percorso più adatto al tuo caso d'uso.

Gratuito

Lead-based

Fornisci dati di contatto reali dell'utente (nome, email, telefono). In cambio, generiamo una stima solare completa e inviamo il lead ai partner installatori. Nessun costo per te né per l'utente.

Nessun costo
Stima completa inclusa
Richiede consenso GDPR

Crediti prepagati

API Key

Registrati come partner, acquista crediti e genera la tua API key. Usa l'API senza fornire dati di contatto dell'utente. Ogni stima scala crediti dal tuo saldo.

Nessun lead richiesto
Rate limit personalizzabile
Gestione chiavi dall'area partner

REST API

Tutti gli endpoint sono sotto il prefisso https://api.solematica.it/api/v1.

Autenticazione

Includi la tua API key nell'header Authorization:

Header

Authorization: Bearer <LA_TUA_API_KEY>

POST/stima

Genera una stima solare completa per un indirizzo in Italia. Richiede API key con crediti.

Request

POST /api/v1/stima

{
  "indirizzo": "Via Roma 1, 20100 Milano MI",
  "consumo_annuo_kwh": 4000,
  "tipo_abitazione": "indipendente",
  "superficie_tetto_mq": 60,
  "orientamento": "sud",
  "nucleo_familiare": 4,
  "interessi": ["fotovoltaico", "accumulo"]
}

Response

200 OK

{
  "fonte_dati": "google_solar",
  "kwp_consigliato": 4.0,
  "n_moduli": 10,
  "produzione_annua_kwh": 5200,
  "produzione_mensile": [286, 338, 442, ...],
  "autoconsumo_percentuale": 60,
  "risparmio_annuo_euro": 1120,
  "roi_anni": 5.4,
  "co2_evitata_kg": 1212,
  "costo_stimato_euro": 6000,
  "costo_totale_euro": 8500,
  "superficie_utilizzabile_mq": 17.0,
  "irradianza_annua": 1300,
  "orientamento_ottimale": "sud"
}

GET/stima/solar-info

Restituisce i dati satellitari del tetto: superficie, orientamento, segmenti, pannelli potenziali. Richiede parametri lat e lng.

GET /api/v1/stima/solar-info?lat=45.464&lng=9.190

{
  "available": true,
  "superficie_tetto_mq": 85.3,
  "superficie_utilizzabile_mq": 42.0,
  "orientamento": "Sud",
  "orientamento_gradi": 180,
  "maxPanels": 24,
  "maxSunshineHours": 1450,
  "roofSegments": [...]
}

POST/leads

Crea un lead qualificato (percorso gratuito). L'utente riceve una stima solare e viene contattato da installatori partner. Richiede consenso GDPR.

POST /api/v1/leads

{
  "nome": "Mario",
  "cognome": "Rossi",
  "email": "mario@example.com",
  "telefono": "+39 333 1234567",
  "indirizzo": "Via Roma 1, 20100 Milano MI",
  "citta": "Milano",
  "provincia": "MI",
  "consumo_annuo_kwh": 4000,
  "consenso_cessione": true
}

GET/tracking/:codice

Controlla lo stato di una pratica tramite il codice di tracking restituito alla creazione del lead.

GET /api/v1/tracking/ABC123XYZ456

{
  "codice": "ABC123XYZ456",
  "stato": "in_lavorazione",
  "stima": { "kwp": 4.0, "risparmio_annuo": 1120 },
  "pratiche": [
    { "partner": "Iren", "stato": "contattato" }
  ]
}

GET/blog

Lista articoli del blog. Supporta filtri per categoria e paginazione.

GET /api/v1/blog?categoria=incentivi&page=1

{
  "articoli": [
    {
      "slug": "incentivi-fotovoltaico-2026",
      "titolo": "Incentivi Fotovoltaico 2026: Guida Completa",
      "categoria": "incentivi",
      "pubblicato_at": "2026-03-10"
    }
  ],
  "total": 42,
  "page": 1,
  "totalPages": 5
}

NUOVOGratuito — nessuna API key richiesta

GET/providers

Restituisce il confronto aggiornato delle offerte fotovoltaico dei principali operatori italiani. Include prezzi, brand componenti, garanzie, finanziamento e indice di trasparenza. Nessuna autenticazione richiesta.

GET /api/v1/providers

{
  "providers": [
    {
      "slug": "iren",
      "nome": "Iren",
      "prezzo_3kw": "da 4.990 €",
      "pannelli": "Trinasolar / AIKO",
      "inverter": "ZCS Azzurro (Zucchetti)",
      "batteria": "ZCS Azzurro 5/10 kWh",
      "garanzia": "25 anni pannelli",
      "finanziamento": "Noleggio operativo disponibile",
      "servizi": ["Progettazione", "Installazione", "Pratica ENEA"],
      "taglie": "2.8 kWp base, personalizzabile",
      "trasparenza": 3,
      "telefono": "800 969 696",
      "sede": "Reggio Emilia",
      "ultimo_check": "2026-03-22"
    },
    { "slug": "enel", "nome": "Enel", ... },
    { "slug": "plenitude", "nome": "Plenitude (Eni)", ... },
    ...
  ]
}

Condizioni d'uso (attribuzione obbligatoria)

Questo endpoint è gratuito e pubblico. In cambio chiediamo un'unica cosa: se usi i dati nel tuo sito, app o servizio, devi includere un link visibile a Solematica nella pagina che mostra i dati:

Attribuzione richiesta

<p>Dati offerte fotovoltaico forniti da
  <a href="https://www.solematica.it/confronto-offerte">
    Solematica — Confronto Offerte Fotovoltaico
  </a>
</p>

Il link deve essere visibile all'utente (no display:none, no nofollow)
Puoi cachare i dati fino a 24 ore, ma non oltre
Non puoi modificare i dati in modo fuorviante
I dati vengono aggiornati ogni 2 settimane dal nostro team

Campi disponibili per ogni provider

Campo	Tipo	Descrizione
slug	string	Identificativo univoco
nome	string	Nome commerciale
prezzo_3kw	string	Prezzo di partenza per 3 kWp
pannelli	string	Brand e modello pannelli
inverter	string	Brand e modello inverter
batteria	string	Opzioni accumulo
garanzia	string	Durata e copertura
finanziamento	string	Opzioni di finanziamento
servizi	string[]	Servizi inclusi nel pacchetto
trasparenza	1-3	Indice di trasparenza (1=bassa, 3=alta)
telefono	string	Numero verde
sede	string	Sede principale
descrizione	string	Descrizione dell'operatore
ultimo_check	date	Data ultimo aggiornamento dati

Rate Limiting

Tipo	Limite	Note
Globale	100 req / 15 min	Per IP
API Key	Configurabile	Default 1000/giorno, reset a mezzanotte
Lead creation	10 req / 15 min	Per IP, anti-abuse

Codici di Errore

Codice	Significato
400	Parametri mancanti o non validi
401	API key mancante o non valida
403	API key disattivata o scaduta
404	Risorsa non trovata
429	Rate limit superato
500	Errore interno del server

MCP Server

npm GitHub

Il Model Context Protocol (MCP) permette agli assistenti AI come Claude di interagire direttamente con i tool di Solematica. Il pacchetto @solematica/mcp-server è pubblicato su npm e pronto all'uso.

Installazione

Nessuna installazione necessaria — npx lo scarica e avvia automaticamente:

Terminal

npx @solematica/mcp-server

Configurazione per Claude Desktop

Aggiungi al file di configurazione di Claude Desktop:

claude_desktop_config.json

{
  "mcpServers": {
    "solematica": {
      "command": "npx",
      "args": ["@solematica/mcp-server"],
      "env": {
        "SOLEMATICA_API_KEY": "la-tua-api-key"
      }
    }
  }
}

L'API key è opzionale — serve solo per stima_solare. Gli altri 5 tool funzionano senza autenticazione.

Configurazione per Claude Code

Terminal

claude mcp add solematica npx @solematica/mcp-server

6 Tool disponibili

stima_solareAPI key

Genera una stima completa del potenziale fotovoltaico per un indirizzo in Italia. Analizza il tetto via satellite, calcola produzione, risparmio, ROI e dimensionamento ottimale.

Parametri: indirizzo (obbligatorio), consumo_annuo_kwh?, tipo_abitazione?, superficie_tetto_mq?, orientamento?

info_tettoGratuito

Analizza un tetto tramite dati satellitari Google Solar API. Restituisce superficie, orientamento, segmenti del tetto e potenziale per pannelli solari.

Parametri: lat (obbligatorio), lng (obbligatorio)

confronta_providerGratuito

Restituisce il confronto aggiornato delle offerte fotovoltaico di 11 operatori italiani con prezzi, brand componenti, garanzie, trasparenza e servizi accessori.

Parametri: nessuno

dettaglio_providerGratuito

Scheda completa di un operatore: descrizione, contatti, componenti, finanziamento, servizi accessori (pompa di calore, wallbox, caldaia).

Parametri: slug (obbligatorio) — es. iren, enel, plenitude, otovo, eon, hera, a2a, edison, engie, sorgenia, bluenergy

prezzi_energiaGratuito

Prezzi correnti dell'energia elettrica in Italia (PUN/ARERA): autoconsumo, SSP, costo kWp, batteria. Aggiornati mensilmente.

Parametri: nessuno

cerca_articoliGratuito

Cerca articoli nel blog di Solematica su fotovoltaico, incentivi, risparmio ed efficientamento energetico.

Parametri: categoria?, limit?

Esempi d'uso con Claude

Con il server MCP configurato, puoi chiedere a Claude:

"Quanto produrrebbe un impianto fotovoltaico in Via Garibaldi 15, Torino?"

→ usa stima_solare

"Confronta le offerte fotovoltaico di Enel e Iren"

→ usa confronta_provider + dettaglio_provider

"Quali provider offrono anche la pompa di calore?"

→ usa confronta_provider e filtra per servizi accessori

"Qual è il prezzo corrente dell'energia in Italia?"

→ usa prezzi_energia

Come ottenere le API key

In 4 semplici passaggi puoi iniziare a integrare le stime solari.

Registrati come partner

Vai su /partner/registrazione e compila il modulo con i dati della tua azienda.

Attendi l'approvazione

Il team Solematica verifica i dati e approva il profilo entro 24-48 ore.

Acquista crediti

Dall'area partner, scegli il pacchetto crediti adatto alle tue esigenze.

Genera la API key

Nella sezione API dell'area partner, genera e gestisci le tue chiavi.

Registrati come Partner

Pricing

Pacchetti crediti prepagati. Più crediti acquisti, meno paghi per stima.

Starter

25 €

50 crediti

0.50 EUR/credito

Popolare

Business

80 €

200 crediti

0.40 EUR/credito

Professional

300 €

1000 crediti

0.30 EUR/credito

Enterprise

Su misura

Illimitati

Costi per azione

Azione	Costo	Descrizione
Stima solare	5.00 crediti	Stima completa con Google Solar API + PVGIS
Info tetto	2.00 crediti	Solo dati satellitari del tetto
Lead qualificato	Gratuito	Percorso lead-based, nessun credito richiesto
Blog / Articoli	Gratuito	Accesso libero senza autenticazione

Supporto

Hai domande sull'integrazione? Il nostro team tecnico è a disposizione.

api@solematica.it