--- title: "SolaX Inverter (Cloud API)" description: "Inverter SolaX (X1, X3, A1, J1) in TapHome tramite SolaX Cloud API su HTTPS: produzione FV, batteria e rete. Serve dongle WiFi/LAN/4G e token API." url: "https://taphome.com/it/compatibility/solax-inverter/" language: it lastmod: 2026-10-08 generator: hugo ai: topics: ["http","inverter","cloud-api","solar","battery-storage","energy-monitoring"] questions: ["Come integrare un inverter SolaX con TapHome tramite la Cloud API?","Quali dati fornisce il template SolaX Cloud API in TapHome?","Come ottenere il tokenID dell'API SolaX per TapHome?","Qual è la differenza tra il template SolaX Cloud API e Modbus in TapHome?","Il template SolaX Cloud API funziona con tutti i modelli di inverter SolaX?","Quali sono i limiti API per l'integrazione SolaX Cloud?"] --- # SolaX Inverter (Cloud API) Comunicazione: Packet Parser → HTTP - [Sito ufficiale SolaX Power](https://www.solaxpower.com) ## Guida all'integrazione Il template SolaX Cloud API collega TapHome a qualsiasi inverter SolaX attraverso la piattaforma di monitoraggio SolaxCloud. A differenza del template [SolaX Hybrid X1/X3 Gen 4](https://taphome.com/it/compatibility/solax-hybrid-x3-gen-4/), che utilizza Modbus RTU su RS-485, questa integrazione cloud non richiede alcun cablaggio fisico verso l'inverter. TapHome interroga i server SolaX Cloud via HTTPS e riceve dati in tempo reale in formato JSON. Il template supporta tutti i tipi di inverter SolaX (23 modelli nelle serie X1, X3, A1 e J1) e fornisce 11 dispositivi di monitoraggio che coprono uscita AC, stato della batteria, flusso di energia in rete e produzione FV per singolo ingresso MPPT. Gli unici requisiti sono un account SolaxCloud, un dongle di comunicazione connesso a internet (Pocket WiFi, LAN o 4G) e il token API. ## Configurazione ### Configurazione dell'account SolaxCloud L'inverter deve essere registrato e online su [SolaxCloud](https://www.solaxcloud.com). Un modulo di comunicazione (Pocket WiFi, LAN o dongle 4G) deve essere installato sull'inverter e connesso a internet. ### Ottenere il token API (tokenID) 1. Accedi a SolaxCloud su [www.solaxcloud.com](https://www.solaxcloud.com) 2. Nella barra laterale sinistra, vai a **Service > Third-party ecosystem** (o la sezione **API**) 3. Copia il **tokenID** visualizzato — si tratta di una stringa di 23 o 24 caratteri Il token è gratuito per tutti gli utenti registrati SolaxCloud. ### Trovare il numero di registrazione (sn) Il parametro `sn` è il **numero di registrazione del dongle di comunicazione** — non il numero di serie dell'inverter. Questa è una fonte comune di confusione. Dove trovarlo: - **Sul dongle** — stampato sull'etichetta del modulo Pocket WiFi / LAN / 4G (codice a barre o codice QR) - **In SolaxCloud** — vai a **Device > Inverter** e cerca la colonna **Registration No.** nella tabella ### Parametri di importazione Quando importi il template in TapHome, inserisci: - **Token ID** — il tokenID da SolaxCloud - **Registration No.** — il numero di serie a 10 caratteri del dongle di comunicazione ### Dipendenza da internet Questa è un'integrazione esclusivamente cloud. Tutti i dati transitano attraverso i server SolaX Cloud (`www.solaxcloud.com:9443`). Il template non funziona senza una connessione internet attiva sia sulla CCU TapHome che sul dongle di comunicazione dell'inverter. > [!TIP] > Per gli utenti che preferiscono la comunicazione locale senza dipendenza dal cloud, il template [SolaX Hybrid X1/X3 Gen 4 (Modbus RTU)](https://taphome.com/it/compatibility/solax-hybrid-x3-gen-4/) fornisce comunicazione diretta RS-485 con gli inverter ibridi Gen 4. ## Funzionalità dei dispositivi ### Uscita AC e produzione energetica Il contatore **AC Output** misura la produzione totale di energia AC (`yieldtotal` in kWh) e la potenza di uscita in tempo reale (`acpower` in W, convertita in kW). Un attributo di servizio riporta la produzione giornaliera (`yieldtoday` in kWh) che si azzera a mezzanotte. ### Monitoraggio della batteria - **Battery SOC** — stato di carica della batteria in percentuale dal campo `soc`. Il valore è diviso per 100 per l'intervallo di ingresso analogico TapHome 0–1 (es. 85% → 0,85). Questo è il dispositivo interrogato più frequentemente con un intervallo di 2,5 secondi - **Battery Power** — potenza istantanea di carica/scarica della batteria in watt. Valori positivi indicano carica (da FV o rete), valori negativi indicano scarica verso il carico ### Potenza di rete e misurazione dell'energia Tre dispositivi coprono il flusso di potenza della rete: - **Grid Power** — potenza di rete bidirezionale grezza in watt. Positivo = esportazione in rete, negativo = importazione dalla rete - **From Grid** — contatore che traccia l'energia consumata dalla rete. Consumo totale (`consumeenergy` in kWh) e potenza di importazione in tempo reale (estratta da `feedinpower` quando negativo, convertita in kW) - **To Grid** — contatore che traccia l'energia esportata in rete. Energia totale immessa in rete (`feedinenergy` in kWh) e potenza di esportazione in tempo reale (estratta da `feedinpower` quando positivo, convertita in kW) ### Monitoraggio della produzione FV Il template fornisce cinque dispositivi per la produzione FV: - **PV Production (Total)** — sensore calcolato che somma la potenza DC da tutti i 4 ingressi MPPT. Null-safe — gli inverter con meno di 4 stringhe restituiscono null per gli MPPT non utilizzati, che la formula tratta come zero - **PV Production (MPPT 1–4)** — letture individuali della potenza DC per ogni ingresso stringa FV in watt ### Diagnostica a livello di modulo Lo script del modulo verifica lo stato dell'inverter ad ogni interrogazione e segnala i problemi: - Lo stato **100** (Wait Mode) e **110** (Standby) generano avvisi in TapHome - Lo stato **103** (Fault Mode) e **104** (Permanent Fault Mode) generano errori - Se la risposta API indica un errore, il messaggio dal campo `exception` viene segnalato Due attributi di servizio sono disponibili sul modulo: - **Inverter status** — mappa i codici di stato 100–113 su nomi leggibili (Wait Mode, Check Mode, Normal Mode, Fault Mode, Permanent Fault Mode, Update Mode, EPS Check Mode, EPS Mode, Self-Test Mode, Idle Mode, Standby Mode, Pv Wake Up Bat Mode, Gen Check Mode, Gen Run Mode) - **Inverter type** — mappa i codici tipo 1–23 su nomi dei modelli (X1-LX, X-Hybrid, X1-Boost/Air/Mini, X3-Hybrid-G4 ecc.) ### Funzionalità aggiuntive L'API SolaX Cloud fornisce anche la potenza AC del Meter 2 (`feedinpowerM2`), la potenza EPS (Emergency Power Supply) per tre fasi (`peps1`–`peps3`), il timestamp di caricamento dati, il numero di serie dell'inverter e lo stato della batteria. Questi possono essere aggiunti in un futuro aggiornamento del template. ## Risoluzione dei problemi ### L'API restituisce un errore o nessun dato 1. Verifica che l'inverter sia online su SolaxCloud — accedi al portale web e controlla lo stato del dispositivo 2. Conferma che il tokenID sia corretto e non sia stato rigenerato (i vecchi token diventano non validi) 3. Assicurati che il parametro `sn` sia il **numero di registrazione del dongle di comunicazione**, non il numero di serie dell'inverter 4. Verifica che il dongle di comunicazione abbia una connessione internet attiva ### Letture obsolete o ritardate L'API SolaX Cloud restituisce i dati più recenti caricati dal dongle di comunicazione. La freschezza dei dati dipende dall'intervallo di caricamento del dongle (tipicamente ogni 5 minuti). Il template interroga l'API ogni 20 secondi, ma i dati sottostanti possono aggiornarsi meno frequentemente. ### Errori di limite API L'API consente un massimo di 10 richieste al minuto e 10.000 richieste al giorno. Il template interroga a intervalli di 20 secondi (circa 3 richieste al minuto), entro i limiti. Se più sistemi (TapHome, Home Assistant, altri strumenti) condividono lo stesso tokenID, il tasso combinato di richieste potrebbe superare il limite. > [!WARNING] > L'API SolaX Cloud richiede una connessione internet attiva e dipende dalla disponibilità dei server SolaX Cloud. Durante interruzioni del cloud o problemi di connettività, il template non riceverà dati aggiornati. Per installazioni che richiedono un controllo locale garantito, considera il [template Modbus RTU](https://taphome.com/it/compatibility/solax-hybrid-x3-gen-4/). ## Dispositivi disponibili 11 Questi dispositivi compaiono in TapHome dopo l'importazione. SolaX Inverter Modulo Attributi di servizio | | | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| | Stato dell'inverter | Modalità operativa attuale — Wait, Check, Normal, Fault, Permanent Fault, Update, EPS Check, EPS, Self-Test, Idle, Standby, Pv Wake Up Bat, Gen Check, Gen Run | | Tipo di inverter | Modello di inverter collegato — identifica la serie SolaX (X1, X3, A1, J1) e la generazione installata | Variabili personalizzate | | | |--------------------|-----------------------------------------------------------------------------------------| | `tokenID` (string) | Token ID dell'API SolaX Cloud (ottenibile dalla pagina API del tuo account SolaX Cloud) | | `sn` (string) | Numero di serie del modulo di comunicazione SolaX (Registration No.) | Lettura (modulo) ```taphome var response := sendhttprequest("/proxy/api/getRealtimeInfo.do?tokenId="+tokenID+"&sn="+sn); if parsejson(response.Content, "success") json := parsejson(response.Content, "result", 1); var statusCode := parsejson(json,"inverterStatus"); if statusCode = "100" addwarning("Inverter in waiting - Check DC"); end if statusCode = "103" adderror("Inverter in fault mode"); end if statusCode = "104" adderror("Inverter in permanent fault mode"); end if statusCode = "110" addwarning("Inverter in standby mode"); end else adderror(parsejson(response.Content, "exception")); end ``` Attributi di servizio Inverter status ```taphome var statusCode := parsejson(json,"inverterStatus"); IF(statusCode = "100",return("Wait Mode")); IF(statusCode = "101",return("Check Mode")); IF(statusCode = "102",return("Normal Mode")); IF(statusCode = "103",return("Fault Mode")); IF(statusCode = "104",return("Permanent Fault Mode")); IF(statusCode = "105",return("Update Mode")); IF(statusCode = "106",return("EPS Check Mode")); IF(statusCode = "107",return("EPS Mode")); IF(statusCode = "108",return("Self-Test Mode")); IF(statusCode = "109",return("Idle Mode")); IF(statusCode = "110",return("Standby Mode")); IF(statusCode = "111",return("Pv Wake Up Bat Mode")); IF(statusCode = "112",return("Gen Check Mode")); IF(statusCode = "113",return("Gen Run Mode")); ``` Inverter type ```taphome var type := parsejson(json,"inverterType"); IF(type = "1",return("X1-LX")); IF(type = "2",return("X-Hybrid")); IF(type = "3",return("X1-Hybiyd/Fit")); IF(type = "4",return("X1-Boost/Air/Mini")); IF(type = "5",return("X3-Hybiyd/Fit")); IF(type = "6",return("X3-20K/30K")); IF(type = "7",return("X3-MIC/PRO")); IF(type = "8",return("X1-Smart")); IF(type = "9",return("X1-AC")); IF(type = "10",return("A1-Hybrid")); IF(type = "11",return("A1-Fit")); IF(type = "12",return("A1-Grid")); IF(type = "13",return("J1-ESS")); IF(type = "14",return("X3-Hybrid-G4")); IF(type = "15",return("X1-Hybrid-G4")); IF(type = "16",return("X3-MIC/PRO-G2")); IF(type = "17",return("X1-SPT")); IF(type = "18",return("X1-Boost/Mini-G4")); IF(type = "19",return("A1-HYB-G2")); IF(type = "20",return("A1-AC-G2")); IF(type = "21",return("A1-SMT-G2")); IF(type = "22",return("X3-FTH")); IF(type = "23",return("X3-MGA-G2")); ``` Uscita AC Contatore elettrico Solo lettura Produzione di energia AC totale e giornaliera (kWh) con potenza di uscita in tempo reale (kW) numeric Unità: kWh / kW JSON parsejson() Attributi di servizio | | | |-------------------------------------|---------------------------------------------------------------| | Inverter.AC.energy.out.daily \[kWh] | Produzione giornaliera di energia AC — si azzera a mezzanotte | Lettura consumo totale ```taphome parsejson(json, "yieldtotal", 1) ``` Lettura domanda ```taphome parsejson(json, "acpower", 1) / 1000 ``` Attributi di servizio Inverter.AC.energy.out.daily \[kWh] ```taphome parsejson(json, "yieldtoday", 1) ``` SOC batteria Ingresso analogico Solo lettura Stato di carica della batteria in percentuale — 0% (vuota) a 100% (piena) numeric Unità: % JSON parsejson() Lettura livello ingresso ```taphome parsejson(json, "soc", 1) / 100 ``` Potenza batteria Variabile Solo lettura Potenza istantanea della batteria in watt — positiva in carica, negativa in scarica numeric Unità: W JSON parsejson() Lettura ```taphome parsejson(json,"batPower",1) ``` Energia dalla rete Contatore elettrico Solo lettura Energia consumata dalla rete — consumo totale (kWh) e potenza di importazione in tempo reale (kW) numeric Unità: kWh / kW JSON parsejson() Lettura consumo totale ```taphome parsejson(json, "consumeenergy", 1) ``` Lettura domanda ```taphome var power := parsejson(json, "feedinpower", 1); if(power < 0, power * -1, 0) / 1000 ``` Potenza di rete Variabile Solo lettura Potenza di rete bidirezionale in watt — positiva in esportazione, negativa in importazione numeric Unità: W JSON parsejson() Lettura ```taphome parsejson(json, "feedinpower", 1) ``` Produzione FV (totale) Variabile Solo lettura Potenza DC combinata da tutti gli ingressi MPPT — somma automaticamente le stringhe disponibili numeric Unità: W JSON parsejson() Lettura ```taphome var PV1 := parsejson(json,"powerdc1",1); var PV2 := parsejson(json,"powerdc2",1); var PV3 := parsejson(json,"powerdc3",1); var PV4 := parsejson(json,"powerdc4",1); if(isnull(PV1), 0, PV1) + if(isnull(PV2), 0, PV2) + if(isnull(PV3), 0, PV3) + if(isnull(PV4), 0, PV4) ``` Produzione FV (MPPT 1) Variabile Solo lettura numeric Unità: W JSON parsejson() Lettura ```taphome parsejson(json,"powerdc1",1) ``` Produzione FV (MPPT 2) Variabile Solo lettura numeric Unità: W JSON parsejson() Lettura ```taphome parsejson(json,"powerdc2",1) ``` Produzione FV (MPPT 3) Variabile Solo lettura numeric Unità: W JSON parsejson() Lettura (modulo) ```taphome parsejson(json,"powerdc3",1) ``` Produzione FV (MPPT 4) Variabile Solo lettura numeric Unità: W JSON parsejson() Lettura (modulo) ```taphome parsejson(json,"powerdc4",1) ``` Energia in rete Contatore elettrico Solo lettura Energia esportata in rete — energia totale immessa (kWh) e potenza di esportazione in tempo reale (kW) numeric Unità: kWh / kW JSON parsejson() Lettura consumo totale ```taphome parsejson(json, "feedinenergy", 1) ``` Lettura domanda ```taphome var power := parsejson(json, "feedinpower", 1); if(power > 0, power, 0) / 1000 ``` **Connessione:** Packet Parser → HTTP Possibili miglioramenti (7) - Meter 2 AC Power — Inverter.Meter2.AC.power.total, 1 W. Secondary meter power reading — available for dual-meter setups - EPS Phase 1 Power — Inverter.AC.EPS.power.R, 1 W. Emergency Power Supply output phase R - EPS Phase 2 Power — Inverter.AC.EPS.power.S, 1 W. Emergency Power Supply output phase S - EPS Phase 3 Power — Inverter.AC.EPS.power.T, 1 W. Emergency Power Supply output phase T - Upload Time — Last data upload timestamp from inverter to SolaX Cloud. Useful for stale-data detection - Inverter Serial Number — Serial number of the inverter hardware (different from communication module SN) - Battery Status — Battery status code with mapped states. Documented in HA integration but not in official API V6.1 PDF ## Parametri di importazione Inserisci questi valori quando importi l'XML. | Richiesto nell'app | Predefinito | |-----------------------------------------|------------------------------| | Token ID | Da inserire all'importazione | | Registration No. (communication module) | Da inserire all'importazione | ## Fonti - SolaX Cloud User Monitoring API V6.1 [www.solaxcloud.com](https://www.solaxcloud.com/user_api/SolaxCloud_User_Monitoring_API_V6.1.pdf) 2026-03-28 [PDF](https://taphome.com/compatibility/devices/solax-inverter/manufacturer/SolaxCloud_User_Monitoring_API_V6.1.pdf) - Home Assistant SolaX Cloud API Integration [github.com](https://github.com/NoUsername10/Solax-Cloud-API-for-Home-assistant) 2026-03-28 - SolaX KB: How to Obtain API Token [solaxpowerservice.zendesk.com](https://solaxpowerservice.zendesk.com/hc/en-001/articles/11054415299087-How-to-abtain-my-API-token) 2026-03-28 I documenti del produttore sono © dei rispettivi proprietari. Sono forniti così come pubblicati dal produttore, solo a titolo informativo. ## Documentazione correlata - [Integrazione Packet Parser](https://taphome.com/it/compatibility/packet-parser-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/it/docs/integration/packet-parser/) - [Funzioni Packet parser](https://taphome.com/it/docs/script/packet-parser/) - [Funzioni di parsing](https://taphome.com/it/docs/script/parsing-functions/)