Vystaviť zariadenia

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.

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.

Rýchlostné obmedzenie (throttling): Aktivuje sa pri maximálnej frekvencii 300 ms. Pri rýchlych zmenách hodnôt sa odošle iba posledná zmena; predchádzajúce medzivzorky hodnôt 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.