TapHome API

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.

Authentifizierung#

Die TapHome API verwendet eine benutzerdefinierte HTTP-Authentifizierung mittels Bearer-Token (nicht Benutzername/Passwort).

Header-Format#

1

Authorization: TapHome {token}

Beispielanfrage#

1
2
3

GET /api/TapHomeApi/v1/location HTTP/1.1
Host: api.taphome.com
Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32

cURL-Beispiel#

1

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

1

GET /api/TapHomeApi/v1/location

Variante 2

1

POST /api/TapHomeApi/v1/location

Parameter: Keine

Antwort:

1
2
3
4
5

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

1

GET /api/TapHomeApi/v1/discovery

Variante 2

1

POST /api/TapHomeApi/v1/discovery

Parameter: Keine

Antwort:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

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

1

GET /api/CloudApi/v1/getDeviceValue/{deviceId}

Variante 2

1

POST /api/CloudApi/v1/getDeviceValue

Parameter: Geräte-ID im URL-Pfad oder JSON-Body

Antwort:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

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

1

POST /api/CloudApi/v1/getMultipleDevicesValues

Parameter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
 "devices": [
    {
      "deviceId": 1,
      "valueTypeId": 7
    },
    {
      "deviceId": 2
    }
  ],
  "timestamp": 855000000000
}

Antwort:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

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

1

GET /api/CloudApi/v1/getAllDevicesValues

Variante 2

1

POST /api/CloudApi/v1/getAllDevicesValues

Antwort:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

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

1

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:

1

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

1

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

1

POST /api/TapHomeApi/v1/setDeviceValue

Parameter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "deviceId": 2,
  "values": [
    {
      "valueTypeId": 46,
      "value": 0.1
    },
    {
      "valueTypeId": 10,
      "value": 0.2
    }
  ]
}

Antwort:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

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