--- title: "TapHome API" description: "TapHome-Geräte über REST API in beliebige Apps integrieren. Authentifizierung, Gerätesteuerung, Webhooks und Swagger-Dokumentation." url: "https://taphome.com/de/docs/expose-devices/taphome-api/" language: de lastmod: 2026-11-06 generator: hugo ai: topics: ["rest-api","api-integration","device-control","authentication","webhook","smart-home-api"] questions: ["Wo finde ich meinen TapHome API-Token in der App?","Wie authentifiziere ich Anfragen an die TapHome API?","Was ist die Basis-URL für die TapHome Cloud API?","Wie erhalte ich alle Gerätewerte in einer einzigen API-Anfrage?","Wie richte ich Webhook-Benachrichtigungen für Geräteänderungen ein?","Welche Core-Firmware-Version ist für die lokale Netzwerk-API erforderlich?","Welche Ratenlimits gelten für den TapHome API setDeviceValue-Endpunkt?","Funktioniert der Webhook ohne Cloud-Zugriff, nur über das lokale Netzwerk?"] --- # TapHome API Integrieren Sie TapHome-Geräte in Anwendungen über HTTP und JSON mit der TapHome-API. Unterstützung von Bearer-Authentifizierung, lokalem Netzwerk, Webhooks und Swagger-Schnittstelle. Zuletzt aktualisiert: 2026-11-06 Die TapHome API ist eine HTTP-Schnittstelle mit JSON-Antworten, über die eine Anwendung eines Drittanbieters die Werte von TapHome-Geräten lesen und ändern kann. Sie arbeitet mit den Geräten, die Sie in der TapHome-App freigeben, und bietet Endpunkte zum Auffinden der Geräte, zum Lesen und zum Setzen von Werten sowie einen Webhook, der Zustandsänderungen an eine von Ihnen festgelegte URL sendet. Sie benötigen ein Zugriffstoken, das Sie in der TapHome-App unter **Einstellungen → Geräte freigeben → TapHome API** erzeugen und im Authorization-Header jeder Anfrage mitsenden. Das Ergebnis: Eine externe Anwendung kann die freigegebenen Geräte über `https://api.taphome.com/api/TapHomeApi/v1/` oder, sofern der Core dies unterstützt, über das lokale Netzwerk überwachen und steuern. ## Überblick Die TapHome API ermöglicht die Integration von TapHome-Geräten in Anwendungen von Drittanbietern über HTTP-Anfragen und JSON-Antworten. Das System ist unter `https://api.taphome.com/api/TapHomeApi/v1/` erreichbar. Wichtige Merkmale sind: - HTTP-basierter Ressourcenzugriff mit passenden Statuscodes - Standard-Swagger-Dokumentation verfügbar unter `https://api.taphome.com/api/doc` - UTF-8-kodierte JSON-Antworten - API-Unterstützung im lokalen Netzwerk (Core 2021.3 oder neuer) über HTTP ohne Swagger UI **Vorteil des lokalen Netzwerks**: Direkter LAN/VPN-Zugriff reduziert Latenz und eliminiert die Abhängigkeit vom Internet. Core-Einheiten erfordern eine feste IP- oder mDNS-Konfiguration. **Sicherheitshinweis**: Die lokale Netzwerk-API und der Webhook laufen über unverschlüsseltes HTTP und setzen voraus, dass das lokale Netzwerk vertrauenswürdig ist. An gemeinsam genutzten oder mandantenfähigen Standorten — zum Beispiel in Hotels oder Büros mit Gäste-Wi-Fi — platzieren Sie den Core in einem dedizierten Netzwerksegment, das vom Gästenetzwerk getrennt ist. Siehe [Netzwerkarchitektur](https://taphome.com/de/docs/configuration/network-architecture/#local-connection). ## Authentifizierung Die TapHome API verwendet eine benutzerdefinierte HTTP-Authentifizierung mittels Bearer-Token (nicht Benutzername/Passwort). ### Header-Format ```http Authorization: TapHome {token} ``` ### Beispielanfrage ```http GET /api/TapHomeApi/v1/location HTTP/1.1 Host: api.taphome.com Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32 ``` ### cURL-Beispiel ```bash curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://api.taphome.com/api/TapHomeApi/v1/location" ``` ### Token-Verwaltung Token in der TapHome-App finden: **Einstellungen → Geräte freigeben → TapHome API** Verwenden Sie das Kontextmenü (drei Punkte), um neue Zugriffstoken zu erzeugen. Das Erzeugen neuer Token macht vorherige Token ungültig. Eine Alternative über Abfrageparameter ist nur für GET-Aufrufe verfügbar (Sicherheitswarnung: Veröffentlichen Sie keine URLs mit Token). Bei kompromittierten Token ist eine sofortige Neuerstellung erforderlich; es ist immer nur ein Token gleichzeitig aktiv. ## API-Referenz ### Standortinformationen abrufen Ruft Standortmetadaten der Steuereinheit ab und validiert den Verbindungsstatus. **Variante 1** ```http GET /api/TapHomeApi/v1/location ``` **Variante 2** ```http POST /api/TapHomeApi/v1/location ``` **Parameter**: Keine **Antwort**: ```json { "locationId": "53e14fbd-c9d1-4615-b994-8d6ec8834e7b", "locationName": "Test Location", "timestamp": 855000000000 } ``` **HTTP-Statusfehler**: - 401 Nicht autorisiert - 404 Nicht gefunden (Standort von der Cloud getrennt) - 405 Methode nicht erlaubt - 500 Interner Serverfehler ### Geräte entdecken Ruft freigegebene Geräte und deren unterstützte Werttypen ab, einschließlich schreibgeschützter Eigenschaften wie dem Gerätestatus. **Variante 1** ```http GET /api/TapHomeApi/v1/discovery ``` **Variante 2** ```http POST /api/TapHomeApi/v1/discovery ``` **Parameter**: Keine **Antwort**: ```json { "devices": [ { "deviceId": 1, "type": "VirtualAnalogOutput", "name": "My AO", "description": "My AO Description", "supportedValues": [ { "valueTypeId": 7, "valueTypeName": "DeviceStatus" }, { "valueTypeId": 42, "valueTypeName": "AnalogOutputValue" }, { "valueTypeId": 48, "valueTypeName": "SwitchState" }, { "valueTypeId": 67, "valueTypeName": "AnalogOutputDesiredValue" } ] }, { "deviceId": 2, "type": "VirtualBlindGroup", "name": "My Blind Group", "description": "My Blind Group Description", "supportedValues": [ { "valueTypeId": 7, "valueTypeName": "DeviceStatus" }, { "valueTypeId": 10, "valueTypeName": "BlindsSlope" }, { "valueTypeId": 46, "valueTypeName": "BlindsLevel" } ] } ], "timestamp": 855000000000 } ``` **HTTP-Statusfehler**: - 401 Nicht autorisiert - 404 Nicht gefunden (Standort von der Cloud getrennt) - 405 Methode nicht erlaubt - 500 Interner Serverfehler ### Gerätewert abrufen Ruft alle aktuellen Werte eines angegebenen Geräts ab, einschließlich Typ-IDs und Namen. Werte sind numerisch (Double-Typ). Einige Eigenschaften sind schreibgeschützt. **Variante 1** ```http GET /api/CloudApi/v1/getDeviceValue/{deviceId} ``` **Variante 2** ```http POST /api/CloudApi/v1/getDeviceValue ``` **Parameter**: Geräte-ID im URL-Pfad oder JSON-Body **Antwort**: ```json { "deviceId": 1, "values": [ { "valueTypeId": 7, "valueTypeName": "DeviceStatus", "value": 0 }, { "valueTypeId": 22, "valueTypeName": "OperationMode", "value": 0 }, { "valueTypeId": 23, "valueTypeName": "ManualTimeout", "value": 0 }, { "valueTypeId": 42, "valueTypeName": "AnalogOutputValue", "value": 1 }, { "valueTypeId": 48, "valueTypeName": "SwitchState", "value": 1 }, { "valueTypeId": 67, "valueTypeName": "AnalogOutputDesiredValue", "value": 1 } ], "timestamp": 855000000000 } ``` **HTTP-Statusfehler**: - 401 Nicht autorisiert - 403 Verboten (Gerät nicht freigegeben) - 404 Nicht gefunden (Standort von der Cloud getrennt) - 405 Methode nicht erlaubt - 500 Interner Serverfehler ### Werte mehrerer Geräte abrufen Ruft alle aktuellen Werte mehrerer Geräte gleichzeitig ab. Reduziert den Bandbreitenverbrauch gegenüber einzelnen Anfragen. Erfordert Core 2021.3 oder neuer. ```http POST /api/CloudApi/v1/getMultipleDevicesValues ``` **Parameter**: ```json { "devices": [ { "deviceId": 1, "valueTypeId": 7 }, { "deviceId": 2 } ], "timestamp": 855000000000 } ``` **Antwort**: ```json { "devices": [ { "deviceId": 1, "values": [ { "valueTypeId": 7, "valueTypeName": "DeviceStatus", "value": 0 } ] }, { "deviceId": 2, "values": [ { "valueTypeId": 7, "valueTypeName": "DeviceStatus", "value": 0 }, { "valueTypeId": 10, "valueTypeName": "BlindsSlope", "value": 1.0 }, { "valueTypeId": 46, "valueTypeName": "BlindsLevel", "value": 0.0 } ] } ], "timestamp": 855000000000 } ``` **HTTP-Statusfehler**: - 401 Nicht autorisiert - 403 Verboten (Gerät nicht freigegeben) - 404 Nicht gefunden (Standort von der Cloud getrennt) - 405 Methode nicht erlaubt - 500 Interner Serverfehler ### Alle Werte aller Geräte abrufen Ruft vollständige Zustandsinformationen aller freigegebenen Geräte in einer einzigen Anfrage ab. Erfordert Core 2021.3 oder neuer. **Variante 1** ```http GET /api/CloudApi/v1/getAllDevicesValues ``` **Variante 2** ```http POST /api/CloudApi/v1/getAllDevicesValues ``` **Antwort**: ```json { "devices": [ { "deviceId": 1, "values": [ { "valueTypeId": 7, "valueTypeName": "DeviceStatus", "value": 0 }, { "valueTypeId": 42, "valueTypeName": "AnalogOutputValue", "value": 1 }, { "valueTypeId": 48, "valueTypeName": "SwitchState", "value": 1 }, { "valueTypeId": 67, "valueTypeName": "AnalogOutputDesiredValue", "value": 1 } ] }, { "deviceId": 2, "values": [ { "valueTypeId": 7, "valueTypeName": "DeviceStatus", "value": 0 }, { "valueTypeId": 10, "valueTypeName": "BlindsSlope", "value": 1.0 }, { "valueTypeId": 46, "valueTypeName": "BlindsLevel", "value": 0.0 } ] } ], "timestamp": 855000000000 } ``` **HTTP-Statusfehler**: - 401 Nicht autorisiert - 403 Verboten (Gerät nicht freigegeben) - 404 Nicht gefunden (Standort von der Cloud getrennt) - 405 Methode nicht erlaubt - 500 Interner Serverfehler ### Einzelnen Gerätewert abrufen Ruft einen einzelnen Gerätewert ab, ohne JSON-Verarbeitung. Ideal für einfache Implementierungen. Die numerische Antwort (Double) wird als Zeichenkette mit Dezimalpunktnotation formatiert. ```http GET /api/CloudApi/v1/getOneDeviceValue/{deviceId}?valueTypeId={valueTypeId}&token={theToken} ``` **Parameter**: Geräte-ID im Pfad, Typ-ID des Werts und Token in der Abfragezeichenfolge **Antwort**: ```text 1.27 ``` Unbekannte Werte liefern `NaN`. Häufige Anfragen (unter 500 ms) können zwischengespeicherte Daten liefern. **HTTP-Statusfehler**: - 401 Nicht autorisiert - 403 Verboten (Gerät nicht freigegeben) - 404 Nicht gefunden (Standort von der Cloud getrennt) - 405 Methode nicht erlaubt - 500 Interner Serverfehler ### Gerätewert setzen Ändert einen oder mehrere Gerätewerte anhand des Typ-Identifiers. Nicht angegebene Werte bleiben unverändert. Numerischer Typ (Double). Häufige Änderungen (Intervalle unter 500 ms) erzeugen eine HTTP-503-Antwort. **Variante 1** ```http GET /api/TapHomeApi/v1/setDeviceValue/{deviceId}?valueTypeId={valueTypeId1}&value={value1}&valueTypeId2={valueTypeId2}&value2={value2}&token={theToken} ``` Unterstützt bis zu drei gleichzeitige Wertzuweisungen. **Variante 2** ```http POST /api/TapHomeApi/v1/setDeviceValue ``` **Parameter**: ```json { "deviceId": 2, "values": [ { "valueTypeId": 46, "value": 0.1 }, { "valueTypeId": 10, "value": 0.2 } ] } ``` **Antwort**: ```json { "deviceId": 2, "valuesChanged": [ { "typeId": 46, "result": "changed" }, { "typeId": 10, "result": "notchanged" }, { "typeId": 7, "result": "failed" } ], "timestamp": 855000000000 } ``` **HTTP-Statusfehler**: - 401 Nicht autorisiert - 403 Verboten (Gerät nicht freigegeben) - 404 Nicht gefunden (Standort von der Cloud getrennt) - 405 Methode nicht erlaubt - 500 Interner Serverfehler - 503 Service Unavailable (zu hohe Set-Value-Frequenz; später erneut versuchen) ## Webhook Die Webhook-Funktionalität liefert freigegebene Gerätestatusänderungen per HTTP POST an eine konfigurierte URL innerhalb von LAN- oder Internetumgebungen. Sie ermöglicht eine effizientere Synchronisierung im Vergleich zu periodischem Polling. **Direkt gesendet, nicht über die Cloud**: Der Webhook ist ein *ausgehender* HTTP POST, den der Core direkt an die konfigurierte URL sendet — die Nutzdaten durchlaufen niemals die TapHome Cloud-Server. Wenn das Ziel im selben lokalen Netzwerk läuft, wird der Webhook lokal über das LAN zugestellt, ohne Umweg über das Internet. Die Schalter **Cloud-Zugriff** und **Lokaler Zugriff** auf der Seite Geräte freigeben steuern nur *eingehende* API-Aufrufe an den Core; sie schalten den Webhook nicht ab. **Drosselung**: Änderungen werden gebündelt und frühestens nach etwa 350 ms gesendet. Bei schnellen Wertübergängen wird nur die neueste Änderung gesendet; frühere Zwischenwerte werden verworfen. Fehlgeschlagene Übertragungen werden nicht wiederholt. **Konfiguration**: Die TapHome-App unterstützt drei benutzerdefinierte HTTP-Anforderungs-Header im Format „Key: Value“. **Datenstruktur**: Identisch mit dem Antwortformat des Endpunkts `getMultipleDevicesValues`.