TapHome API

Pomoću TapHome API-ja uređaje TapHome možete povezati s bilo kojom aplikacijom treće strane, na primjer s glasovnim upravljanjem Apple Siri.

Pregled

TapHome API omogućuje povezivanje uređaja TapHome s aplikacijama trećih strana putem zahtjeva preko protokola HTTP i odgovora u formatu JSON. Sustav radi putem adrese https://api.taphome.com/api/TapHomeApi/v1/.

Glavne značajke:

pristup resursima putem HTTP-a s odgovarajućim statusnim kodovima
standardna dokumentacija Swagger dostupna na adresi https://api.taphome.com/api/doc
odgovori u formatu JSON s kodiranjem UTF-8
podrška za API u lokalnoj mreži (Core 2021.3+) putem HTTP-a, bez sučelja Swagger UI

Prednost lokalne mreže: izravan pristup preko LAN-a/VPN-a smanjuje kašnjenje i uklanja ovisnost o internetu. Centralne jedinice Core trebaju fiksnu IP adresu ili konfiguraciju mDNS.

Sigurnosna napomena: API u lokalnoj mreži i webhook rade preko nešifriranog HTTP-a i pretpostavljaju da je lokalna mreža pouzdana. Na zajedničkim lokacijama ili lokacijama s više korisnika, na primjer u hotelima ili uredima s Wi-Fi mrežom za goste, centralnu jedinicu Core postavite u zaseban mrežni segment odvojen od mreže za goste. Pogledajte Mrežnu arhitekturu.

Autentifikacija

TapHome API koristi vlastitu HTTP autentifikaciju s bearer tokenima (bez korisničkog imena i lozinke).

Format zaglavlja

1
Authorization: TapHome {token}

Primjer zahtjeva

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

Primjer za cURL

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

Upravljanje tokenima

Tokene ćete pronaći u aplikaciji TapHome: Postavke → Izložite uređaje → TapHome API

Nove pristupne tokene generirajte pomoću kontekstnog izbornika (tri točke). Generiranjem novog tokena prethodni prestaju vrijediti. Kao alternativa, token se može poslati kao parametar upita, ali samo kod poziva GET (sigurnosno upozorenje: ne dijelite URL-ove koji sadrže token).

Ugroženi token odmah treba ponovno generirati. Istodobno je aktivan samo jedan token.

Referentna dokumentacija API-ja

Dohvaćanje informacija o lokaciji

Dohvaća metapodatke o lokaciji centralne jedinice i provjerava stanje povezanosti.

Varijanta 1

1
GET /api/TapHomeApi/v1/location

Varijanta 2

1
POST /api/TapHomeApi/v1/location

Parametri: nema

Odgovor:

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

Pogreške (HTTP statusni kodovi):

401 Neovlašten pristup
404 Nije pronađeno (lokacija nije povezana s oblakom)
405 Metoda nije dopuštena
500 Interna pogreška poslužitelja

Otkrivanje uređaja

Dohvaća izložene uređaje i vrste vrijednosti koje podržavaju, uključujući svojstva samo za čitanje kao što je stanje uređaja (Device Status).

Varijanta 1

1
GET /api/TapHomeApi/v1/discovery

Varijanta 2

1
POST /api/TapHomeApi/v1/discovery

Parametri: nema

Odgovor:

 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
}

Pogreške (HTTP statusni kodovi):

401 Neovlašten pristup
404 Nije pronađeno (lokacija nije povezana s oblakom)
405 Metoda nije dopuštena
500 Interna pogreška poslužitelja

Dohvaćanje vrijednosti uređaja

Dohvaća sve trenutačne vrijednosti navedenog uređaja, uključujući ID-ove i nazive vrsta vrijednosti. Vrijednosti su brojčane (tip double). Neka su svojstva samo za čitanje.

Česti zahtjevi (u razmacima kraćim od 500 ms) mogu vratiti vrijednosti iz predmemorije. Vremenske oznake uspoređujte samo na jednakost.

Varijanta 1

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

Varijanta 2

1
POST /api/CloudApi/v1/getDeviceValue

Parametri: ID uređaja u putanji URL-a ili u tijelu zahtjeva u formatu JSON

Odgovor:

 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
}

Pogreške (HTTP statusni kodovi):

401 Neovlašten pristup
403 Zabranjeno (uređaj nije izložen)
404 Nije pronađeno (lokacija nije povezana s oblakom)
405 Metoda nije dopuštena
500 Interna pogreška poslužitelja

Dohvaćanje vrijednosti više uređaja

Istodobno dohvaća sve trenutačne vrijednosti više uređaja. U usporedbi s pojedinačnim zahtjevima smanjuje prijenos podataka. Potrebna je verzija firmvera centralne jedinice Core 2021.3 ili novija.

1
POST /api/CloudApi/v1/getMultipleDevicesValues

Parametri:

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

Odgovor:

 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
}

Pogreške (HTTP statusni kodovi):

401 Neovlašten pristup
403 Zabranjeno (uređaj nije izložen)
404 Nije pronađeno (lokacija nije povezana s oblakom)
405 Metoda nije dopuštena
500 Interna pogreška poslužitelja

Dohvaćanje svih vrijednosti svih uređaja

Jednim zahtjevom dohvaća potpune informacije o stanju svih izloženih uređaja. Potrebna je verzija firmvera centralne jedinice Core 2021.3 ili novija.

Varijanta 1

1
GET /api/CloudApi/v1/getAllDevicesValues

Varijanta 2

1
POST /api/CloudApi/v1/getAllDevicesValues

Odgovor:

 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
}

Pogreške (HTTP statusni kodovi):

401 Neovlašten pristup
403 Zabranjeno (uređaj nije izložen)
404 Nije pronađeno (lokacija nije povezana s oblakom)
405 Metoda nije dopuštena
500 Interna pogreška poslužitelja

Dohvaćanje jedne vrijednosti uređaja

Dohvaća jednu vrijednost uređaja bez potrebe za obradom JSON-a. Idealno za jednostavne implementacije. Brojčani odgovor (double) vraća se kao tekst s decimalnom točkom.

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

Parametri: ID uređaja u putanji, ID vrste vrijednosti i token u nizu upita

Odgovor:

1
1.27

Za nepoznate vrijednosti vraća se NaN. Česti zahtjevi (u razmacima kraćim od 500 ms) mogu vratiti podatke iz predmemorije.

Pogreške (HTTP statusni kodovi):

401 Neovlašten pristup
403 Zabranjeno (uređaj nije izložen)
404 Nije pronađeno (lokacija nije povezana s oblakom)
405 Metoda nije dopuštena
500 Interna pogreška poslužitelja

Postavljanje vrijednosti uređaja

Mijenja jednu ili više vrijednosti uređaja prema identifikatoru vrste. Vrijednosti koje nisu navedene ostaju nepromijenjene. Brojčani tip (double).

Česte promjene (u razmacima kraćim od 500 ms) vraćaju odgovor HTTP 503.

Varijanta 1

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

Podržava postavljanje najviše triju vrijednosti istodobno.

Varijanta 2

1
POST /api/TapHomeApi/v1/setDeviceValue

Parametri:

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

Odgovor:

 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
}

Pogreške (HTTP statusni kodovi):

401 Neovlašten pristup
403 Zabranjeno (uređaj nije izložen)
404 Nije pronađeno (lokacija nije povezana s oblakom)
405 Metoda nije dopuštena
500 Interna pogreška poslužitelja
503 Usluga nije dostupna (prečesto postavljanje vrijednosti; pokušajte ponovno kasnije)

Webhook

Funkcija webhook šalje promjene stanja izloženih uređaja zahtjevom HTTP POST na konfigurirani URL u lokalnoj mreži (LAN) ili na internetu. U usporedbi s periodičnim ispitivanjem omogućuje učinkovitiju sinkronizaciju.

Šalje se izravno, ne preko oblaka: webhook je odlazni zahtjev HTTP POST koji centralna jedinica Core šalje izravno na konfigurirani URL. Podaci nikad ne prolaze kroz poslužitelje TapHome u oblaku. Ako je odredište u istoj lokalnoj mreži, webhook se isporučuje lokalno preko LAN-a, bez prolaska kroz internet. Prekidači Pristup u oblaku i Lokalni pristup na stranici Izložite uređaje upravljaju samo dolaznim API pozivima prema centralnoj jedinici Core. Webhook ne isključuju.

Ograničavanje učestalosti: promjene se skupljaju i šalju najranije nakon približno 350 ms. Kod brzih promjena vrijednosti šalje se samo posljednja promjena, a prethodne međuvrijednosti se odbacuju. Neuspjela slanja ne ponavljaju se.

Konfiguracija: aplikacija TapHome podržava tri prilagođena zaglavlja HTTP zahtjeva u formatu „ključ: vrijednost”.

Struktura podataka: ista kao format odgovora krajnje točke getMultipleDevicesValues.

TapHome API

Pregled#

Autentifikacija#

Format zaglavlja#

Primjer zahtjeva#

Primjer za cURL#

Upravljanje tokenima#

Referentna dokumentacija API-ja#

Dohvaćanje informacija o lokaciji#

Otkrivanje uređaja#

Dohvaćanje vrijednosti uređaja#

Dohvaćanje vrijednosti više uređaja#

Dohvaćanje svih vrijednosti svih uređaja#

Dohvaćanje jedne vrijednosti uređaja#

Postavljanje vrijednosti uređaja#

Webhook#

Pregled

Autentifikacija

Format zaglavlja

Primjer zahtjeva

Primjer za cURL

Upravljanje tokenima

Referentna dokumentacija API-ja

Dohvaćanje informacija o lokaciji

Otkrivanje uređaja

Dohvaćanje vrijednosti uređaja

Dohvaćanje vrijednosti više uređaja

Dohvaćanje svih vrijednosti svih uređaja

Dohvaćanje jedne vrijednosti uređaja

Postavljanje vrijednosti uređaja

Webhook