--- title: "TapHome API" description: "Integruj urządzenia TapHome z dowolną aplikacją przez REST API. Uwierzytelnianie, sterowanie, webhooki i dokumentacja Swagger." url: "https://taphome.com/pl/docs/expose-devices/taphome-api/" language: pl lastmod: 2026-11-06 generator: hugo ai: topics: ["rest-api","api-integration","device-control","authentication","webhook","smart-home-api"] questions: ["Gdzie znajdę mój token TapHome API w aplikacji?","Jak uwierzytelniać żądania do TapHome API?","Jaki jest bazowy URL dla TapHome cloud API?","Jak pobrać wartości wszystkich urządzeń jednym żądaniem API?","Jak skonfigurować powiadomienia webhook dla zmian urządzeń?","Jaka wersja firmware Core jest wymagana dla lokalnego API sieciowego?","Jakie limity częstotliwości obowiązują dla endpointu setDeviceValue TapHome API?","Czy webhook działa bez dostępu do chmury, tylko w sieci lokalnej?"] --- # 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. Ostatnia aktualizacja: 2026-11-06 TapHome API to interfejs HTTP z odpowiedziami w formacie JSON, który pozwala aplikacji firmy trzeciej odczytywać i zmieniać wartości urządzeń TapHome. Działa z urządzeniami, które udostępnisz w aplikacji TapHome, i oferuje punkty końcowe do wykrywania urządzeń, odczytu wartości i ich ustawiania, a także webhook wysyłający zmiany stanu na skonfigurowany przez Ciebie adres URL. Potrzebujesz tokena dostępu, który wygenerujesz w aplikacji TapHome w sekcji **Ustawienia → Udostępnij urządzenia → TapHome API** i prześlesz w nagłówku Authorization każdego żądania. Efektem jest to, że zewnętrzna aplikacja może monitorować udostępnione urządzenia i sterować nimi przez `https://api.taphome.com/api/TapHomeApi/v1/` lub, jeśli Core to obsługuje, przez sieć lokalną. ## 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 lub nowszy) 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. **Uwaga dotycząca bezpieczeństwa**: Lokalne API sieciowe oraz webhook działają przez zwykły HTTP i zakładają, że sieć lokalna jest zaufana. W obiektach współdzielonych lub wielodostępnych — na przykład w hotelach lub biurach z gościnnym Wi-Fi — należy umieścić Core w dedykowanym segmencie sieci oddzielonym od sieci dla gości. Zobacz [Architektura sieci](https://taphome.com/pl/docs/configuration/network-architecture/#local-connection). ## Uwierzytelnianie TapHome API wykorzystuje niestandardowe uwierzytelnianie HTTP za pomocą tokenów Bearer (nie używa poświadczeń użytkownik/hasło). ### Format nagłówka ```text Authorization: TapHome {token} ``` ### Przykład żądania ```text GET /api/TapHomeApi/v1/location HTTP/1.1 Host: api.taphome.com Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32 ``` ### Przykład cURL ```text 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** ```text GET /api/TapHomeApi/v1/location ``` **Wariant 2** ```text POST /api/TapHomeApi/v1/location ``` **Parametry**: Brak **Odpowiedź**: ```json { "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** ```text GET /api/TapHomeApi/v1/discovery ``` **Wariant 2** ```text POST /api/TapHomeApi/v1/discovery ``` **Parametry**: Brak **Odpowiedź**: ```json { "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** ```text GET /api/CloudApi/v1/getDeviceValue/{deviceId} ``` **Wariant 2** ```text POST /api/CloudApi/v1/getDeviceValue ``` **Parametry**: Identyfikator urządzenia w ścieżce URL lub w treści JSON **Odpowiedź**: ```json { "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. Wymagana wersja: Core 2021.3 lub nowszy. ```text POST /api/CloudApi/v1/getMultipleDevicesValues ``` **Parametry**: ```json { "devices": [ { "deviceId": 1, "valueTypeId": 7 }, { "deviceId": 2 } ], "timestamp": 855000000000 } ``` **Odpowiedź**: ```json { "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. Wymagana wersja: Core 2021.3 lub nowszy. **Wariant 1** ```text GET /api/CloudApi/v1/getAllDevicesValues ``` **Wariant 2** ```text POST /api/CloudApi/v1/getAllDevicesValues ``` **Odpowiedź**: ```json { "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ą. ```text 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ź**: ```text 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** ```text 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** ```text POST /api/TapHomeApi/v1/setDeviceValue ``` **Parametry**: ```json { "deviceId": 2, "values": [ { "valueTypeId": 46, "value": 0.1 }, { "valueTypeId": 10, "value": 0.2 } ] } ``` **Odpowiedź**: ```json { "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. **Wysyłane bezpośrednio, nie przez chmurę**: Webhook to *wychodzące* żądanie HTTP POST, które Core wysyła prosto na skonfigurowany URL — dane nigdy nie przechodzą przez serwery w chmurze TapHome. Jeśli cel działa w tej samej sieci lokalnej, webhook jest dostarczany lokalnie przez LAN, bez konieczności łączenia się z internetem. Przełączniki **Dostęp przez chmurę** i **Dostęp lokalny** na stronie Udostępnij urządzenia kontrolują tylko *przychodzące* wywołania API do Core; nie wyłączają one webhooka. **Ograniczanie częstotliwości**: Zmiany są grupowane i wysyłane najwcześniej po około 350 ms. Szybkie zmiany wartości powodują wysłanie tylko najnowszej zmiany; 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`.