Udostępnij urządzenia

TapHome API

TapHome API do integracji i obsługi urządzeń za pomocą żądań HTTP, uwierzytelnianie za pomocą tokena Bearer i webhook do powiadomień o zmianie stanu.

Przegląd

TapHome API umożliwia integrację urządzeń TapHome z aplikacjami firm trzecich za pomocą żądań protokołu HTTP i odpowiedzi JSON. System działa pod adresem https://api.taphome.com/api/TapHomeApi/v1/.

Najważniejsze cechy:

  • Dostęp do zasobów oparty na HTTP, z odpowiednimi kodami statusu
  • Standardowa dokumentacja Swagger dostępna pod https://api.taphome.com/api/doc
  • Odpowiedzi JSON kodowane w UTF-8
  • Wsparcie dla API w sieci lokalnej (Core 2021.3+) przez HTTP, bez interfejsu Swagger UI

Zaleta sieci lokalnej: Bezpośredni dostęp przez LAN/VPN zmniejsza opóźnienia i eliminuje zależność od Internetu. Jednostki Core wymagają stałego adresu IP lub konfiguracji mDNS.

Uwierzytelnianie

TapHome API wykorzystuje niestandardowe uwierzytelnianie HTTP za pomocą tokenów Bearer (nie używa poświadczeń użytkownik/hasło).

Format nagłówka

1

Authorization: TapHome {token}

Przykład żądania

1
2
3

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

Przykład cURL

1

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

Zarządzanie tokenami

Tokeny znajdziesz w aplikacji TapHome: Ustawienia → Udostępnij urządzenia → TapHome API.

Użyj menu kontekstowego (trzy kropki), aby wygenerować nowe tokeny dostępu. Wygenerowanie nowego tokena unieważnia poprzedni. Alternatywna metoda z parametrem zapytania jest dostępna wyłącznie dla wywołań GET (ostrzeżenie dotyczące bezpieczeństwa: unikaj udostępniania adresów URL zawierających tokeny).

Skompromitowane tokeny należy niezwłocznie zregenerować; w danym momencie aktywny jest tylko jeden token.

Referencje API

Pobierz informacje o lokalizacji

Pobiera metadane lokalizacji jednostki sterującej i weryfikuje status połączenia.

Wariant 1

1

GET /api/TapHomeApi/v1/location

Wariant 2

1

POST /api/TapHomeApi/v1/location

Parametry: Brak

Odpowiedź:

1
2
3
4
5

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

Błędy statusu HTTP:

  • 401 Nieautoryzowany
  • 404 Nie znaleziono (lokalizacja odłączona od chmury)
  • 405 Metoda niedozwolona
  • 500 Wewnętrzny błąd serwera

Odkrywanie urządzeń

Pobiera wyeksponowane urządzenia i ich obsługiwane typy wartości, w tym właściwości tylko do odczytu, takie jak Status urządzenia.

Wariant 1

1

GET /api/TapHomeApi/v1/discovery

Wariant 2

1

POST /api/TapHomeApi/v1/discovery

Parametry: Brak

Odpowiedź:

 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
}

Błędy statusu HTTP:

  • 401 Nieautoryzowany
  • 404 Nie znaleziono (lokalizacja odłączona od chmury)
  • 405 Metoda niedozwolona
  • 500 Wewnętrzny błąd serwera

Pobierz wartości urządzenia

Pobiera bieżące wartości dla wskazanego urządzenia, w tym identyfikatory typów i nazwy. Wartości są numeryczne (typ double). Niektóre właściwości są tylko do odczytu.

Wariant 1

1

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

Wariant 2

1

POST /api/CloudApi/v1/getDeviceValue

Parametry: Identyfikator urządzenia w ścieżce URL lub w treści JSON

Odpowiedź:

 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
}

Błędy statusu HTTP:

  • 401 Nieautoryzowany
  • 403 Zabroniony (urządzenie nie jest wyeksponowane)
  • 404 Nie znaleziono (lokalizacja odłączona od chmury)
  • 405 Metoda niedozwolona
  • 500 Wewnętrzny błąd serwera

Pobierz wartości wielu urządzeń

Pobiera wszystkie bieżące wartości dla wielu urządzeń jednocześnie. Zmniejsza zużycie pasma w porównaniu z indywidualnymi żądaniami. Wymaga Core 2021.3 lub nowszej.

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
}

Odpowiedź:

 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
}

Błędy statusu HTTP:

  • 401 Nieautoryzowany
  • 403 Zabroniony (urządzenie nie jest wyeksponowane)
  • 404 Nie znaleziono (lokalizacja odłączona od chmury)
  • 405 Metoda niedozwolona
  • 500 Wewnętrzny błąd serwera

Pobierz wszystkie wartości wszystkich urządzeń

Pobiera pełne informacje o stanie wszystkich wyeksponowanych urządzeń w jednym żądaniu. Wymaga Core 2021.3 lub nowszej.

Wariant 1

1

GET /api/CloudApi/v1/getAllDevicesValues

Wariant 2

1

POST /api/CloudApi/v1/getAllDevicesValues

Odpowiedź:

 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
}

Błędy statusu HTTP:

  • 401 Nieautoryzowany
  • 403 Zabroniony (urządzenie nie jest wyeksponowane)
  • 404 Nie znaleziono (lokalizacja odłączona od chmury)
  • 405 Metoda niedozwolona
  • 500 Wewnętrzny błąd serwera

Pobierz wartość pojedynczego urządzenia

Pobiera pojedynczą wartość urządzenia bez konieczności przetwarzania JSON. Idealne dla prostych implementacji. Odpowiedź jest liczbą (double) sformatowaną jako łańcuch znaków z notacją dziesiętną.

1

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

Parametry: Identyfikator urządzenia w ścieżce, identyfikator typu wartości i token w ciągu zapytania

Odpowiedź:

1

1.27

Nieznane wartości zwracają NaN. Częste żądania (częściej niż co 500 ms) mogą zwracać dane z pamięci podręcznej.

Błędy statusu HTTP:

  • 401 Nieautoryzowany
  • 403 Zabroniony (urządzenie nie jest wyeksponowane)
  • 404 Nie znaleziono (lokalizacja odłączona od chmury)
  • 405 Metoda niedozwolona
  • 500 Wewnętrzny błąd serwera

Ustaw wartość urządzenia

Modyfikuje jedną lub więcej wartości urządzenia według identyfikatora typu. Wartości nieokreślone pozostają bez zmian. Typ numeryczny (double).

Częste modyfikacje (częściej niż co 500 ms) generują odpowiedź HTTP 503.

Wariant 1

1

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

Obsługuje do trzech jednoczesnych przypisań wartości.

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

Odpowiedź:

 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
}

Błędy statusu HTTP:

  • 401 Nieautoryzowany
  • 403 Zabroniony (urządzenie nie jest wyeksponowane)
  • 404 Nie znaleziono (lokalizacja odłączona od chmury)
  • 405 Metoda niedozwolona
  • 500 Wewnętrzny błąd serwera
  • 503 Usługa niedostępna (zbyt częste ustawianie wartości; spróbuj ponownie później)

Webhook

Funkcjonalność Webhook dostarcza zmiany stanu wyeksponowanych urządzeń poprzez HTTP POST na skonfigurowany adres URL w środowiskach LAN lub Internet. Zapewnia bardziej efektywną synchronizację w porównaniu z okresowym odpytywaniem.

Ograniczanie częstotliwości: Aktywuje się przy minimalnych odstępach 300 ms. Przy szybkich zmianach wartości wysyłana jest tylko ostatnia zmiana; wcześniejsze wartości pośrednie są odrzucane. Nieudane transmisje nie są ponawiane.

Konfiguracja: Aplikacja TapHome obsługuje trzy niestandardowe nagłówki HTTP w formacie „klucz: wartość”.

Struktura danych: Identyczna jak format odpowiedzi punktu końcowego getMultipleDevicesValues.