Koncové body REST API ZiggyMeter

Veřejné API ZiggyMeter.

Autentizace

API ZiggyMeter používá autentizaci HTTP Bearer. Získejte krátkodobý přístupový token prostřednictvím přihlašovacího koncového bodu a poté jej posílejte v hlavičce Authorization při následných požadavcích.

Poznámky

• Tokeny vyprší po uplynutí doby expires_in_secs. Po vypršení se znovu autentizujte.
• Chybějící nebo neplatné tokeny budou mít za následek chybu 401 Unauthorized.
• Vždy zahrňte přesný název hlavičky Authorization s hodnotou Bearer <token>.

Výjimky

• POST /api/v1/system/login nevyžaduje token.
• POST /api/v1/system/password nevyžaduje token (místo toho validuje old_password).

Systémové API (/api/v1/system)

POST /api/v1/system/login

Přihlášení. Vrací autorizační token.

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

Pole	Typ	Popis
username	string	Uživatelské jméno
password	string	Heslo

Odpověď

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

Pole	Typ	Popis
token	string	Autorizační token
expires_in_secs	integer	Zbývající platnost v sekundách

POST /api/v1/system/logout

Odhlášení

Odpovědi

• 200 OK s prázdným tělem

GET /api/v1/system/version

Získat verzi firmwaru.

Odpověď

{
    "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	Popis
firmware	object	Podrobnosti o verzi firmwaru
firmware.version	string	Verze firmwaru
firmware.date	string	Datum sestavení firmwaru
firmware.time	string	Čas sestavení firmwaru
frontend	object	Podrobnosti o verzi frontend
frontend.version	string	Verze frontend
frontend.date	string	Datum sestavení frontend
frontend.time	string	Čas sestavení frontend
build_number	integer	Číslo sestavení
upgrade_url	string	URL pro aktualizaci firmwaru

GET /api/v1/system/status

Získat stav zařízení.

Odpovědi

{
    "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	Popis
battery_voltage	number	Napětí baterie
usb_voltage	number	Napětí USB
battery_powered	boolean	Zda je zařízení napájeno baterií
battery_status	integer	Úroveň nabití baterie v procentech
device_temperature	number	Teplota zařízení (°C)
zigbee_enabled	boolean	Integrace Zigbee povolena
wifi_enabled	boolean	Wi-Fi povolena
home_assistant_enabled	boolean	Integrace Home Assistant povolena

POST /api/v1/system/reboot

Restartovat zařízení.

Odpovědi

• 200 OK s prázdným tělem. Zařízení se okamžitě restartuje, což způsobí přerušení aktuálních spojení.

POST /api/v1/system/factory_reset

Tovární reset. Vymaže veškerou konfiguraci, včetně Wi-Fi a hesla správce, a restartuje zařízení.

Odpovědi

• 200 OK s prázdným tělem. Zařízení se restartuje a vrátí se do výchozího stavu nastavení.

POST /api/v1/system/password

Změnit heslo správce.

Tento koncový bod nevyžaduje Bearer token. Validuje old_password.

Tělo požadavku

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

Pole	Typ	Popis
old_password	string	Aktuální heslo správce
new_password	string	Nové heslo správce

Odpovědi

• 200 OK s prázdným tělem
• 400 Bad Request pokud chybí pole JSON
• 403 Forbidden pokud je old_password neplatné

POST /api/v1/system/ota

Odesílá obraz aktualizace firmwaru. Po úspěšném přenosu se zařízení restartuje a aktualizuje. Zařízení je aktualizováno pouze tehdy, když je přenesen celý obraz. Neúspěšný přenos je ignorován a nezpůsobí nefunkčnost zařízení.

TIP

V případě problémů s přenosem omezte rychlost přenosu. Viz API.

Tělo požadavku

Binární data obrazu firmwaru (nikoli JSON, surová binární data).

Odpovědi

• 200 OK s prázdným tělem po úspěšném přenosu a zahájení aktualizace.
• 401 Unauthorized pokud token chybí nebo je neplatný.
• 500 Internal Server Error pokud aktualizace selže.

Síťové API (/api/v1/network)

GET /api/v1/network/status

Získat stav sítě.

Odpovědi

{
    "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	Popis
ip	string	IP adresa
netmask	string	Maska sítě
gateway	string	IP adresa brány
hostname	string	Hostitelské jméno zařízení
dhcp	boolean	DHCP povoleno
ssid	string	SSID Wi-Fi
rssi	integer	Síla signálu
channel	integer	Kanál Wi-Fi
authmode	integer	Režim autentizace
ap_mode	boolean	Režim přístupového bodu (AP)

GET /api/v1/network/scan

Získat Wi-Fi sítě.

Odpověď

{
    "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	Popis
hostname	string	Hostitelské jméno zařízení
networks	array	Seznam dostupných Wi-Fi sítí
networks[].ssid	string	SSID sítě
networks[].bssid	string	BSSID sítě (MAC adresa)
networks[].rssi	integer	Síla signálu (RSSI)
networks[].channel	integer	Kanál Wi-Fi
networks[].authmode	integer	Režim autentizace

POST /api/v1/network/wifi

Odeslat konfiguraci Wi-Fi.

Tělo požadavku

Pole	Typ	Popis
ssid	string	SSID Wi-Fi (vyžadováno, 1-31 znaků)
password	string	Heslo Wi-Fi (vyžadováno, až 63 znaků)
dhcp	boolean	Povolit DHCP (vyžadováno)
hostname	string	Hostitelské jméno zařízení (volitelné, neprázdný řetězec až 31 znaků)
ip	string	Statická IP adresa (vyžadováno, pokud je DHCP false, platná IP)
netmask	string	Maska sítě (vyžadováno, pokud je DHCP false, platná IP)
gateway	string	IP adresa brány (vyžadováno, pokud je DHCP false, platná IP)
apply	boolean	Použít nastavení okamžitě (volitelné, výchozí hodnota false)

Odpovědi

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

Pole	Typ	Popis
ssid	string	Nakonfigurované SSID Wi-Fi
dhcp	boolean	Stav DHCP
hostname	string	Nakonfigurované hostitelské jméno
ip	string	Aktuální/Statická IP adresa
netmask	string	Aktuální/Statická maska sítě
gateway	string	Aktuální/Statická IP brány

WARNING

Pokud je apply nastaveno na true, zařízení se pokusí okamžitě připojit k nové síti. To způsobí přerušení aktuálního spojení.

POST /api/v1/network/ap

Odeslat konfiguraci přístupového bodu (AP).

Tělo požadavku

Pole	Typ	Popis
ap_ssid	string	SSID přístupového bodu (volitelné, 1-31 znaků)
ap_password	string	Heslo přístupového bodu (volitelné, 8-63 znaků)
ap_enabled	boolean	Povolit režim přístupového bodu (volitelné)
apply	boolean	Použít nastavení okamžitě (volitelné, výchozí hodnota false)

Odpovědi

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

Pole	Typ	Popis
ap_ssid	string	Nakonfigurované SSID AP
ap_enabled	boolean	Stav režimu AP

Zigbee API (/api/v1/zigbee)

GET /api/v1/zigbee/config

Získat konfiguraci Zigbee.

Odpověď

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

Pole	Typ	Popis
enabled	boolean	Zigbee povoleno/zakázáno podle uložené konfigurace
channel	integer	Aktuální kanál Zigbee
short_address	integer	Aktuální krátká adresa Zigbee
extended_pan_id	string	Aktuální rozšířené PAN ID Zigbee (16 hex znaků)
pan_id	integer	Aktuální PAN ID Zigbee

POST /api/v1/zigbee/config

Nastavit konfiguraci Zigbee.

Tělo požadavku

{
    "enabled": true
}

Pole	Typ	Popis
enabled	boolean	Povolit nebo zakázat podporu Zigbee

Odpovědi

• 200 OK s prázdným tělem

POST /api/v1/zigbee/reset

Spustit reset Zigbee. Po resetu je interní modul Zigbee vymazán a připraven k připojení k nové síti Zigbee.

Odpovědi

• 200 OK s prázdným tělem. Aktuální párování Zigbee bude ztraceno.

POST /api/v1/zigbee/map

Odeslat konfiguraci Zigbee pro přiřazení konkrétních datových bodů Zigbee k OBIS kódům elektroměru.

Tělo požadavku

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

Pole	Typ	Popis
mapping	array	Seznam položek mapování OBIS na Zigbee
mapping[].obis	string	OBIS kód k mapování (např. 1.8.0 nebo 1-0:15.8.0)
mapping[].mode	integer	Režim shody: 0 (shoda s úplným kódem OBIS), 1 (shoda s krátkým kódem OBIS)
mapping[].mapping_id	string	Zigbee mapovací ID (8 hex znaků, např. 07020000; cluster + ID)

Odpovědi

• 200 OK s prázdným tělem
• 401 Unauthorized pokud token chybí nebo je neplatný
• 400 Bad Request pokud je struktura JSON neplatná

Home Assistant API (/api/v1/hass)

GET /api/v1/hass

Získat konfiguraci Home Assistant.

Odpověď

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

Pole	Typ	Popis
enabled	boolean	Zda je integrace Home Assistant povolena
url	string	URL Home Assistant (přítomno pouze při povolení)
cert_max_size	integer	Maximální velikost certifikátu Home Assistant v bajtech

POST /api/v1/hass

Nastavit konfiguraci Home Assistant.

Tělo požadavku

Pole	Typ	Popis
enabled	boolean	Povolit nebo zakázat integraci Home Assistant
url	string	URL serveru Home Assistant (vyžadováno při povolení)
token	string	Dlouhodobý přístupový token Home Assistant (vyžadováno při povolení)
lang	string	Jazyk pro popisů OBIS (volitelné, výchozí 'en' při povolení)
cert	string	PEM certifikát pro HTTPS spojení (volitelné, při neposkytnutí a povolení se vymaže)

Odpovědi

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

Pole	Typ	Popis
enabled	boolean	Zda je integrace povolena
url	string	Cílová URL Home Assistant
cert_max_size	integer	Maximální podporovaná velikost certifikátu

GET /api/v1/hass/send

Odeslat testovací publikaci do Home Assistant.

Odpověď

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

Pole	Typ	Popis
retcode	integer	návratový kód (0 znamená úspěch)
http_status_code	integer	HTTP stavový kód vrácený Home Assistantem

Chyby

• 400 Bad Request pokud není povolena integrace Home Assistant

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

GET /api/v1/iec62056/read

Spustit odečet elektroměru a vrátit naměřené hodnoty.

Odpovědi

200

Vrací JSON strukturu s podrobnostmi o elektroměru a polem odečtů 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	Popis
protocol	string	Použitý protokol (IEC62056-21)
meter_id	string	Identifikátor elektroměru z identifikačního telegramu elektroměru
mode	string	Komunikační režim (např. 'C' nebo 'D')
baudrate	integer	Přenosová rychlost (baudrate) použitá pro komunikaci
timestamp	integer	Epoch časové razítko odečtu
status	integer	Stavový kód odečtu (0 = úspěch, ostatní hodnoty indikují chyby)
readings	array	Pole odečtů OBIS
readings[].obis_long	string	Úplný OBIS kód (např. 1-0:1.8.0)
readings[].obis	string	Krátký OBIS kód (např. 1.8.0)
readings[].value1	string	Primární hodnota přijatá z elektroměru
readings[].value2	string	Sekundární hodnota (např. časové razítko maxima), pokud je přítomna
readings[].value1_number	number|null	Parsed numeric value of value1
readings[].value1_unit	string	Jednotka pro value1 (např. 'kWh', 'kW', 'V')
readings[].medium	integer|null	Identifikátor média
readings[].channel	integer|null	Identifikátor kanálu
readings[].billing_period	integer|null	Identifikátor zúčtovacího období
readings[].mapping_id	string	Zigbee mapovací ID (8 hex znaků, např. 07020000), nebo 00000000, pokud není mapováno
readings[].en	string|null	Anglický popis OBIS kódu

500

• Meter timeout: Odečet neskončil v očekávaném časovém rámci (~45 s).
• Meter error: Elektroměr vrátil chybovou odpověď.

GET /api/v1/iec62056/last

Získat poslední dostupné odečty elektroměru (nespouští nový odečet).

Odpovědi

200

Stejné schéma odpovědi jako GET /api/v1/iec62056/read.

GET /api/v1/iec62056/config

Získat konfiguraci elektroměru.

Odpovědi

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

Pole	Typ	Popis
mode_d_enabled	boolean	Zda je povolen IEC 62056 režim D
mode_d_baudrate	integer	Přenosová rychlost pro komunikaci v režimu D
baudrate_max	integer	Maximální podporovaná přenosová rychlost
schedule_min	integer	Minimální interval plánovaného odečtu (minuty)
battery	boolean	Zda je elektroměr napájen z baterie

POST /api/v1/iec62056/config

Odeslat konfiguraci elektroměru.

Tělo požadavku

Pole	Typ	Popis
mode_d_enabled	boolean	Povolit nebo zakázat IEC 62056 režim D
mode_d_baudrate	integer	Přenosová rychlost pro režim D (musí být platná hodnota)
baudrate_max	integer	Maximální podporovaná přenosová rychlost (musí být platná hodnota)
battery	boolean	Zda je elektroměr napájen z baterie
schedule_min	integer	Minimální interval plánovaného odečtu v minutách (minimálně -1)

Odpovědi

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

Pole	Typ	Popis
mode_d_enabled	boolean	Stav režimu D IEC 62056
mode_d_baudrate	integer	Nakonfigurovaná přenosová rychlost pro režim D
baudrate_max	integer	Maximální komunikační přenosová rychlost
schedule_min	integer	Interval plánovaných odečtů (minuty)
battery	boolean	Příznak provozu na baterie