Zpřístupnit zařízení

TapHome API

Integrace zařízení přes TapHome API s podporou JSON odpovědí, autentizace prostřednictvím Bearer tokenů a webhooků pro rychlou synchronizaci.

Přehled

TapHome API umožňuje integraci zařízení TapHome do aplikací třetích stran prostřednictvím HTTP požadavků a JSON odpovědí. Systém běží na adrese https://api.taphome.com/api/TapHomeApi/v1/

Klíčové charakteristiky zahrnují:

  • Přístup k prostředkům založený na HTTP s odpovídajícími stavovými kódy
  • Standardní dokumentace Swagger je k dispozici na https://api.taphome.com/api/doc
  • JSON odpovědi kódované v UTF-8
  • Podpora API v místní síti (Core 2021.3+) přes HTTP bez Swagger UI

Výhoda místní sítě: Přímý přístup přes LAN/VPN snižuje latenci a eliminuje závislost na internetu. Jádrové jednotky vyžadují pevnou IP adresu nebo konfiguraci mDNS.

Autentizace

TapHome API používá vlastní HTTP autentizaci pomocí bearer tokenů (namísto přihlašovacího jména a hesla).

Formát hlavičky

1

Authorization: TapHome {token}

Příklad požadavku

1
2
3

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

Příklad cURL

1

curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://api.taphome.com/api/TapHomeApi/v1/location"

Správa tokenů

Tokeny najdete v aplikaci TapHome: Nastavení → Zpřístupnit zařízení → TapHome API

Pomocí kontextové nabídky (tři tečky) vygenerujete nové přístupové tokeny. Vygenerování nových tokenů zneplatní předchozí. Alternativní použití dotazovacího parametru je k dispozici pouze pro volání GET (bezpečnostní upozornění: vyvarujte se sdílení URL obsahujících tokeny).

Tokeny, které byly kompromitovány, je nutné okamžitě regenerovat; současně může být aktivní pouze jeden token.

Referenční dokumentace API

Získat informace o lokalitě

Získá metadata lokality řídicí jednotky a ověří stav připojení.

Varianta 1

1

GET /api/TapHomeApi/v1/location

Varianta 2

1

POST /api/TapHomeApi/v1/location

Parametry: Žádné

Odpověď:

1
2
3
4
5

{
  "locationId": "53e14fbd-c9d1-4615-b994-8d6ec8834e7b",
  "locationName": "Test Location",
  "timestamp": 855000000000
}

Chybové stavy HTTP:

  • 401 Unauthorized
  • 404 Not Found (lokalita odpojena od cloudu)
  • 405 Method Not Allowed
  • 500 Internal Server Error

Zjištění zařízení

Zobrazí vystavená zařízení a jejich podporované typy hodnot, včetně vlastností jen pro čtení, jako je Stav zařízení.

Varianta 1

1

GET /api/TapHomeApi/v1/discovery

Varianta 2

1

POST /api/TapHomeApi/v1/discovery

Parametry: Žádné

Odpověď:

 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
}

Chybové stavy HTTP:

  • 401 Unauthorized
  • 404 Not Found (lokalita odpojena od cloudu)
  • 405 Method Not Allowed
  • 500 Internal Server Error

Získat hodnotu zařízení

Získá všechna aktuální data pro zadané zařízení, včetně identifikátorů typů a názvů. Hodnoty jsou číselné (typu double). Některé vlastnosti jsou pouze pro čtení.

Časté dotazy (v intervalu pod 500 ms) mohou vracet kešované hodnoty; pro porovnání rovnosti porovnávejte pouze časové razítko.

Varianta 1

1

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

Varianta 2

1

POST /api/CloudApi/v1/getDeviceValue

Parametry: ID zařízení v cestě URL nebo v JSON těle

Odpověď:

 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
}

Chybové stavy HTTP:

  • 401 Unauthorized
  • 403 Forbidden (zařízení není vystaveno)
  • 404 Not Found (lokalita odpojena od cloudu)
  • 405 Method Not Allowed
  • 500 Internal Server Error

Získat hodnoty více zařízení

Získá současně všechny aktuální hodnoty pro více zařízení. Snižuje spotřebu šířky pásma oproti jednotlivým požadavkům. Vyžaduje Core 2021.3 nebo novější.

1

POST /api/CloudApi/v1/getMultipleDevicesValues

Parametry:

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

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

Odpověď:

 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
}

Chybové stavy HTTP:

  • 401 Unauthorized
  • 403 Forbidden (zařízení není vystaveno)
  • 404 Not Found (lokalita odpojena od cloudu)
  • 405 Method Not Allowed
  • 500 Internal Server Error

Získat všechny hodnoty všech zařízení

Získá kompletní stav všech vystavených zařízení v jednom požadavku. Vyžaduje Core 2021.3 nebo novější.

Varianta 1

1

GET /api/CloudApi/v1/getAllDevicesValues

Varianta 2

1

POST /api/CloudApi/v1/getAllDevicesValues

Odpověď:

 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
}

Chybové stavy HTTP:

  • 401 Unauthorized
  • 403 Forbidden (zařízení není vystaveno)
  • 404 Not Found (lokalita odpojena od cloudu)
  • 405 Method Not Allowed
  • 500 Internal Server Error

Získat hodnotu jednoho zařízení

Získá jednu hodnotu zařízení bez nutnosti zpracování JSON. Vhodné pro jednoduché implementace. Číselná odpověď (double) je formátována jako řetězec s desetinnou tečkou.

1

GET /api/CloudApi/v1/getOneDeviceValue/{deviceId}?valueTypeId={valueTypeId}&token={theToken}

Parametry: ID zařízení v cestě, ID typu hodnoty a token v dotazu

Odpověď:

1

1.27

Neznámé hodnoty vrací NaN. Časté dotazy (pod 500 ms) mohou vracet uložená data.

Chybové stavy HTTP:

  • 401 Unauthorized
  • 403 Forbidden (zařízení není vystaveno)
  • 404 Not Found (lokalita odpojena od cloudu)
  • 405 Method Not Allowed
  • 500 Internal Server Error

Nastavit hodnotu zařízení

Upraví jednu nebo více hodnot zařízení podle identifikátoru typu. Nedefinované hodnoty zůstávají nezměněny. Číselný typ (double).

Časté úpravy (v intervalu pod 500 ms) vyvolají odpověď HTTP 503.

Varianta 1

1

GET /api/TapHomeApi/v1/setDeviceValue/{deviceId}?valueTypeId={valueTypeId1}&value={value1}&valueTypeId2={valueTypeId2}&value2={value2}&token={theToken}

Podporuje až tři současná přiřazení hodnot.

Varianta 2

1

POST /api/TapHomeApi/v1/setDeviceValue

Parametry:

 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
    }
  ]
}

Odpověď:

 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
}

Chybové stavy HTTP:

  • 401 Unauthorized
  • 403 Forbidden (zařízení není vystaveno)
  • 404 Not Found (lokalita odpojena od cloudu)
  • 405 Method Not Allowed
  • 500 Internal Server Error
  • 503 Service Unavailable (nadměrně časté nastavování hodnot; zkuste to později)

Webhook

Funkcionalita webhooku doručuje změny stavu vystavených zařízení prostřednictvím HTTP POST na nakonfigurovanou URL v prostředích LAN nebo internetu. Umožňuje efektivní synchronizaci oproti periodickému dotazování.

Omezení rychlosti (throttling): Aktivuje se při minimálním intervalu 300 ms. Při rychlých změnách hodnot je odeslána pouze poslední změna; předchozí mezistavové hodnoty jsou zahazovány. Neúspěšné přenosy se neopakují.

Konfigurace: Aplikace TapHome podporuje tři vlastní HTTP hlavičky ve formátu “klíč: hodnota”.

Datová struktura: Identická s formátem odpovědi koncového bodu getMultipleDevicesValues.