1. Überblick
Die Zählerstandserfassung verwaltet Objekte und zugehörige Verbrauchsstellen. Zählerstände können in der Administration manuell eingetragen oder über eine Smartphone-Seite nach dem Scannen eines QR-Codes erfasst werden. Die Daten werden in JSON-Dateien gespeichert; eine relationale Datenbank ist für den Betrieb nicht erforderlich.
Einfach ablesen
QR-Code scannen, Verbrauchsstelle kontrollieren, Zählerstand eingeben und speichern.
Daten austauschen
CSV-Export für ausgewählte Zeiträume und REST-Endpunkte für automatisierten Datenaustausch.
Verwaltung zentral
Objekte, Verbrauchsstellen, Nutzer und Schnittstelleneinstellungen an einer Stelle pflegen.
Ohne Datenbank
Die Anwendung verwendet JSON-Dateien im Datenverzeichnis. Dieses Verzeichnis muss vor direktem Webzugriff geschützt sein.
2. Verwaltung
Objekte
Objekte bilden Gebäude oder Standorte ab. Typische Angaben sind eine interne Nummer, Name und Anschrift. Verbrauchsstellen werden einem Objekt zugeordnet.
Verbrauchsstellen / Zähler
Je Verbrauchsstelle können eine ID, eine Verbrauchsstellennummer, eine Bezeichnung, die Zählernummer und eine Einheit wie kWh oder m³ hinterlegt werden. Die Bezeichnung hilft Mitarbeitenden, den richtigen Zähler vor Ort zu identifizieren.
Benutzer & Einstellungen
Die Administration ist anmeldegeschützt. API- und Synchronisierungseinstellungen sowie – falls eingerichtet – SMTP-Einstellungen werden zentral verwaltet. Nach der Erstinstallation sollte das Standard-Administratorkennwort umgehend geändert werden.
3. QR-Code & mobile Erfassung
- Für eine Verbrauchsstelle wird ein eigener QR-Code bereitgestellt.
- Der QR-Code öffnet die mobile Erfassungsseite für genau diese Verbrauchsstelle.
- Vor dem Speichern kann die Person die angezeigte Bezeichnung und den Ablesehinweis prüfen.
- Der eingegebene Stand wird zusammen mit dem Erfassungsdatum und der Herkunft gespeichert.
QR-Codes können für einzelne Verbrauchsstellen sowie als druckbare Sammelseite vorbereitet werden. Die QR-Codes verweisen auf eine URL der Installation, typischerweise in der Form:
https://IHRE-DOMAIN/zaehlerstand_erfassen.php?meter=VERBRAUCHSSTELLEN-ID
4. Bezeichnungen & Zählerablesehinweise
Jede Verbrauchsstelle kann eine frei wählbare Bezeichnung und einen individuellen Ablesehinweis erhalten. Die Bezeichnung wird im QR-Code-Ausdruck bzw. in der zugehörigen mobilen Erfassungsansicht angezeigt. Der Hinweis unterstützt eine korrekte Ablesung direkt vor Ort.
| Feld | Beispiel | Zweck |
|---|---|---|
| Verbrauchsstellennummer | 10001 | Eindeutige fachliche Zuordnung und CSV-Export. |
| Bezeichnung | Stromzähler Hauptgebäude | Gut lesbarer Name auf QR-Ausdruck und mobiler Seite. |
| Ablesehinweis | Nur die schwarzen Ziffern ablesen. | Individuelle Anweisung für die Person vor Ort. |
| Einheit | kWh | Einheit des erfassten Zählerstands. |
Die Bezeichnung ist ein Anzeige-/Orientierungsfeld; für den maschinellen Datenaustausch sollten stabile IDs und Verbrauchsstellennummern verwendet werden.
5. Zählerstände, Übersicht und Historie
- Zählerstände lassen sich in der Administration manuell erfassen.
- Die mobile QR-Erfassung speichert einen Stand für die ausgewählte Verbrauchsstelle.
- Die Übersicht kann nach Objekt und Datum gefiltert werden.
- Die Anwendung kann fehlende bzw. überfällige Ablesungen kennzeichnen; in der mobilen Ansicht werden insbesondere Verbrauchsstellen mit länger zurückliegendem Stand hervorgehoben.
- Die letzten zwölf Stände pro Verbrauchsstelle sind in der vorgesehenen Historienansicht verfügbar.
- Neu importierte Verbrauchsstellen können gekennzeichnet werden; Benachrichtigungen sind abhängig von der Mailkonfiguration.
6. CSV-Export für einen Zeitraum
Mit dem CSV-Export können gespeicherte Zählerstände für einen bestimmten Zeitraum heruntergeladen und beispielsweise in Excel oder ein anderes Auswertungssystem übernommen werden. Der Zeitraum wird über Start- und Enddatum eingegrenzt.
Spaltenformat
Verbrauchsstellennummer;Datum;Uhrzeit;Stand
Beispiel
Verbrauchsstellennummer;Datum;Uhrzeit;Stand 10001;2026-10-01;08:15:00;15234.5 10001;2026-10-15;09:30:00;15421.8 10002;2026-10-15;10:10:00;823.4
- Trennzeichen: Semikolon (
;). - Die Verbrauchsstellennummer identifiziert die fachliche Stelle.
- Datum und Uhrzeit stammen aus dem gespeicherten Erfassungszeitpunkt, soweit verfügbar.
- Bei älteren Datensätzen ohne Uhrzeit kann als Ersatz
00:00:00verwendet werden. - Der Stand wird als Zahlenwert exportiert. Einheit und Bezeichnung sind nicht Teil des angeforderten Vier-Spaltenformats.
JJJJ-MM-TT und einen Punkt als Dezimaltrennzeichen in den Beispieldaten.7. REST-API v1.0
Die REST-API stellt JSON-Daten bereit und kann Objekte, Verbrauchsstellen und Zählerstände lesen oder Daten entgegennehmen. Der Basis-Endpunkt liegt in der Installation unter /api_v1.php. Die folgenden Beispiele zeigen relative Pfade; ersetze die Domain durch die tatsächliche Adresse deiner Installation.
/api_v1.php?action=snapshotGesamten Datenbestand lesen
Gibt Objekte, Verbrauchsstellen und Zählerstände zusammen mit API-Version und Erstellungszeitpunkt zurück.
{
"api_version": "1.0",
"objects": [{"id":"OBJ-100","number":"100","name":"Schule Nord"}],
"meters": [{"id":"ZS-100-01","object_id":"OBJ-100","number":"100-01","label":"Hauptwasserzähler","unit":"m³"}],
"readings": [{"id":"READ-1","meter_id":"ZS-100-01","date":"2026-10-21","value":1238.12,"source":"qr-mobile"}],
"generated_at": "2026-10-21T09:15:00+02:00"
}/api_v1.php?action=objects, ?action=meters, ?action=readingsEinzelne Listen lesen
Gibt jeweils die passende Liste im Feld data sowie API-Version und Erstellungszeitpunkt zurück. Diese Endpunkte sind sinnvoll, wenn nicht der vollständige Snapshot benötigt wird.
/api_v1.php?action=syncObjekte, Verbrauchsstellen und Stände synchronisieren
Akzeptiert ein JSON-Objekt mit optionalen Arrays objects, meters und readings. Datensätze werden anhand ihrer id ergänzt oder aktualisiert. Nicht mitgesendete Datensätze werden nicht automatisch gelöscht.
{
"objects": [{"id":"OBJ-100","number":"100","name":"Schule Nord"}],
"meters": [{"id":"ZS-100-01","object_id":"OBJ-100","number":"100-01","label":"Hauptwasserzähler","unit":"m³"}],
"readings": [{"id":"READ-2","meter_id":"ZS-100-01","date":"2026-10-21","value":1238.12}]
}/api_v1.php?action=readingEinzelnen Zählerstand senden
Pflichtfelder: meter_id und numerischer value. Optional sind id, date und source. Wenn keine ID angegeben wird, erzeugt die Anwendung eine ID.
{
"id": "READ-2026-0002",
"meter_id": "ZS-100-01",
"date": "2026-10-21",
"value": 1238.12,
"source": "external"
}/api_v1.php?action=readings/bulkMehrere Zählerstände in einem Request senden
Erwartet ein Objekt mit einem Array readings. Jeder gültige Eintrag benötigt meter_id und value; optional sind unter anderem id, date, source und created_at.
{
"api_version": "1.0",
"readings": [
{"id":"R123","meter_id":"ZS-100-01","date":"2026-10-21","value":1238.12,"source":"qr-mobile","created_at":"2026-10-21T09:15:00+02:00"}
]
}Antworten und Statuscodes
| HTTP-Code | Bedeutung |
|---|---|
200 | Erfolgreiche Anfrage; JSON enthält Daten oder ein Ergebnisobjekt. |
400 | Ungültiger JSON-Body, fehlendes Pflichtfeld oder ungültiger Zahlenwert. |
401 | API-Schlüssel fehlt oder ist ungültig, sofern ein Schlüssel in der Konfiguration gesetzt ist. |
cURL-Beispiele
Lesen eines Snapshots:
curl -H "X-API-Key: MEIN_API_TOKEN" \ "https://IHRE-DOMAIN/api_v1.php?action=snapshot"
Einen Stand übertragen:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-API-Key: MEIN_API_TOKEN" \
-d '{"meter_id":"ZS-100-01","date":"2026-10-21","value":1238.12}' \
"https://IHRE-DOMAIN/api_v1.php?action=reading"
Feldmodell
| Feld | Beschreibung |
|---|---|
id | Stabile, eindeutige ID eines Datensatzes. |
object_id | ID des zugehörigen Objekts bei einer Verbrauchsstelle. |
meter_id | ID der Verbrauchsstelle, zu der ein Zählerstand gehört. |
number | Fachliche Nummer, z. B. Verbrauchsstellennummer. |
label | Lesbare Bezeichnung der Verbrauchsstelle. |
meter_number | Physische Zählernummer, sofern bekannt. |
date | Ablesedatum im Format YYYY-MM-DD. |
value | Numerischer Zählerstand; JSON-Zahl ohne Tausendertrennzeichen. |
source | Herkunft des Datensatzes, z. B. qr-mobile oder external. |
8. Sicherheit & Authentifizierung
- Die API verwendet den HTTP-Header
X-API-Key. - Setze einen langen, zufälligen API-Schlüssel in der Administration. In der aktuellen Implementierung wird der Schlüssel geprüft, wenn in der Konfiguration ein Token gesetzt ist; ein leerer Token deaktiviert diese Prüfung. Deshalb für den Produktivbetrieb unbedingt einen Token setzen.
- Nutze HTTPS, damit API-Schlüssel und Zählerstände nicht unverschlüsselt übertragen werden.
- Das Verzeichnis
data/enthält Anwendungsdaten und Konfiguration. Direkte Webzugriffe müssen blockiert sein. - API-Schlüssel nicht in öffentliche Dokumentationen, Screenshots oder Quellcode-Repositories kopieren.
9. Cronjob & Synchronisierung
Der Cronjob ist für geplante Hintergrundaufgaben vorgesehen. Je nach Konfiguration kann er einen Snapshot aus einem Quellsystem importieren und neue Zählerstände an ein Zielsystem exportieren. Die tatsächliche Synchronisierung funktioniert nur, wenn erreichbare Endpunkte und passende Schlüssel konfiguriert sind.
- Quell-URL und ggf. Quell-API-Schlüssel konfigurieren.
- Ziel-URL und ggf. Ziel-API-Schlüssel konfigurieren.
- Abgleich aktivieren, wenn die Verbindung getestet wurde.
- Den externen Cronjob beim Hosting-Anbieter planen; beispielsweise täglich auf
/cron.php. - Das Protokoll unter
cron.logkontrollieren, sofern Schreibrechte vorhanden sind.
10. Installation & Betrieb
- PHP 8 oder neuer wird empfohlen; für ausgehende HTTP-Aufrufe des Cronjobs wird cURL benötigt.
- Das Verzeichnis
data/benötigt Schreibrechte für den PHP-Prozess. - Die Anwendung kann in einem eigenen Webverzeichnis oder auf einer Subdomain betrieben werden. Das Dokumentenverzeichnis der Subdomain muss auf den Ordner zeigen, in dem die Einstiegsdateien liegen.
- Nach dem Hochladen die Anmeldeseite, einen QR-Code, die mobile Erfassung, den CSV-Export und einen API-Leseaufruf testen.
- Vor Updates ein Backup des gesamten Anwendungsverzeichnisses einschließlich
data/erstellen. Bei Updates den vorhandenen Datenordner nicht unbedacht überschreiben. - Der QR-Code-Generator kann von einem externen CDN abhängen; zum Erzeugen der QR-Codes kann daher eine Internetverbindung im Browser erforderlich sein.
11. Hinweise und technische Grenzen
- Die API ist eine Referenzschnittstelle. Sie unterstützt derzeit keine allgemeine OAuth2-Anmeldung, Signaturen oder herstellerspezifisches Mapping.
- Stabile IDs sind wichtig, damit Synchronisierungen vorhandene Datensätze aktualisieren statt Dubletten anzulegen.
- Die aktuelle Synchronisierung löscht keine Datensätze allein deshalb, weil sie in einem Snapshot fehlen.
- Die CSV-Datei enthält absichtlich nur die vier angeforderten Spalten. Einheit, Objektname und Bezeichnung werden nicht zusätzlich exportiert.
- Vor dem produktiven Datenaustausch müssen Feldnamen, Zeitformat, Einheiten und Fehlerbehandlung mit dem Fremdsystem abgestimmt werden.