ZiggyMeter REST API

Publiczne API ZiggyMeter.

Uwierzytelnianie

API ZiggyMeter używa uwierzytelniania HTTP Bearer. Pobierz krótkożyciowy token dostępu za pomocą punktu końcowego login, a następnie przesyłaj go w nagłówku Authorization w kolejnych żądaniach.

Uwagi

• Tokeny wygasają po czasie określonym w expires_in_secs. Po tym czasie należy zalogować się ponownie.
• Brakujący lub nieprawidłowy token skutkuje błędem 401 Unauthorized.
• Zawsze używaj dokładnej nazwy nagłówka Authorization z wartością Bearer <token>.

Wyjątki

• POST /api/v1/system/login nie wymaga tokena.
• POST /api/v1/system/password nie wymaga tokena (weryfikuje old_password).

System API (/api/v1/system)

POST /api/v1/system/login

Logowanie. Zwraca token autoryzacyjny.

{
    "username": "username",
    "password": "password"
}

Pole	Typ	Opis
username	string	Nazwa użytkownika
password	string	Hasło

Odpowiedź

{
    "token": "vKEsedeLOBqLoSYYiWVrOF9To8T2RNK0ZV91aUwW",
    "expires_in_secs": 3600
}

Pole	Typ	Opis
token	string	Token autoryzacyjny
expires_in_secs	integer	Pozostały czas ważności w sekundach

POST /api/v1/system/logout

Wylogowanie

Odpowiedzi

• 200 OK z pustą treścią

GET /api/v1/system/version

Pobierz wersję oprogramowania.

Odpowiedź

{
    "firmware": {
        "version": "1.0.320",
        "date": "Jan  3 2026",
        "time": "11:50:00"
    },
    "frontend": {
        "version": "1.0.320",
        "date": "Jan  3 2026",
        "time": "11:36:31"
    },
    "build_number": 320,
    "upgrade_url": "https://fw.ziggymeter.com/"
}

Pole	Typ	Opis
firmware	object	Szczegóły wersji oprogramowania (firmware)
firmware.version	string	Wersja oprogramowania
firmware.date	string	Data kompilacji oprogramowania
firmware.time	string	Godzina kompilacji oprogramowania
frontend	object	Szczegóły wersji interfejsu (frontend)
frontend.version	string	Wersja interfejsu
frontend.date	string	Data kompilacji interfejsu
frontend.time	string	Godzina kompilacji interfejsu
build_number	integer	Numer kompilacji
upgrade_url	string	URL do aktualizacji oprogramowania

GET /api/v1/system/status

Pobierz status urządzenia.

Odpowiedzi

{
    "battery_voltage": 0,
    "usb_voltage": 5.146,
    "battery_powered": false,
    "battery_status": 0,
    "device_temperature": 26.6,
    "zigbee_enabled": false,
    "wifi_enabled": true,
    "home_assistant_enabled": false
}

Pole	Typ	Opis
battery_voltage	number	Napięcie baterii
usb_voltage	number	Napięcie USB
battery_powered	boolean	Czy urządzenie jest zasilane z baterii
battery_status	integer	Poziom naładowania baterii w procentach
device_temperature	number	Temperatura urządzenia (°C)
zigbee_enabled	boolean	Integracja Zigbee włączona
wifi_enabled	boolean	Wi-Fi włączone
home_assistant_enabled	boolean	Integracja Home Assistant włączona

POST /api/v1/system/reboot

Restart urządzenia.

Odpowiedzi

• 200 OK z pustą treścią. Urządzenie zrestartuje się natychmiast, co spowoduje zerwanie obecnych połączeń.

POST /api/v1/system/factory_reset

Przywracanie ustawień fabrycznych. Czyści całą konfigurację, w tym Wi-Fi i hasło administratora, a następnie restartuje urządzenie.

Odpowiedzi

• 200 OK z pustą treścią. Urządzenie zrestartuje się i powróci do stanu początkowej konfiguracji.

POST /api/v1/system/password

Zmiana hasła administratora.

Ten punkt końcowy nie wymaga tokena Bearer. Weryfikuje old_password.

Treść żądania

{
    "old_password": "old",
    "new_password": "new"
}

Pole	Typ	Opis
old_password	string	Aktualne hasło administratora
new_password	string	Nowe hasło administratora

Odpowiedzi

• 200 OK z pustą treścią
• 400 Bad Request jeśli brakuje pól JSON
• 403 Forbidden jeśli old_password jest nieprawidłowe

POST /api/v1/system/ota

Wysyła obraz aktualizacji oprogramowania. Po pomyślnym przesłaniu urządzenie zrestartuje się i zaktualizuje. Urządzenie zostaje zaktualizowane tylko wtedy, gdy przesłany zostanie cały obraz. Nieudana transmisja jest ignorowana i nie powoduje uszkodzenia urządzenia.

TIP

Ogranicz prędkość transmisji w przypadku problemów z połączeniem. Zobacz API.

Treść żądania

Dane binarne obrazu oprogramowania (raw binary, nie JSON).

Odpowiedzi

• 200 OK z pustą treścią po udanej transmisji i rozpoczęciu aktualizacji.
• 401 Unauthorized jeśli brakuje tokena lub jest on nieprawidłowy.
• 500 Internal Server Error jeśli aktualizacja się nie powiedzie.

Network API (/api/v1/network)

GET /api/v1/network/status

Pobierz status sieci.

Odpowiedzi

{
    "ip": "192.168.20.242",
    "netmask": "255.255.255.0",
    "gateway": "192.168.20.1",
    "hostname": "ZiggyMeter-1234",
    "dhcp": true,
    "ssid": "wifinetname",
    "rssi": -89,
    "channel": 4,
    "authmode": 3,
    "ap_mode": false
}

Pole	Typ	Opis
ip	string	Adres IP
netmask	string	Maska podsieci
gateway	string	Adres IP bramy
hostname	string	Nazwa hosta urządzenia
dhcp	boolean	DHCP włączone
ssid	string	SSID sieci Wi-Fi
rssi	integer	Siła sygnału
channel	integer	Kanał Wi-Fi
authmode	integer	Tryb uwierzytelniania
ap_mode	boolean	Tryb Punktu Dostępowego

GET /api/v1/network/scan

Skanowanie sieci Wi-Fi.

Odpowiedź

{
    "hostname": "ZiggyMeter-1234",
    "networks": [
        {
            "ssid": "Star-XYZ123",
            "bssid": "A1B2C3D4E5F6",
            "rssi": -87,
            "channel": 4,
            "authmode": 7
        },
        {
            "ssid": "HomeNet-5G",
            "bssid": "F0E1D2C3B4A5",
            "rssi": -88,
            "channel": 4,
            "authmode": 3
        },
        {
            "ssid": "GuestWiFi",
            "bssid": "9A8B7C6D5E4F",
            "rssi": -93,
            "channel": 6,
            "authmode": 3
        },
        {
            "ssid": "OfficeSecure",
            "bssid": "1F2E3D4C5B6A",
            "rssi": -94,
            "channel": 13,
            "authmode": 3
        }
    ]
}

Pole	Typ	Opis
hostname	string	Nazwa hosta urządzenia
networks	array	Lista dostępnych sieci Wi-Fi
networks[].ssid	string	SSID sieci
networks[].bssid	string	BSSID sieci (adres MAC)
networks[].rssi	integer	Siła sygnału (RSSI)
networks[].channel	integer	Kanał Wi-Fi
networks[].authmode	integer	Tryb uwierzytelniania

POST /api/v1/network/wifi

Ustawienia konfiguracji Wi-Fi.

Treść żądania

Pole	Typ	Opis
ssid	string	SSID sieci Wi-Fi (wymagane, 1-31 znaków)
password	string	Hasło Wi-Fi (wymagane, do 63 znaków)
dhcp	boolean	Włącz DHCP (wymagane)
hostname	string	Nazwa hosta (opcjonalne, do 31 znaków)
ip	string	Statyczny adres IP (wymagane jeśli DHCP wyłączone)
netmask	string	Maska podsieci (wymagane jeśli DHCP wyłączone)
gateway	string	Adres IP bramy (wymagane jeśli DHCP wyłączone)
apply	boolean	Zastosuj ustawienia natychmiast (opcjonalne, domyślnie false)

Odpowiedzi

{
    "ssid": "iot-net",
    "dhcp": true,
    "hostname": "ziggymeter1",
    "ip": "192.168.8.177",
    "netmask": "255.255.255.0",
    "gateway": "192.168.8.1"
}

Pole	Typ	Opis
ssid	string	Skonfigurowany SSID
dhcp	boolean	Status DHCP
hostname	string	Skonfigurowana nazwa hosta
ip	string	Aktualny/Statyczny adres IP
netmask	string	Aktualna/Statyczna maska sieci
gateway	string	Aktualna/Statyczna brama IP

WARNING

Jeśli apply jest ustawione na true, urządzenie natychmiast spróbuje połączyć się z nową siecią. Spowoduje to zerwanie obecnej sesji.

POST /api/v1/network/ap

Ustawienia Punktu Dostępowego (AP).

Treść żądania

Pole	Typ	Opis
ap_ssid	string	SSID Punktu Dostępowego (opcjonalne, 1-31 znaków)
ap_password	string	Hasło Punktu Dostępowego (opcjonalne, 8-63 znaki)
ap_enabled	boolean	Włącz tryb AP (opcjonalne)
apply	boolean	Zastosuj ustawienia natychmiast (opcjonalne, domyślnie false)

Odpowiedzi

{
    "ap_ssid": "ZiggyMeter-1234",
    "ap_enabled": true
}

Pole	Typ	Opis
ap_ssid	string	Skonfigurowany SSID AP
ap_enabled	boolean	Status trybu AP

Zigbee API (/api/v1/zigbee)

GET /api/v1/zigbee/config

Pobierz konfigurację Zigbee.

Odpowiedź

{
    "enabled": false,
    "channel": 11,
    "short_address": 0,
    "extended_pan_id": "00124b0000000000",
    "pan_id": 0
}

Pole	Typ	Opis
enabled	boolean	Zigbee włączone/wyłączone w zapisanej konfiguracji
channel	integer	Aktualny kanał Zigbee
short_address	integer	Aktualny adres krótki Zigbee
extended_pan_id	string	Aktualny Extended PAN ID Zigbee (16 znaków hex)
pan_id	integer	Aktualny PAN ID Zigbee

POST /api/v1/zigbee/config

Ustaw konfigurację Zigbee.

Treść żądania

{
    "enabled": true
}

Pole	Typ	Opis
enabled	boolean	Włącz lub wyłącz obsługę Zigbee

Odpowiedzi

• 200 OK z pustą treścią

POST /api/v1/zigbee/reset

Wywołuje reset Zigbee. Po resecie wewnętrzny moduł Zigbee jest czyszczony i gotowy do dołączenia do nowej sieci.

Odpowiedzi

• 200 OK z pustą treścią. Obecne sparowanie Zigbee zostanie utracone.

POST /api/v1/zigbee/map

Ustawia mapowanie punktów danych Zigbee do kodów OBIS licznika.

Treść żądania

{
    "mapping": [
        {
            "obis": "1-0:15.8.0",
            "mode": 0,
            "mapping_id": "07020000"
        },
        {
            "obis": "15.8.2",
            "mode": 1,
            "mapping_id": "07020001"
        }
    ]
}

Pole	Typ	Opis
mapping	array	Lista wpisów mapowania OBIS-do-Zigbee
mapping[].obis	string	Kod OBIS do zamapowania (np. 1.8.0 lub 1-0:15.8.0)
mapping[].mode	integer	Tryb dopasowania: 0 (pełny kod OBIS), 1 (krótki kod OBIS)
mapping[].mapping_id	string	ID mapowania Zigbee (8 znaków hex, np. 07020000; cluster + ID)

Odpowiedzi

• 200 OK z pustą treścią
• 401 Unauthorized jeśli brakuje tokena lub jest on nieprawidłowy
• 400 Bad Request jeśli struktura JSON jest nieprawidłowa

Home Assistant API (/api/v1/hass)

GET /api/v1/hass

Pobierz konfigurację Home Assistant.

Odpowiedź

{
    "enabled": false,
    "url": "https://home-assistant.local:8123",
    "cert_max_size": 10239
}

Pole	Typ	Opis
enabled	boolean	Czy integracja Home Assistant jest włączona
url	string	URL Home Assistant (obecny tylko gdy włączone)
cert_max_size	integer	Maksymalny rozmiar certyfikatu Home Assistant w bajtach

POST /api/v1/hass

Ustaw konfigurację Home Assistant.

Treść żądania

Pole	Typ	Opis
enabled	boolean	Włącz lub wyłącz integrację Home Assistant
url	string	URL serwera Home Assistant (wymagane jeśli włączone)
token	string	Długoterminowy token dostępu HA (wymagane jeśli włączone)
lang	string	Język opisów OBIS (opcjonalne, domyślnie 'en')
cert	string	Certyfikat PEM dla HTTPS (opcjonalne)

Odpowiedzi

{
    "enabled": true,
    "url": "https://home-assistant.local:8123",
    "cert_max_size": 10239
}

Pole	Typ	Opis
enabled	boolean	Czy integracja jest włączona
url	string	Docelowy URL Home Assistant
cert_max_size	integer	Maksymalny obsługiwany rozmiar certyfikatu

GET /api/v1/hass/send

Wyślij testową publikację do Home Assistant.

Odpowiedź

{
    "retcode": 0,
    "http_status_code": 200
}

Pole	Typ	Opis
retcode	integer	kod zwrotny (0 oznacza sukces)
http_status_code	integer	kod statusu HTTP zwrócony przez Home Assistant

Błędy

• 400 Bad Request jeśli Home Assistant nie jest włączony

Meter API (IEC 62056-21) (/api/v1/iec62056)

GET /api/v1/iec62056/read

Wymusza odczyt licznika i zwraca dane.

Odpowiedzi

200

Zwraca strukturę JSON ze szczegółami licznika i tablicą odczytów OBIS.

{
    "protocol": "IEC62056-21",
    "meter_id": "/XXX6\\2YYYYYY",
    "mode": "C",
    "baudrate": 9600,
    "timestamp": 293209783,
    "status": 1,
    "readings": [
        {
            "obis_long": "0-0:C.1.0",
            "obis": "C.1.0",
            "value1": "12345678",
            "value2": "",
            "value1_number": null,
            "value1_unit": "",
            "medium": 0,
            "channel": 0,
            "billing_period": null,
            "mapping_id": "00000000",
            "en": "Meter serial number"
        },
        {
            "obis_long": "1-0:15.8.0",
            "obis": "15.8.0",
            "value1": "00000001000.657*kWh",
            "value2": "",
            "value1_number": 1000.657,
            "value1_unit": "kWh",
            "medium": 1,
            "channel": 0,
            "billing_period": null,
            "mapping_id": "07020000",
            "en": "Absolute active energy total"
        }
    ]
}

Pole	Typ	Opis
protocol	string	Użyty protokół (IEC62056-21)
meter_id	string	Identyfikator licznika z telegramu powitalnego
mode	string	Tryb komunikacji (np. 'C' lub 'D')
baudrate	integer	Prędkość transmisji (baudrate)
timestamp	integer	znacznik czasu odczytu
status	integer	Kod statusu odczytu (0 = sukces, inne = błędy)
readings	array	Tablica odczytów OBIS
readings[].obis_long	string	Pełny kod OBIS (np. 1-0:1.8.0)
readings[].obis	string	Krótki kod OBIS (np. 1.8.0)
readings[].value1	string	Wartość podstawowa otrzymana z licznika
readings[].value2	string	Wartość dodatkowa (np. znacznik czasu maksimum)
readings[].value1_number	number|null	Przetworzona wartość numeryczna value1
readings[].value1_unit	string	Jednostka dla value1 (np. 'kWh', 'kW', 'V')
readings[].medium	integer|null	Identyfikator medium
readings[].channel	integer|null	Identyfikator kanału
readings[].billing_period	integer|null	Identyfikator okresu rozliczeniowego
readings[].mapping_id	string	ID mapowania Zigbee (8 znaków hex), 00000000 jeśli nie zamapowano
readings[].en	string|null	Angielski opis kodu OBIS

500

• Meter timeout: Odczyt nie zakończył się w oczekiwanym czasie (~45s).
• Meter error: Licznik zwrócił odpowiedź z błędem.

GET /api/v1/iec62056/last

Pobiera ostatnie dostępne odczyty (nie wyzwala nowego odczytu).

Odpowiedzi

200

Taki sam schemat odpowiedzi jak GET /api/v1/iec62056/read.

GET /api/v1/iec62056/config

Pobierz konfigurację licznika.

Odpowiedzi

{
    "mode_d_enabled": false,
    "mode_d_baudrate": 2400,
    "baudrate_max": 9600,
    "schedule_min": 1,
    "battery": false
}

Pole	Typ	Opis
mode_d_enabled	boolean	Czy tryb IEC 62056 D jest włączony
mode_d_baudrate	integer	Prędkość transmisji dla trybu D
baudrate_max	integer	Maksymalna obsługiwana prędkość
schedule_min	integer	Minimalny interwał harmonogramu odczytów (minuty)
battery	boolean	Czy licznik jest zasilany bateryjnie

POST /api/v1/iec62056/config

Ustaw konfigurację licznika.

Treść żądania

Pole	Typ	Opis
mode_d_enabled	boolean	Włącz lub wyłącz tryb IEC 62056 D
mode_d_baudrate	integer	Prędkość transmisji dla trybu D
baudrate_max	integer	Maksymalna obsługiwana prędkość
battery	boolean	Czy licznik jest zasilany bateryjnie
schedule_min	integer	Interwał harmonogramu odczytów w minutach (minimum -1)

Odpowiedzi

{
    "mode_d_enabled": false,
    "mode_d_baudrate": 2400,
    "baudrate_max": 9600,
    "schedule_min": 5,
    "battery": false
}

Pole	Typ	Opis
mode_d_enabled	boolean	Status trybu IEC 62056 D
mode_d_baudrate	integer	Skonfigurowany baudrate trybu D
baudrate_max	integer	Maksymalny baudrate komunikacji
schedule_min	integer	Interwał harmonogramu odczytów (minuty)
battery	boolean	Flaga zasilania bateryjnego