--- title: "SolaX Inverter (Cloud API)" description: "Każdy falownik SolaX w TapHome przez SolaX Cloud API (HTTPS): moc AC, bateria, sieć i PV z MPPT. Wymaga konta SolaxCloud, dongla i tokenu API." url: "https://taphome.com/pl/compatibility/solax-inverter/" language: pl lastmod: 2026-10-08 generator: hugo ai: topics: ["http","inverter","cloud-api","solar","battery-storage","energy-monitoring"] questions: ["Jak zintegrować falownik SolaX z TapHome przez Cloud API?","Jakie dane dostarcza szablon SolaX Cloud API w TapHome?","Jak uzyskać tokenID API SolaX dla TapHome?","Jaka jest różnica między szablonem SolaX Cloud API a Modbus w TapHome?","Czy szablon SolaX Cloud API działa ze wszystkimi modelami falowników SolaX?","Jakie są limity API dla integracji SolaX Cloud?"] --- # SolaX Inverter (Cloud API) Komunikacja: Packet Parser → HTTP - [Oficjalna strona SolaX Power](https://www.solaxpower.com) ## Poradnik integracji Szablon SolaX Cloud API łączy TapHome z dowolnym falownikiem SolaX za pośrednictwem platformy monitorującej SolaxCloud. W odróżnieniu od szablonu [SolaX Hybrid X1/X3 Gen 4](https://taphome.com/pl/compatibility/solax-hybrid-x3-gen-4/), który wykorzystuje Modbus RTU przez RS-485, ta integracja chmurowa nie wymaga żadnego fizycznego okablowania do falownika. TapHome odpytuje serwery SolaX Cloud przez HTTPS i otrzymuje dane w czasie rzeczywistym w formacie JSON. Szablon obsługuje wszystkie typy falowników SolaX (23 modele z serii X1, X3, A1 i J1) i udostępnia 11 urządzeń monitorujących obejmujących wyjście AC, stan baterii, przepływ energii sieciowej i produkcję FV na poszczególnych wejściach MPPT. Jedynymi wymaganiami są konto SolaxCloud, dongle komunikacyjny z dostępem do internetu (Pocket WiFi, LAN lub 4G) oraz token API. ## Konfiguracja ### Konfiguracja konta SolaxCloud Falownik musi być zarejestrowany i online na [SolaxCloud](https://www.solaxcloud.com). Na falowniku musi być zainstalowany moduł komunikacyjny (Pocket WiFi, LAN lub dongle 4G) podłączony do internetu. ### Uzyskanie tokenu API (tokenID) 1. Zaloguj się do SolaxCloud na [www.solaxcloud.com](https://www.solaxcloud.com) 2. W lewym panelu bocznym przejdź do **Service > Third-party ecosystem** (lub sekcji **API**) 3. Skopiuj wyświetlony **tokenID** — jest to ciąg 23 lub 24 znaków Token jest bezpłatny dla wszystkich zarejestrowanych użytkowników SolaxCloud. ### Znajdowanie numeru rejestracyjnego (sn) Parametr `sn` to **numer rejestracyjny dongla komunikacyjnego** — nie numer seryjny falownika. To częste źródło pomyłek. Gdzie go znaleźć: - **Na donglu** — wydrukowany na etykiecie modułu Pocket WiFi / LAN / 4G (kod kreskowy lub kod QR) - **W SolaxCloud** — przejdź do **Device > Inverter** i znajdź kolumnę **Registration No.** w tabeli ### Parametry importu Podczas importowania szablonu w TapHome wprowadź: - **Token ID** — tokenID z SolaxCloud - **Registration No.** — 10-znakowy numer seryjny dongla komunikacyjnego ### Zależność od internetu To jest wyłącznie chmurowa integracja. Wszystkie dane przepływają przez serwery SolaX Cloud (`www.solaxcloud.com:9443`). Szablon nie będzie działać bez aktywnego połączenia internetowego zarówno na TapHome CCU, jak i na donglu komunikacyjnym falownika. > [!TIP] > Dla użytkowników preferujących komunikację lokalną bez zależności od chmury, szablon [SolaX Hybrid X1/X3 Gen 4 (Modbus RTU)](https://taphome.com/pl/compatibility/solax-hybrid-x3-gen-4/) zapewnia bezpośrednią komunikację RS-485 z falownikami hybrydowymi Gen 4. ## Możliwości urządzeń ### Wyjście AC i produkcja energii Licznik energii **AC Output** mierzy całkowitą produkcję energii AC (`yieldtotal` w kWh) i moc wyjściową w czasie rzeczywistym (`acpower` w W, przeliczoną na kW). Atrybut serwisowy raportuje dzienny uzysk (`yieldtoday` w kWh), który resetuje się o północy. ### Monitoring baterii - **Battery SOC** — stan naładowania baterii w procentach z pola `soc`. Wartość jest dzielona przez 100 dla zakresu wejścia analogowego TapHome 0–1 (np. 85% → 0,85). To najszybciej odpytywane urządzenie z interwałem 2,5 sekundy - **Battery Power** — chwilowa moc ładowania/rozładowywania baterii w watach. Wartości dodatnie oznaczają ładowanie (z FV lub sieci), wartości ujemne oznaczają rozładowywanie do obciążenia ### Moc sieciowa i pomiar energii Trzy urządzenia obejmują przepływ mocy sieciowej: - **Grid Power** — surowa dwukierunkowa moc sieciowa w watach. Dodatnia = eksport do sieci, ujemna = pobór z sieci - **From Grid** — licznik śledzący energię pobraną z sieci. Całkowite zużycie (`consumeenergy` w kWh) i moc poboru w czasie rzeczywistym (wyodrębniona z `feedinpower` przy wartości ujemnej, przeliczona na kW) - **To Grid** — licznik śledzący energię wyeksportowaną do sieci. Całkowita energia oddana do sieci (`feedinenergy` w kWh) i moc eksportu w czasie rzeczywistym (wyodrębniona z `feedinpower` przy wartości dodatniej, przeliczona na kW) ### Monitoring produkcji FV Szablon udostępnia pięć urządzeń do monitoringu produkcji FV: - **PV Production (Total)** — obliczany sensor sumujący moc DC ze wszystkich 4 wejść MPPT. Null-safe — falowniki z mniej niż 4 stringami zwracają null dla nieużywanych MPPT, co formuła traktuje jako zero - **PV Production (MPPT 1–4)** — indywidualne odczyty mocy DC dla każdego wejścia stringa FV w watach ### Diagnostyka na poziomie modułu Główny skrypt modułu sprawdza stan falownika przy każdym odpytaniu i zgłasza problemy: - Status **100** (Wait Mode) i **110** (Standby) wyzwalają ostrzeżenia w TapHome - Status **103** (Fault Mode) i **104** (Permanent Fault Mode) wyzwalają błędy - Jeśli odpowiedź API wskazuje na błąd, komunikat z pola `exception` jest raportowany Na module dostępne są dwa atrybuty serwisowe: - **Inverter status** — mapuje kody stanu 100–113 na czytelne nazwy (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** — mapuje kody typów 1–23 na nazwy modeli (X1-LX, X-Hybrid, X1-Boost/Air/Mini, X3-Hybrid-G4 itd.) ### Dodatkowe możliwości API SolaX Cloud udostępnia również moc AC Meter 2 (`feedinpowerM2`), moc EPS (Emergency Power Supply) dla trzech faz (`peps1`–`peps3`), znacznik czasu przesłania danych, numer seryjny falownika i stan baterii. Mogą one zostać dodane w przyszłej aktualizacji szablonu. ## Rozwiązywanie problemów ### API zwraca błąd lub brak danych 1. Sprawdź, czy falownik jest online na SolaxCloud — zaloguj się na portalu i zweryfikuj stan urządzenia 2. Potwierdź, że tokenID jest prawidłowy i nie został wygenerowany ponownie (stare tokeny stają się nieważne) 3. Upewnij się, że parametr `sn` to **numer rejestracyjny dongla komunikacyjnego**, a nie numer seryjny falownika 4. Sprawdź, czy dongle komunikacyjny ma aktywne połączenie internetowe ### Nieaktualne lub opóźnione odczyty API SolaX Cloud zwraca najnowsze dane przesłane przez dongle komunikacyjny. Świeżość danych zależy od interwału przesyłania dongla (zazwyczaj co 5 minut). Szablon odpytuje API co 20 sekund, ale dane bazowe mogą aktualizować się rzadziej. ### Błędy limitów API API pozwala na maksymalnie 10 zapytań na minutę i 10 000 zapytań dziennie. Szablon odpytuje w 20-sekundowych interwałach (około 3 zapytania na minutę), co mieści się w limitach. Jeśli wiele systemów (TapHome, Home Assistant, inne narzędzia) współdzieli ten sam tokenID, łączna liczba zapytań może przekroczyć limit. > [!WARNING] > API SolaX Cloud wymaga aktywnego połączenia internetowego i zależy od dostępności serwerów SolaX Cloud. Podczas awarii chmury lub przerw w łączności szablon nie będzie otrzymywać zaktualizowanych danych. Dla instalacji wymagających gwarantowanego sterowania lokalnego rozważ [szablon Modbus RTU](https://taphome.com/pl/compatibility/solax-hybrid-x3-gen-4/). ## Dostępne urządzenia 11 Te urządzenia pojawią się w TapHome po imporcie. SolaX Inverter Moduł Atrybuty serwisowe | | | |----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | Stan falownika | Aktualny tryb pracy — Wait, Check, Normal, Fault, Permanent Fault, Update, EPS Check, EPS, Self-Test, Idle, Standby, Pv Wake Up Bat, Gen Check, Gen Run | | Typ falownika | Podłączony model falownika — identyfikuje zainstalowaną serię SolaX (X1, X3, A1, J1) i generację | Zmienne niestandardowe | | | |--------------------|----------------------------------------------------------------------------| | `tokenID` (string) | Token ID API SolaX Cloud (uzyskaj ze strony API swojego konta SolaX Cloud) | | `sn` (string) | Numer seryjny modułu komunikacyjnego SolaX (Registration No.) | Odczyt (moduł) ```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 ``` Atrybuty serwisowe 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")); ``` Wyjście AC Licznik energii Tylko do odczytu Całkowita i dzienna produkcja energii AC (kWh) z mocą wyjściową w czasie rzeczywistym (kW) numeric Jednostka: kWh / kW JSON parsejson() Atrybuty serwisowe | | | |-------------------------------------|---------------------------------------------------| | Inverter.AC.energy.out.daily \[kWh] | Dzienny uzysk energii AC — resetuje się o północy | Odczyt całkowitego zużycia ```taphome parsejson(json, "yieldtotal", 1) ``` Odczyt zapotrzebowania ```taphome parsejson(json, "acpower", 1) / 1000 ``` Atrybuty serwisowe Inverter.AC.energy.out.daily \[kWh] ```taphome parsejson(json, "yieldtoday", 1) ``` SOC baterii Wejście analogowe Tylko do odczytu Stan naładowania baterii w procentach — 0% (pusta) do 100% (pełna) numeric Jednostka: % JSON parsejson() Odczyt poziomu wejściowego ```taphome parsejson(json, "soc", 1) / 100 ``` Moc baterii Zmienna Tylko do odczytu Chwilowa moc baterii w watach — dodatnia przy ładowaniu, ujemna przy rozładowywaniu numeric Jednostka: W JSON parsejson() Odczyt ```taphome parsejson(json,"batPower",1) ``` Pobór z sieci Licznik energii Tylko do odczytu Energia pobrana z sieci — całkowite zużycie (kWh) i moc poboru w czasie rzeczywistym (kW) numeric Jednostka: kWh / kW JSON parsejson() Odczyt całkowitego zużycia ```taphome parsejson(json, "consumeenergy", 1) ``` Odczyt zapotrzebowania ```taphome var power := parsejson(json, "feedinpower", 1); if(power < 0, power * -1, 0) / 1000 ``` Moc sieciowa Zmienna Tylko do odczytu Dwukierunkowa moc sieciowa w watach — dodatnia przy eksporcie, ujemna przy poborze numeric Jednostka: W JSON parsejson() Odczyt ```taphome parsejson(json, "feedinpower", 1) ``` Produkcja FV (łącznie) Zmienna Tylko do odczytu Łączna moc DC ze wszystkich wejść MPPT — automatycznie sumuje dostępne stringi numeric Jednostka: W JSON parsejson() Odczyt ```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) ``` Produkcja FV (MPPT 1) Zmienna Tylko do odczytu numeric Jednostka: W JSON parsejson() Odczyt ```taphome parsejson(json,"powerdc1",1) ``` Produkcja FV (MPPT 2) Zmienna Tylko do odczytu numeric Jednostka: W JSON parsejson() Odczyt ```taphome parsejson(json,"powerdc2",1) ``` Produkcja FV (MPPT 3) Zmienna Tylko do odczytu numeric Jednostka: W JSON parsejson() Odczyt (moduł) ```taphome parsejson(json,"powerdc3",1) ``` Produkcja FV (MPPT 4) Zmienna Tylko do odczytu numeric Jednostka: W JSON parsejson() Odczyt (moduł) ```taphome parsejson(json,"powerdc4",1) ``` Oddawanie do sieci Licznik energii Tylko do odczytu Energia oddana do sieci — całkowita energia oddana (kWh) i moc eksportu w czasie rzeczywistym (kW) numeric Jednostka: kWh / kW JSON parsejson() Odczyt całkowitego zużycia ```taphome parsejson(json, "feedinenergy", 1) ``` Odczyt zapotrzebowania ```taphome var power := parsejson(json, "feedinpower", 1); if(power > 0, power, 0) / 1000 ``` **Połączenie:** Packet Parser → HTTP Możliwe ulepszenia (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 ## Parametry importu Te wartości podajesz podczas importu pliku XML. | Pytanie w aplikacji | Domyślnie | |-----------------------------------------|---------------------| | Token ID | Podaj przy imporcie | | Registration No. (communication module) | Podaj przy imporcie | ## Źródła - 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 Dokumenty producentów są © ich właścicieli. Udostępniamy je w formie opublikowanej przez producenta, wyłącznie w celach informacyjnych. ## Powiązana dokumentacja - [Integracja Packet Parser](https://taphome.com/pl/compatibility/packet-parser-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/pl/docs/integration/packet-parser/) - [Funkcje Packet parser](https://taphome.com/pl/docs/script/packet-parser/) - [Funkcje parsowania](https://taphome.com/pl/docs/script/parsing-functions/)