TapHome

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.

Bezpečnostní poznámka: API lokální sítě a webhook běží přes nešifrované HTTP a předpokládají, že lokální síť je důvěryhodná. Ve sdílených nebo vícenájemních lokalitách — například v hotelech nebo kancelářích s Wi-Fi pro hosty — umístěte Core do vyhrazeného síťového segmentu odděleného od sítě pro hosty. Viz Architektura sítě.

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í.

Odesíláno přímo, nikoli přes cloud: Webhook je odchozí HTTP POST, který Core odesílá přímo na nakonfigurovanou URL — přenášená data nikdy neprocházejí přes cloudové servery TapHome. Pokud cíl běží ve stejné lokální síti, webhook je doručen lokálně přes LAN, bez nutnosti komunikace přes internet. Přepínače Cloudový přístup a Lokální přístup na stránce Zpřístupnit zařízení řídí pouze příchozí volání API do Core; nevypínají webhook.

Omezování četnosti: Změny jsou dávkovány a odesílány nejdříve po přibližně 350 ms. Při rychlých změnách hodnot se odesílá pouze nejnovější změna; dřívější mezihodnoty jsou zahozeny. 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.