Geräte freigeben

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.

Ü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+) ü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.

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.

Drosselung: Aktiviert bei minimalen Intervallen von 300 ms. Bei schnellen Wertübergängen wird nur die zuletzt gemeldete Änderung gesendet; frühere Zwischenwerte werden verworfen. Fehlgeschlagene Übertragungen werden nicht erneut versucht.

Konfiguration: Die TapHome-App unterstützt drei benutzerdefinierte HTTP-Anforderungs-Header im Format „Key: Value“.

Datenstruktur: Identisch mit dem Antwortformat des Endpunkts getMultipleDevicesValues.