TapHome API

TapHome API umožňuje integráciu smart zariadení do aplikácií tretích strán, podporuje autentifikáciu, získavanie stavov a webhook notifikácie.

Prehľad

TapHome API umožňuje integráciu zariadení TapHome do aplikácií tretích strán prostredníctvom HTTP požiadaviek a JSON odpovedí. Systém funguje cez https://api.taphome.com/api/TapHomeApi/v1/.

Kľúčové charakteristiky zahŕňajú:

prístup k zdrojom na báze HTTP s vhodnými stavovými kódmi
štandardnú Swagger dokumentáciu k dispozícii na https://api.taphome.com/api/doc
JSON odpovede kódované vo formáte UTF-8
podporu API pre miestnu sieť (Core 2021.3+) cez HTTP bez Swagger UI

Výhoda miestnej siete: Priamy prístup cez LAN/VPN znižuje latenciu a eliminuje závislosť na internete. Core jednotky vyžadujú pevnú IP adresu alebo konfiguráciu mDNS.

Bezpečnostná poznámka: API lokálnej siete a webhook bežia cez nešifrované HTTP a predpokladajú, že lokálna sieť je dôveryhodná. Na zdieľaných lokalitách alebo lokalitách pre viacerých nájomníkov — napríklad v hoteloch alebo kanceláriách s hosťovskou Wi-Fi — umiestnite Core do vyhradeného sieťového segmentu oddeleného od hosťovskej siete. Pozrite si Architektúra siete.

Autentifikácia

TapHome API používa vlastnú HTTP autentifikáciu pomocou bearer tokenov (nie prihlasovacie meno a heslo).

Header Format

1
Authorization: TapHome {token}

Example Request

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

cURL Example

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

Token Management

Tokeny nájdete v aplikácii TapHome: Nastavenia → Zverejniť zariadenia → TapHome API.

Pomocou kontextového menu (tri bodky) môžete generovať nové prístupové tokeny. Vygenerovanie nových tokenov zneplatní všetky predchádzajúce.

Alternatívny parameter dotazu je k dispozícii len pre GET volania (bezpečnostné upozornenie: vyhýbajte sa zdieľaniu URL obsahujúcich tokeny).

Tokeny, ktoré boli kompromitované, je potrebné okamžite zrušiť a vygenerovať nanovo; naraz je aktívny len jeden token.

Referenčná dokumentácia API

Získanie informácií o lokalite

Získa metadáta lokality riadiacej jednotky a overí stav pripojenia.

Variant 1

1
GET /api/TapHomeApi/v1/location

Variant 2

1
POST /api/TapHomeApi/v1/location

Parametre: Žiadne

Odpoveď:

1
2
3
4
5
{
  "locationId": "53e14fbd-c9d1-4615-b994-8d6ec8834e7b",
  "locationName": "Test Location",
  "timestamp": 855000000000
}

HTTP Status Errors:

401 Neoprávnený prístup
404 Nenájdené (lokalita odpojená od cloudu)
405 Metóda nie je povolená
500 Interná chyba servera

Objav zariadení

Načíta vystavené zariadenia a ich podporované typy hodnôt, vrátane čitateľných vlastností ako stav zariadenia.

Variant 1

1
GET /api/TapHomeApi/v1/discovery

Variant 2

1
POST /api/TapHomeApi/v1/discovery

Parametre: Žiadne

Odpoveď:

 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 Status Errors:

401 Neoprávnený prístup
404 Nenájdené (lokalita odpojená od cloudu)
405 Metóda nie je povolená
500 Interná chyba servera

Získanie hodnoty zariadenia

Získa všetky aktuálne hodnoty pre špecifikované zariadenie, vrátane identifikátorov typov a ich názvov. Hodnoty sú číselné (double). Niektoré vlastnosti sú len na čítanie.

Variant 1

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

Variant 2

1
POST /api/CloudApi/v1/getDeviceValue

Parametre: ID zariadenia v URL ceste alebo v tele JSON

Odpoveď:

 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 Status Errors:

401 Neoprávnený prístup
403 Zakázaný prístup (zariadenie nie je vystavené)
404 Nenájdené (lokalita odpojená od cloudu)
405 Metóda nie je povolená
500 Interná chyba servera

Získanie hodnôt viacerých zariadení

Získa všetky aktuálne hodnoty pre viaceré zariadenia súčasne. Znižuje dátový prenos oproti individuálnym dopytom. Vyžaduje Core 2021.3 alebo novší.

1
POST /api/CloudApi/v1/getMultipleDevicesValues

Parametre:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
 "devices": [
    {
      "deviceId": 1,
      "valueTypeId": 7
    },
    {
      "deviceId": 2
    }
  ],
  "timestamp": 855000000000
}

Odpoveď:

 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 Status Errors:

401 Neoprávnený prístup
403 Zakázaný prístup (zariadenie nie je vystavené)
404 Nenájdené (lokalita odpojená od cloudu)
405 Metóda nie je povolená
500 Interná chyba servera

Získanie všetkých hodnôt všetkých zariadení

Získa úplný stav všetkých vystavených zariadení v jednej požiadavke. Vyžaduje Core 2021.3 alebo novší.

Variant 1

1
GET /api/CloudApi/v1/getAllDevicesValues

Variant 2

1
POST /api/CloudApi/v1/getAllDevicesValues

Odpoveď:

 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 Status Errors:

401 Neoprávnený prístup
403 Zakázaný prístup (zariadenie nie je vystavené)
404 Nenájdené (lokalita odpojená od cloudu)
405 Metóda nie je povolená
500 Interná chyba servera

Získanie jednej hodnoty zariadenia

Získa jednu hodnotu zariadenia bez potreby spracovania JSON. Ideálne pre jednoduché implementácie. Číselná odpoveď (double) formátovaná ako reťazec s desatinnou bodkou.

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

Parametre: ID zariadenia v ceste, ID typu hodnoty a token v dotazovacom reťazci

Odpoveď:

1
1.27

Neznáme hodnoty vracajú NaN. Časté požiadavky (s intervalom pod 500 ms) môžu vrátiť dáta z cache.

HTTP Status Errors:

401 Neoprávnený prístup
403 Zakázaný prístup (zariadenie nie je vystavené)
404 Nenájdené (lokalita odpojená od cloudu)
405 Metóda nie je povolená
500 Interná chyba servera

Nastavenie hodnoty zariadenia

Upraví jednu alebo viacero hodnôt zariadenia podľa identifikátora typu. Nešpecifikované hodnoty zostávajú nezmenené. Číselný typ (double).

Časté úpravy (s intervalom pod 500 ms) vyvolajú odpoveď HTTP 503.

Variant 1

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

Podporuje až tri súčasné priradenia hodnôt.

Variant 2

1
POST /api/TapHomeApi/v1/setDeviceValue

Parametre:

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

Odpoveď:

 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 Status Errors:

401 Neoprávnený prístup
403 Zakázaný prístup (zariadenie nie je vystavené)
404 Nenájdené (lokalita odpojená od cloudu)
405 Metóda nie je povolená
500 Interná chyba servera
503 Služba nedostupná (nadmerná frekvencia nastavovania hodnôt; skúste to znova neskôr)

Webhook

Webhook funkčnosť doručuje zmeny stavu vystavených zariadení prostredníctvom HTTP POST na nakonfigurovanú URL adresu v prostredí LAN alebo internetu. Umožňuje efektívnu synchronizáciu v porovnaní s periodickým dotazovaním.

Odosielané priamo, nie cez cloud: Webhook je odchádzajúci HTTP POST, ktorý Core posiela priamo na nakonfigurovanú URL — dáta nikdy neprechádzajú cez cloudové servery TapHome. Ak cieľ beží v rovnakej lokálnej sieti, webhook je doručený lokálne cez LAN, bez cesty cez internet. Prepínače Cloudový prístup a Lokálny prístup na stránke Zverejniť zariadenia riadia iba prichádzajúce volania API do Core; nevypínajú webhook.

Obmedzovanie frekvencie: Zmeny sú zoskupované do dávok a odosielané najskôr po približne 350 ms. Pri rýchlych zmenách hodnôt sa odošle iba najnovšia zmena; predchádzajúce priebežné hodnoty sa zahodia. Zlyhané prenosy sa neopakujú.

Konfigurácia: Aplikácia TapHome vyžaduje tri vlastné hlavičky HTTP vo formáte „kľúč: hodnota“.

Dátová štruktúra: Identická s formátom odpovede endpointu getMultipleDevicesValues.

TapHome API

Prehľad#

Autentifikácia#

Header Format#

Example Request#

cURL Example#

Token Management#

Referenčná dokumentácia API#

Získanie informácií o lokalite#

Objav zariadení#

Získanie hodnoty zariadenia#

Získanie hodnôt viacerých zariadení#

Získanie všetkých hodnôt všetkých zariadení#

Získanie jednej hodnoty zariadenia#

Nastavenie hodnoty zariadenia#

Webhook#

Prehľad

Autentifikácia

Header Format

Example Request

cURL Example

Token Management

Referenčná dokumentácia API

Získanie informácií o lokalite

Objav zariadení

Získanie hodnoty zariadenia

Získanie hodnôt viacerých zariadení

Získanie všetkých hodnôt všetkých zariadení

Získanie jednej hodnoty zariadenia

Nastavenie hodnoty zariadenia

Webhook