Hermetry bietet drei Wege, wie Ihre eigenen Systeme mit Ihrer Organisation zusammenarbeiten können, sowie eine separate API für Geräte. Dieser Abschnitt behandelt die ersten drei.
| Schnittstelle | Richtung | Wer nutzt sie | Anmeldung |
|---|---|---|---|
| Management-REST-API | Ihr System ruft Hermetry auf | ERPs, MES, Ticketsysteme, Skripte, Berichte | API-Schlüssel |
| Webhooks | Hermetry ruft Ihr System auf | Alles, was auf Ereignisse reagieren muss: ein Gerät, das offline geht, ein Alarm, der ausgelöst wird, ein Befehl, der endet | Ein Signaturgeheimnis, das Sie prüfen |
| MCP-Server | Ein KI-Assistent ruft Hermetry auf | KI-Assistenten, die MCP unterstützen | API-Schlüssel oder eine Anmeldung (OAuth) |
| Geräte-API | Geräte senden Daten und empfangen Befehle | Geräte und Gateways | Gerätetoken, MQTT-Benutzername und Passwort oder Zertifikat |
Die Geräte-API ist in der Geräte-Dokumentation beschrieben: MQTT, Geräte-HTTP-API und MQTT-Topics und Payloads. Verwenden Sie auf einem Gerät keinen API-Schlüssel und in einer Integration kein Gerätetoken.
Was Sie mit der Management-API tun können
Mit einem API-Schlüssel können Sie per Code alles tun, was ein Mitglied in der App tun kann, innerhalb der Berechtigungen, die Sie dem Schlüssel geben:
- Geräte und Gerätprofile auflisten, anlegen, ändern und löschen sowie Gerätezugangsdaten rotieren,
- Attribute lesen und schreiben, die neuesten Werte und den Verlauf der Telemetrie lesen,
- Befehle an Geräte senden und deren Ergebnisse lesen,
- Alarme auflisten, bestätigen und beheben sowie die Alarmregeln eines Profils ersetzen,
- den Baum aus Standorten und Anlagen aufbauen und lesen sowie Geräte darin platzieren,
- Firmware registrieren, Rollouts starten und Geräteeinstellungen ändern,
- LoRaWAN-Gateways und -Geräte verwalten.
Die REST-API hat keine Route zum Schreiben von Telemetrie. Messwerte kommen von Geräten (MQTT oder HTTP) oder aus Flows.
Ein erster Aufruf
- Öffnen Sie API Keys und erstellen Sie einen Schlüssel mit der Voreinstellung Read only des Moduls Geräte. Siehe Authentifizierung.
- Ihre Organisations-ID (
tenantId) finden Sie in der Adresszeile der App:https://<your host>/tenant/<tenantId>/admin/.... - Rufen Sie die Geräteliste ab:
curl -s "https://<your host>/tenant/<tenantId>/api/iot/devices?pageSize=5" \
-H "Authorization: Bearer sk_live_…"Die Antwort lautet { "devices": [...], "total": 42 }.
In diesem Abschnitt
Erste Schritte:
- Authentifizierung: API-Schlüssel, Berechtigungen, Netzwerke, Ablauf, Rotation.
- REST-API-Grundlagen: Pfade, Listen, Paging, Sortierung, Filter und Konventionen.
- Fehler und Ratenlimits: der Fehlerinhalt, jeder Statuscode und die Limits, die mit
429antworten.
Routenreferenzen:
- Geräte- und Profil-API
- Telemetrie- und Attribut-API
- Befehls-API
- Alarm-API
- Standort- und Anlagen-API
- Firmware- und Geräteeinstellungs-API
- LoRaWAN-API
Ereignisse:
- Webhooks: anlegen, signieren, wiederholen, testen.
- Webhook-Ereignisreferenz: jedes IoT-Ereignis mit einem Beispiel-Payload.
KI-Assistenten:
- KI-Assistenten (MCP): was ein Assistent tun kann und was er nie tun kann.
- KI-Assistenten verbinden
- MCP-Schlüssel und verbundene Apps
- MCP-Werkzeugreferenz
- MCP-Einstellungen und Sicherheit
Bevor Sie eine Integration aufbauen
- Geben Sie jeder Integration einen eigenen Schlüssel mit nur den Berechtigungen, die sie benötigt. Siehe Härtung von API-Schlüsseln.
- Rechnen Sie mit
429und beachten SieRetry-After. - Behandeln Sie IDs als undurchsichtige UUIDs. Bauen Sie sie nie selbst.
- Nutzen Sie für Änderungen Webhooks statt Polling: die Verbindung eines Geräts, einen Alarm, ein Befehlsergebnis.
- API-Schlüssel und Webhooks werden von Administratoren verwaltet. Das Rotieren des Signaturgeheimnisses eines Webhooks erfordert die Rolle Owner.