Dokumentation · Version 1.6

Zählerstandserfassung

Funktionsübersicht für Verwaltung, mobile QR-Ablesung, Zählerablesehinweise, CSV-Export und die Anbindung anderer Systeme über REST-API.

PHP + JSONSmartphone & DesktopREST API v1.0CSV mit Semikolon

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

  1. Für eine Verbrauchsstelle wird ein eigener QR-Code bereitgestellt.
  2. Der QR-Code öffnet die mobile Erfassungsseite für genau diese Verbrauchsstelle.
  3. Vor dem Speichern kann die Person die angezeigte Bezeichnung und den Ablesehinweis prüfen.
  4. 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
Hinweis: Trage in den Einstellungen die richtige QR-Code-Basisadresse ein, wenn die Anwendung auf einer Subdomain oder in einem Unterordner installiert ist. Prüfe anschließend einen frisch erzeugten QR-Code mit einem Smartphone.

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.

FeldBeispielZweck
Verbrauchsstellennummer10001Eindeutige fachliche Zuordnung und CSV-Export.
BezeichnungStromzähler HauptgebäudeGut lesbarer Name auf QR-Ausdruck und mobiler Seite.
AblesehinweisNur die schwarzen Ziffern ablesen.Individuelle Anweisung für die Person vor Ort.
EinheitkWhEinheit 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:00 verwendet werden.
  • Der Stand wird als Zahlenwert exportiert. Einheit und Bezeichnung sind nicht Teil des angeforderten Vier-Spaltenformats.
Prüfung vor dem Import: Vergewissere dich beim Zielsystem, welches Dezimaltrennzeichen und welches Datumsformat erwartet werden. Das hier dokumentierte Format verwendet ISO-Datum 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.

Wichtig zur Integration: Die API stellt Endpunkte dieser Anwendung bereit. Eine automatische Verbindung zu einem beliebigen Fremdsystem entsteht erst, wenn dessen URL, Authentifizierung und JSON-Feldstruktur passend konfiguriert und getestet wurden.
GET/api_v1.php?action=snapshot

Gesamten 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"
}
GET/api_v1.php?action=objects, ?action=meters, ?action=readings

Einzelne 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.

POST/api_v1.php?action=sync

Objekte, 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}]
}
POST/api_v1.php?action=reading

Einzelnen 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"
}
POST/api_v1.php?action=readings/bulk

Mehrere 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-CodeBedeutung
200Erfolgreiche Anfrage; JSON enthält Daten oder ein Ergebnisobjekt.
400Ungültiger JSON-Body, fehlendes Pflichtfeld oder ungültiger Zahlenwert.
401API-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

FeldBeschreibung
idStabile, eindeutige ID eines Datensatzes.
object_idID des zugehörigen Objekts bei einer Verbrauchsstelle.
meter_idID der Verbrauchsstelle, zu der ein Zählerstand gehört.
numberFachliche Nummer, z. B. Verbrauchsstellennummer.
labelLesbare Bezeichnung der Verbrauchsstelle.
meter_numberPhysische Zählernummer, sofern bekannt.
dateAblesedatum im Format YYYY-MM-DD.
valueNumerischer Zählerstand; JSON-Zahl ohne Tausendertrennzeichen.
sourceHerkunft 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.

  1. Quell-URL und ggf. Quell-API-Schlüssel konfigurieren.
  2. Ziel-URL und ggf. Ziel-API-Schlüssel konfigurieren.
  3. Abgleich aktivieren, wenn die Verbindung getestet wurde.
  4. Den externen Cronjob beim Hosting-Anbieter planen; beispielsweise täglich auf /cron.php.
  5. Das Protokoll unter cron.log kontrollieren, sofern Schreibrechte vorhanden sind.
Keinen beliebigen Zeitplan ungeprüft übernehmen: Die tatsächliche Cron-Ausführung hängt vom Hostinganbieter ab. Prüfe dessen Zeitplan, PHP-Version, cURL-Unterstützung und Schreibrechte.

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.
Empfohlener Funktionstest: Lege ein Testobjekt und eine Testverbrauchsstelle an, scanne deren QR-Code, speichere einen Teststand, exportiere einen kurzen Zeitraum als CSV und rufe danach den API-Snapshot ab.