TapHome API

Prezentare generală#

TapHome API permite integrarea dispozitivelor TapHome în aplicații terțe prin cereri pe protocolul HTTP și răspunsuri JSON. Sistemul funcționează prin https://api.taphome.com/api/TapHomeApi/v1/

Caracteristici principale:

• acces la resurse prin HTTP, cu coduri de stare corespunzătoare
• documentație Swagger standard disponibilă la https://api.taphome.com/api/doc
• răspunsuri JSON codificate în UTF-8
• suport pentru API în rețeaua locală (Core 2021.3+) prin HTTP, fără interfața Swagger

Avantajul rețelei locale: accesul direct prin LAN/VPN reduce latența și elimină dependența de internet. Unitățile Core necesită o adresă IP fixă sau configurare mDNS.

Notă de securitate: API-ul din rețeaua locală și webhook-ul funcționează prin HTTP simplu și presupun că rețeaua locală este de încredere. În clădirile cu rețea partajată sau cu mai mulți utilizatori, de exemplu hoteluri sau birouri cu Wi-Fi pentru oaspeți, amplasați unitatea Core într-un segment de rețea dedicat, separat de rețeaua pentru oaspeți. Consultați Arhitectura rețelei.

Autentificare#

TapHome API folosește o autentificare HTTP proprie, cu tokenuri bearer (nu cu nume de utilizator și parolă).

Formatul antetului#

1

Authorization: TapHome {token}

Exemplu de cerere#

1
2
3

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

Exemplu cURL#

1

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

Gestionarea tokenurilor#

Tokenurile se găsesc în aplicația TapHome: Setări → Expun dispozitive → TapHome API

Folosiți meniul contextual (cele trei puncte) pentru a genera tokenuri de acces noi. Generarea unui token nou invalidează tokenurile anterioare. Alternativa cu parametru de interogare este disponibilă doar pentru apelurile GET (avertisment de securitate: nu partajați URL-uri care conțin tokenuri).

Un token compromis trebuie regenerat imediat; la un moment dat este activ un singur token.

Referința API#

Obținerea informațiilor despre locație#

Returnează metadatele locației unității de control și verifică starea conexiunii.

Varianta 1

1

GET /api/TapHomeApi/v1/location

Varianta 2

1

POST /api/TapHomeApi/v1/location

Parametri: niciunul

Răspuns:

1
2
3
4
5

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

Erori HTTP:

• 401 Unauthorized (neautorizat)
• 404 Not Found (locația este deconectată de la cloud)
• 405 Method Not Allowed (metodă nepermisă)
• 500 Internal Server Error (eroare internă a serverului)

Descoperirea dispozitivelor#

Returnează dispozitivele expuse și tipurile de valori acceptate de acestea, inclusiv proprietățile doar pentru citire, precum Device Status.

Varianta 1

1

GET /api/TapHomeApi/v1/discovery

Varianta 2

1

POST /api/TapHomeApi/v1/discovery

Parametri: niciunul

Răspuns:

 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
}

Erori HTTP:

• 401 Unauthorized (neautorizat)
• 404 Not Found (locația este deconectată de la cloud)
• 405 Method Not Allowed (metodă nepermisă)
• 500 Internal Server Error (eroare internă a serverului)

Obținerea valorilor unui dispozitiv#

Returnează toate valorile actuale ale dispozitivului indicat, inclusiv ID-urile și numele tipurilor. Valorile sunt numerice (tip double). Unele proprietăți sunt doar pentru citire.

Cererile frecvente (la intervale sub 500 ms) pot returna valori din cache; comparați marcajele de timp (timestamp) doar pentru egalitate.

Varianta 1

1

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

Varianta 2

1

POST /api/CloudApi/v1/getDeviceValue

Parametri: ID-ul dispozitivului în calea URL sau în corpul JSON

Răspuns:

 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
}

Erori HTTP:

• 401 Unauthorized (neautorizat)
• 403 Forbidden (dispozitivul nu este expus)
• 404 Not Found (locația este deconectată de la cloud)
• 405 Method Not Allowed (metodă nepermisă)
• 500 Internal Server Error (eroare internă a serverului)

Obținerea valorilor mai multor dispozitive#

Returnează simultan toate valorile actuale ale mai multor dispozitive. Consumă mai puțină lățime de bandă decât cererile individuale. Necesită Core 2021.3 sau mai nou.

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
}

Răspuns:

 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
}

Erori HTTP:

• 401 Unauthorized (neautorizat)
• 403 Forbidden (dispozitivul nu este expus)
• 404 Not Found (locația este deconectată de la cloud)
• 405 Method Not Allowed (metodă nepermisă)
• 500 Internal Server Error (eroare internă a serverului)

Obținerea tuturor valorilor tuturor dispozitivelor#

Returnează într-o singură cerere starea completă a tuturor dispozitivelor expuse. Necesită Core 2021.3 sau mai nou.

Varianta 1

1

GET /api/CloudApi/v1/getAllDevicesValues

Varianta 2

1

POST /api/CloudApi/v1/getAllDevicesValues

Răspuns:

 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
}

Erori HTTP:

• 401 Unauthorized (neautorizat)
• 403 Forbidden (dispozitivul nu este expus)
• 404 Not Found (locația este deconectată de la cloud)
• 405 Method Not Allowed (metodă nepermisă)
• 500 Internal Server Error (eroare internă a serverului)

Obținerea unei singure valori a dispozitivului#

Returnează o singură valoare a dispozitivului, fără a fi necesară procesarea JSON. Ideal pentru implementări simple. Răspunsul numeric (double) este formatat ca șir de caractere, cu punct zecimal.

1

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

Parametri: ID-ul dispozitivului în cale, ID-ul tipului de valoare și tokenul în parametrii de interogare

Răspuns:

1

1.27

Pentru valorile necunoscute se returnează NaN. Cererile frecvente (la intervale sub 500 ms) pot returna date din cache.

Erori HTTP:

• 401 Unauthorized (neautorizat)
• 403 Forbidden (dispozitivul nu este expus)
• 404 Not Found (locația este deconectată de la cloud)
• 405 Method Not Allowed (metodă nepermisă)
• 500 Internal Server Error (eroare internă a serverului)

Setarea valorii dispozitivului#

Modifică una sau mai multe valori ale dispozitivului, după identificatorul tipului. Valorile neindicate rămân neschimbate. Tip numeric (double).

Modificările frecvente (la intervale sub 500 ms) duc la răspunsul HTTP 503.

Varianta 1

1

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

Se pot seta simultan până la trei valori.

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

Răspuns:

 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
}

Erori HTTP:

• 401 Unauthorized (neautorizat)
• 403 Forbidden (dispozitivul nu este expus)
• 404 Not Found (locația este deconectată de la cloud)
• 405 Method Not Allowed (metodă nepermisă)
• 500 Internal Server Error (eroare internă a serverului)
• 503 Service Unavailable (valorile se setează prea des; reîncercați mai târziu)

Webhook#

Funcția webhook trimite modificările de stare ale dispozitivelor expuse prin HTTP POST la un URL configurat, în rețeaua LAN sau pe internet. Permite o sincronizare mai eficientă decât interogarea periodică.

Se trimite direct, nu prin cloud: webhook-ul este un HTTP POST de ieșire, pe care unitatea Core îl trimite direct la URL-ul configurat; datele nu trec niciodată prin serverele cloud TapHome. Dacă destinația funcționează în aceeași rețea locală, webhook-ul se livrează local prin LAN, fără să treacă prin internet. Comutatoarele Activați accesul la cloud și Activați accesul local de pe pagina Expun dispozitive controlează doar apelurile API de intrare către unitatea Core; ele nu dezactivează webhook-ul.

Limitarea frecvenței: modificările se grupează și se trimit cel mai devreme după aproximativ 350 ms. La schimbări rapide ale valorii se trimite doar ultima modificare; valorile intermediare anterioare se elimină. Trimiterile eșuate nu se repetă.

Configurare: aplicația TapHome acceptă trei antete HTTP personalizate ale cererii, în formatul „key: value”.

Structura datelor: identică cu formatul răspunsului endpointului getMultipleDevicesValues.