ZiggyMeter REST-API

Öffentliche API von ZiggyMeter.

Authentifizierung

Die ZiggyMeter-API verwendet die HTTP-Bearer-Authentifizierung. Fordern Sie über den Login-Endpunkt einen kurzlebigen Zugriffs-Token an und senden Sie diesen bei nachfolgenden Anfragen im Authorization-Header mit.

Hinweise

• Tokens laufen nach expires_in_secs ab. Nach Ablauf müssen Sie sich erneut authentifizieren.
• Fehlende oder ungültige Tokens führen zu 401 Unauthorized.
• Verwenden Sie immer den exakten Header-Namen Authorization mit dem Wert Bearer <token>.

Ausnahmen

• POST /api/v1/system/login erfordert keinen Token.
• POST /api/v1/system/password erfordert keinen Token (es validiert stattdessen old_password).

System-API (/api/v1/system)

POST /api/v1/system/login

Login. Gibt einen Autorisierungs-Token zurück.

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

Feld	Typ	Beschreibung
username	string	Benutzername
password	string	Passwort

Antwort

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

Feld	Typ	Beschreibung
token	string	Autorisierungs-Token
expires_in_secs	integer	Verbleibende Gültigkeit in Sekunden

POST /api/v1/system/logout

Logout

Antworten

• 200 OK mit leerem Body

GET /api/v1/system/version

Firmware-Version abrufen.

Antwort

{
    "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/"
}

Feld	Typ	Beschreibung
firmware	object	Details zur Firmware-Version
firmware.version	string	Firmware-Version
firmware.date	string	Build-Datum der Firmware
firmware.time	string	Build-Uhrzeit der Firmware
frontend	object	Details zur Frontend-Version
frontend.version	string	Frontend-Version
frontend.date	string	Build-Datum des Frontends
frontend.time	string	Build-Uhrzeit des Frontends
build_number	integer	Build-Nummer
upgrade_url	string	URL für Firmware-Upgrades

GET /api/v1/system/status

Gerätestatus abrufen.

Antworten

{
    "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
}

Feld	Typ	Beschreibung
battery_voltage	number	Batteriespannung
usb_voltage	number	USB-Spannung
battery_powered	boolean	Ob das Gerät batteriebetrieben ist
battery_status	integer	Batteriestand in Prozent
device_temperature	number	Gerätetemperatur (°C)
zigbee_enabled	boolean	Zigbee-Integration aktiviert
wifi_enabled	boolean	WLAN aktiviert
home_assistant_enabled	boolean	Home Assistant-Integration aktiviert

POST /api/v1/system/reboot

Gerät neu starten.

Antworten

• 200 OK mit leerem Body. Das Gerät startet sofort neu, was zum Abbruch aktueller Verbindungen führt.

POST /api/v1/system/factory_reset

Werkseinstellungen wiederherstellen. Dadurch werden alle Konfigurationen, einschließlich WLAN und Admin-Passwort, gelöscht und das Gerät neu gestartet.

Antworten

• 200 OK mit leerem Body. Das Gerät startet neu und kehrt in den ursprünglichen Einrichtungszustand zurück.

POST /api/v1/system/password

Admin-Passwort ändern.

Dieser Endpunkt erfordert kein Bearer-Token. Er validiert old_password.

Request Body

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

Feld	Typ	Beschreibung
old_password	string	Aktuelles Admin-Passwort
new_password	string	Neues Admin-Passwort

Antworten

• 200 OK mit leerem Body
• 400 Bad Request, wenn JSON-Felder fehlen
• 403 Forbidden, wenn old_password ungültig ist

POST /api/v1/system/ota

Firmware-Update-Image senden. Nach erfolgreicher Übertragung startet das Gerät neu und führt das Update durch. Das Gerät wird nur aktualisiert, wenn das gesamte Image übertragen wurde. Eine fehlgeschlagene Übertragung wird ignoriert und macht das Gerät nicht funktionsunfähig.

TIP

Begrenzen Sie bei Übertragungsproblemen die Übertragungsrate. Siehe API.

Request Body

Binäre Firmware-Image-Daten (kein JSON, rohe Binärdaten).

Antworten

• 200 OK mit leerem Body bei erfolgreicher Übertragung und Update-Start.
• 401 Unauthorized, wenn das Token fehlt oder ungültig ist.
• 500 Internal Server Error, wenn das Update fehlschlägt.

Netzwerk-API (/api/v1/network)

GET /api/v1/network/status

Netzwerkstatus abrufen.

Antworten

{
    "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
}

Feld	Typ	Beschreibung
ip	string	IP-Adresse
netmask	string	Netzmaske
gateway	string	Gateway-IP-Adresse
hostname	string	Geräte-Hostname
dhcp	boolean	DHCP aktiviert
ssid	string	WLAN-SSID
rssi	integer	Signalstärke
channel	integer	WLAN-Kanal
authmode	integer	Authentifizierungsmodus
ap_mode	boolean	Access Point-Modus

GET /api/v1/network/scan

WLAN-Netzwerke suchen.

Antwort

{
    "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
        }
    ]
}

Feld	Typ	Beschreibung
hostname	string	Geräte-Hostname
networks	array	Liste der verfügbaren WLAN-Netzwerke
networks[].ssid	string	Netzwerk-SSID
networks[].bssid	string	Netzwerk-BSSID (MAC-Adresse)
networks[].rssi	integer	Signalstärke (RSSI)
networks[].channel	integer	WLAN-Kanal
networks[].authmode	integer	Authentifizierungsmodus

POST /api/v1/network/wifi

WLAN-Konfiguration senden.

Request Body

Feld	Typ	Beschreibung
ssid	string	WLAN-SSID (erforderlich, 1-31 Zeichen)
password	string	WLAN-Passwort (erforderlich, bis zu 63 Zeichen)
dhcp	boolean	DHCP aktivieren (erforderlich)
hostname	string	Geräte-Hostname (optional, nicht leerer String bis zu 31 Zeichen)
ip	string	Statische IP-Adresse (erforderlich, wenn DHCP falsch, gültige IP)
netmask	string	Netzmaske (erforderlich, wenn DHCP falsch, gültige IP)
gateway	string	Gateway-IP-Adresse (erforderlich, wenn DHCP falsch, gültige IP)
apply	boolean	Einstellungen sofort übernehmen (optional, Standard ist falsch)

Antworten

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

Feld	Typ	Beschreibung
ssid	string	Konfigurierte WLAN-SSID
dhcp	boolean	DHCP-Status
hostname	string	Konfigurierter Hostname
ip	string	Aktuelle/Statische IP-Adresse
netmask	string	Aktuelle/Statische Netzmaske
gateway	string	Aktuelle/Statische Gateway-IP

WARNING

Wenn apply auf true gesetzt ist, versucht das Gerät sofort, eine Verbindung zum neuen Netzwerk herzustellen. Dies führt zum Abbruch der aktuellen Verbindung.

POST /api/v1/network/ap

Access Point-Konfiguration senden.

Request Body

Feld	Typ	Beschreibung
ap_ssid	string	Access Point-SSID (optional, 1-31 Zeichen)
ap_password	string	Access Point-Passwort (optional, 8-63 Zeichen)
ap_enabled	boolean	Access Point-Modus aktivieren (optional)
apply	boolean	Einstellungen sofort übernehmen (optional, Standard ist falsch)

Antworten

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

Feld	Typ	Beschreibung
ap_ssid	string	Konfigurierte AP-SSID
ap_enabled	boolean	AP-Modus Status

Zigbee-API (/api/v1/zigbee)

GET /api/v1/zigbee/config

Zigbee-Konfiguration abrufen.

Antwort

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

Feld	Typ	Beschreibung
enabled	boolean	Zigbee aktiviert/deaktiviert (aus gespeicherter Konf.)
channel	integer	Aktueller Zigbee-Kanal
short_address	integer	Aktuelle Zigbee-Kurzadresse
extended_pan_id	string	Aktuelle Zigbee Extended PAN ID (16 Hex-Zeichen)
pan_id	integer	Aktuelle Zigbee PAN ID

POST /api/v1/zigbee/config

Zigbee-Konfiguration festlegen.

Request Body

{
    "enabled": true
}

Feld	Typ	Beschreibung
enabled	boolean	Zigbee-Unterstützung aktivieren oder deaktivieren

Antworten

• 200 OK mit leerem Body

POST /api/v1/zigbee/reset

Zigbee-Reset auslösen. Nach dem Reset ist das interne Zigbee-Modul des Geräts gelöscht und bereit, einem neuen Zigbee-Netzwerk beizutreten.

Antworten

• 200 OK mit leerem Body. Die aktuelle Zigbee-Kopplung geht verloren.

POST /api/v1/zigbee/map

Zigbee-Konfiguration senden, um spezifische Zigbee-Datenpunkte den OBIS-Codes des Zählers zuzuweisen.

Request Body

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

Feld	Typ	Beschreibung
mapping	array	Liste der OBIS-zu-Zigbee-Mapping-Einträge
mapping[].obis	string	Zu mappenden OBIS-Code (z. B. 1.8.0 oder 1-0:15.8.0)
mapping[].mode	integer	Vergleichsmodus: 0 (vollständiger OBIS-Code), 1 (kurzer OBIS-Code)
mapping[].mapping_id	string	Zigbee-Mapping-ID (8 Hex-Zeichen, z. B. 07020000; Cluster + ID)

Antworten

• 200 OK mit leerem Body
• 401 Unauthorized, wenn das Token fehlt oder ungültig ist
• 400 Bad Request, wenn die JSON-Struktur ungültig ist

Home Assistant-API (/api/v1/hass)

GET /api/v1/hass

Home Assistant-Konfiguration abrufen.

Antwort

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

Feld	Typ	Beschreibung
enabled	boolean	Ob die Home Assistant-Integration aktiviert ist
url	string	Home Assistant-URL (nur vorhanden, wenn aktiviert)
cert_max_size	integer	Maximale Größe des Home Assistant-Zertifikats in Bytes

POST /api/v1/hass

Home Assistant-Konfiguration festlegen.

Request Body

Feld	Typ	Beschreibung
enabled	boolean	Home Assistant-Integration aktivieren oder deaktivieren
url	string	Server-URL von Home Assistant (erforderlich, wenn aktiviert)
token	string	Langlebiges Zugriffstoken von Home Assistant (erforderlich, wenn aktiviert)
lang	string	Sprache für OBIS-Beschreibungen (optional, Standard 'en', wenn aktiviert)
cert	string	PEM-Zertifikat für HTTPS-Verbindung (optional, wird gelöscht, wenn nicht angegeben)

Antworten

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

Feld	Typ	Beschreibung
enabled	boolean	Ob die Integration aktiviert ist
url	string	Ziel-URL von Home Assistant
cert_max_size	integer	Maximal unterstützte Zertifikatsgröße

GET /api/v1/hass/send

Test-Veröffentlichung an Home Assistant senden.

Antwort

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

Feld	Typ	Beschreibung
retcode	integer	Rückgabecode (0 bedeutet Erfolg)
http_status_code	integer	Von Home Assistant zurückgegebener HTTP-Statuscode

Fehler

• 400 Bad Request, wenn Home Assistant nicht aktiviert ist

Zähler-API (IEC 62056-21) (/api/v1/iec62056)

GET /api/v1/iec62056/read

Zählerauslesung auslösen und Werte zurückgeben.

Antworten

200

Gibt die JSON-Struktur mit Zählerdetails und einem Array von OBIS-Ablesungen zurück.

{
    "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"
        }
    ]
}

Feld	Typ	Beschreibung
protocol	string	Verwendetes Protokoll (IEC62056-21)
meter_id	string	Zählerkennung aus dem Identifikationstelegramm des Zählers
mode	string	Kommunikationsmodus (z. B. 'C' oder 'D')
baudrate	integer	Für die Kommunikation verwendete Baudrate
timestamp	integer	Epoch-Zeitstempel der Ablesung
status	integer	Auslesestatus-Code (0 = Erfolg, andere Werte deuten auf Fehler hin)
readings	array	Array von OBIS-Ablesungen
readings[].obis_long	string	Vollständiger OBIS-Code (z. B. 1-0:1.8.0)
readings[].obis	string	Kurzer OBIS-Code (z. B. 1.8.0)
readings[].value1	string	Primärer Wert, wie vom Zähler empfangen
readings[].value2	string	Sekundärer Wert (z. B. Zeitstempel des Maximums), falls vorhanden
readings[].value1_number	number|null	Geparster numerischer Wert von value1
readings[].value1_unit	string	Einheit für value1 (z. B. 'kWh', 'kW', 'V')
readings[].medium	integer|null	Medium-Kennung
readings[].channel	integer|null	Kanal-Kennung
readings[].billing_period	integer|null	Abrechnungsperioden-Kennung
readings[].mapping_id	string	Zigbee-Mapping-ID (8 Hex-Zeichen, z. B. 07020000), oder 00000000 falls nicht gemappt
readings[].en	string|null	Englische Beschreibung des OBIS-Codes

500

• Meter timeout: Die Auslesung wurde nicht innerhalb des erwarteten Zeitrahmens abgeschlossen (~45s).
• Meter error: Der Zähler gab eine Fehlermeldung zurück.

GET /api/v1/iec62056/last

Letzte verfügbare Zählerstände abrufen (löst keine neue Auslesung aus).

Antworten

200

Gleiches Antwortschema wie GET /api/v1/iec62056/read.

GET /api/v1/iec62056/config

Zählerkonfiguration abrufen.

Antworten

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

Feld	Typ	Beschreibung
mode_d_enabled	boolean	Ob IEC 62056 Modus D aktiviert ist
mode_d_baudrate	integer	Baudrate für Modus-D-Kommunikation
baudrate_max	integer	Maximal unterstützte Baudrate
schedule_min	integer	Mindestintervall für Ablesezeitplan (Minuten)
battery	boolean	Ob der Zähler batteriebetrieben ist

POST /api/v1/iec62056/config

Zählerkonfiguration senden.

Request Body

Feld	Typ	Beschreibung
mode_d_enabled	boolean	IEC 62056 Modus D aktivieren oder deaktivieren
mode_d_baudrate	integer	Baudrate für Modus-D-Kommunikation (muss eine gültige Baudrate sein)
baudrate_max	integer	Maximal unterstützte Baudrate (muss eine gültige Baudrate sein)
battery	boolean	Ob der Zähler batteriebetrieben ist
schedule_min	integer	Mindestintervall für Ablesezeitplan in Minuten (Minimum -1)

Antworten

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

Feld	Typ	Beschreibung
mode_d_enabled	boolean	IEC 62056 Modus D Status
mode_d_baudrate	integer	Konfigurierte Modus-D-Baudrate
baudrate_max	integer	Maximale Kommunikations-Baudrate
schedule_min	integer	Intervall für Ablesezeitplan (Minuten)
battery	boolean	Batteriebetriebs-Flag