--- title: "TapHome API" description: "TapHome eszközök integrálása bármely alkalmazásba REST API-n keresztül. Hitelesítés, eszközvezérlés, webhookok és Swagger dokumentáció." url: "https://taphome.com/hu/docs/expose-devices/taphome-api/" language: hu lastmod: 2026-11-06 generator: hugo ai: topics: ["rest-api","api-integration","device-control","authentication","webhook","smart-home-api"] questions: ["Hol találom a TapHome API tokent az alkalmazásban?","Hogyan hitelesítsem a TapHome API kéréseket?","Mi a TapHome cloud API alap URL-je?","Hogyan kérhetem le az összes eszközértéket egyetlen API kéréssel?","Hogyan állítsam be a webhook értesítéseket eszközváltozásokhoz?","Melyik Core firmware verzió szükséges a helyi hálózati API-hoz?","Milyen rate limitek vonatkoznak a TapHome API setDeviceValue végpontra?","Működik a webhook felhő hozzáférés nélkül, csak a helyi hálózaton keresztül?"] --- # TapHome API Integrálja a TapHome eszközöket alkalmazásokba HTTP és JSON használatával a TapHome API-n keresztül. Támogatja az autentikációt, az értékek lekérdezését és beállítását, webhookokat. Utoljára frissítve: 2026-11-06 A TapHome API egy HTTP-felület JSON-válaszokkal, amelynek segítségével egy harmadik fél alkalmazása kiolvashatja és módosíthatja a TapHome eszközök értékeit. A TapHome alkalmazásban felfedett eszközökkel működik, és végpontokat kínál az eszközök felderítésére, az értékek lekérdezésére és beállítására, valamint egy webhookot, amely az állapotváltozásokat az Ön által megadott URL-re küldi. Hozzáférési tokenre van szüksége, amelyet a TapHome alkalmazásban a **Beállítások → Eszközök felfedése → TapHome API** menüpontban hozhat létre, és minden kérés Authorization fejlécében kell elküldenie. Az eredmény: egy külső alkalmazás a `https://api.taphome.com/api/TapHomeApi/v1/` címen keresztül, vagy ha a Core támogatja, a helyi hálózaton át figyelheti és vezérelheti a felfedett eszközöket. ## Áttekintés A TapHome API lehetővé teszi a TapHome eszközök integrációját harmadik fél alkalmazásaiba HTTP-kérések és JSON-válaszok segítségével. A rendszer a `https://api.taphome.com/api/TapHomeApi/v1/` címen érhető el. Fő jellemzők: - HTTP-alapú erőforrás-hozzáférés megfelelő státuszkódokkal - Szabványos Swagger dokumentáció a `https://api.taphome.com/api/doc` címen - UTF-8 kódolású JSON válaszok - Helyi hálózati API-támogatás (Core 2021.3 vagy újabb) HTTP-n keresztül, Swagger UI nélkül **Helyi hálózati előnyök**: A közvetlen LAN/VPN hozzáférés csökkenti a késleltetést és megszünteti az internetkapcsolattól való függést. A Core egységekhez fix IP-cím vagy mDNS-konfiguráció szükséges. **Biztonsági megjegyzés**: A helyi hálózati API és a webhook egyszerű HTTP-n keresztül fut, és feltételezi, hogy a helyi hálózat megbízható. Megosztott vagy több bérlős helyszíneken — például szállodákban vagy vendég Wi-Fi-vel rendelkező irodákban — helyezze a Core-t egy dedikált hálózati szegmensre, elkülönítve a vendéghálózattól. Lásd: [Hálózati architektúra](https://taphome.com/hu/docs/configuration/network-architecture/#local-connection). ## Hitelesítés A TapHome API egyedi HTTP-alapú hitelesítést használ bearer tokenekkel (nem felhasználónév/jelszó-alapú hitelesítés). ### Fejléc formátuma ```http Authorization: TapHome {token} ``` ### Példa kérés ```http GET /api/TapHomeApi/v1/location HTTP/1.1 Host: api.taphome.com Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32 ``` ### cURL példa ```bash curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://api.taphome.com/api/TapHomeApi/v1/location" ``` ### Tokenkezelés A tokenek a TapHome alkalmazásban, a **Beállítások → Eszközök felfedése → TapHome API** menüpontban érhetők el. A kontextusmenüből (három pont) friss hozzáférési tokenek generálhatók. Új tokenok generálása érvényteleníti a korábbiakat. GET hívásokhoz lekérdezési paraméteres alternatíva is elérhető (biztonsági figyelmeztetés: kerülje a tokeneket tartalmazó URL-ek megosztását). Kompromittált tokenek esetén azonnali regenerálás szükséges; egyszerre csak egy token lehet aktív. ## API referencia ### Helyinformáció lekérése Lekéri a vezérlőegység helyadatait, és érvényesíti a kapcsolati állapotot. **Változat 1** ```http GET /api/TapHomeApi/v1/location ``` **Változat 2** ```http POST /api/TapHomeApi/v1/location ``` **Paraméterek**: Nincs **Válasz**: ```json { "locationId": "53e14fbd-c9d1-4615-b994-8d6ec8834e7b", "locationName": "Test Location", "timestamp": 855000000000 } ``` **HTTP állapot hibák**: - 401 Nem hitelesített - 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz) - 405 Módszer nem engedélyezett - 500 Belső szerverhiba ### Eszközök felfedezése Lekéri a felfedett eszközöket és az általuk támogatott értéktípusokat, beleértve az írásvédett tulajdonságokat is, mint az Eszközállapot. **Változat 1** ```http GET /api/TapHomeApi/v1/discovery ``` **Változat 2** ```http POST /api/TapHomeApi/v1/discovery ``` **Paraméterek**: Nincs **Válasz**: ```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 } ``` **HTTP állapot hibák**: - 401 Nem hitelesített - 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz) - 405 Módszer nem engedélyezett - 500 Belső szerverhiba ### Eszközérték lekérése Lekéri egy adott eszköz összes aktuális értékét, beleértve a típusazonosítókat és neveket. Az értékek numerikusak (double típusúak). Néhány tulajdonság csak olvasható. Gyakori kérések (500 ms alatti intervallumok) esetén előfordulhat, hogy gyorsítótárazott értékek kerülnek visszaadásra; az egyezőséget kizárólag az időbélyegek alapján ellenőrizze. **Változat 1** ```http GET /api/CloudApi/v1/getDeviceValue/{deviceId} ``` **Változat 2** ```http POST /api/CloudApi/v1/getDeviceValue ``` **Paraméterek**: Eszközazonosító az URL-ben vagy a JSON törzsben **Válasz**: ```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 } ``` **HTTP állapot hibák**: - 401 Nem hitelesített - 403 Tiltott (az eszköz nincs felfedve) - 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz) - 405 Módszer nem engedélyezett - 500 Belső szerverhiba ### Több eszköz értékeinek lekérése Egyszerre lekéri több eszköz aktuális értékeit. Csökkenti a sávszélesség-használatot az egyedi kérésekhez képest. Szükséges verzió: Core 2021.3 vagy újabb. ```http POST /api/CloudApi/v1/getMultipleDevicesValues ``` **Paraméterek**: ```json { "devices": [ { "deviceId": 1, "valueTypeId": 7 }, { "deviceId": 2 } ], "timestamp": 855000000000 } ``` **Válasz**: ```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 } ``` **HTTP állapot hibák**: - 401 Nem hitelesített - 403 Tiltott (az eszköz nincs felfedve) - 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz) - 405 Módszer nem engedélyezett - 500 Belső szerverhiba ### Az összes eszköz értékeinek lekérése Egyszerre lekéri az összes előzetesen felfedett eszköz teljes állapotinformációját egyetlen kérésben. Szükséges verzió: Core 2021.3 vagy újabb. **Változat 1** ```http GET /api/CloudApi/v1/getAllDevicesValues ``` **Változat 2** ```http POST /api/CloudApi/v1/getAllDevicesValues ``` **Válasz**: ```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 } ``` **HTTP állapot hibák**: - 401 Nem hitelesített - 403 Tiltott (az eszköz nincs felfedve) - 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz) - 405 Módszer nem engedélyezett - 500 Belső szerverhiba ### Egy eszköz értékének lekérése Lekéri egyetlen eszköz értékét JSON-feldolgozási követelmények nélkül. Ideális egyszerű megvalósításokhoz. A numerikus válasz (double) sztringként, tizedes ponttal formázva érkezik. ```http GET /api/CloudApi/v1/getOneDeviceValue/{deviceId}?valueTypeId={valueTypeId}&token={theToken} ``` **Paraméterek**: Eszközazonosító az útvonalban, értéktípus-azonosító és token a lekérdezési paraméterekben **Válasz**: ```text 1.27 ``` Ismeretlen értékek esetén `NaN` kerül visszaadásra. Gyakori kérések (500 ms alatti intervallumok) esetén előfordulhat, hogy gyorsítótárazott adatok kerülnek visszaadásra. **HTTP állapot hibák**: - 401 Nem hitelesített - 403 Tiltott (az eszköz nincs felfedve) - 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz) - 405 Módszer nem engedélyezett - 500 Belső szerverhiba ### Eszközérték beállítása Egy vagy több eszközérték módosítása típusazonosító alapján. A megadott értékek módosulnak, a meg nem adott értékek változatlanok maradnak. Numerikus típus (double). Gyakori módosítások (500 ms alatti intervallumok) HTTP 503 választ eredményezhetnek. **Változat 1** ```http GET /api/TapHomeApi/v1/setDeviceValue/{deviceId}?valueTypeId={valueTypeId1}&value={value1}&valueTypeId2={valueTypeId2}&value2={value2}&token={theToken} ``` Egyszerű használatra legfeljebb három egyidejű érték hozzárendelését támogatja. **Változat 2** ```http POST /api/TapHomeApi/v1/setDeviceValue ``` **Paraméterek**: ```json { "deviceId": 2, "values": [ { "valueTypeId": 46, "value": 0.1 }, { "valueTypeId": 10, "value": 0.2 } ] } ``` **Válasz**: ```json { "deviceId": 2, "valuesChanged": [ { "typeId": 46, "result": "changed" }, { "typeId": 10, "result": "notchanged" }, { "typeId": 7, "result": "failed" } ], "timestamp": 855000000000 } ``` **HTTP állapot hibák**: - 401 Nem hitelesített - 403 Tiltott (az eszköz nincs felfedve) - 404 Nem található (a helyszín nincs csatlakoztatva a felhőhöz) - 405 Módszer nem engedélyezett - 500 Belső szerverhiba - 503 Szolgáltatás nem érhető el (túlzott értékállítási gyakoriság; próbálja újra később) ## Webhook A Webhook-funkcionalitás a nyilvános eszközállapot-változásokat HTTP POST kéréssel küldi egy konfigurált URL-re a helyi hálózatban vagy az interneten. Hatékonyabb szinkronizációt biztosít az időszakos lekérdezéshez képest. **Közvetlenül küldve, nem a felhőn keresztül**: A webhook egy *kimenő* HTTP POST, amelyet a Core egyenesen a beállított URL-re küld — az adatcsomag soha nem halad át a TapHome felhőszervereken. Ha a cél ugyanazon a helyi hálózaton fut, a webhook helyben, a LAN-on keresztül kerül kézbesítésre, internetes oda-vissza út nélkül. Az Eszközök felfedése oldalon található **Felhő hozzáférés** és **Helyi hozzáférés** kapcsolók csak a Core-ba irányuló *bejövő* API hívásokat szabályozzák; nem kapcsolják ki a webhookot. **Sebességkorlátozás**: A változtatások kötegelve, legkorábban körülbelül 350 ms elteltével kerülnek elküldésre. A gyors értékátmenetek csak a legutolsó változást küldik el; a korábbi köztes értékek eldobásra kerülnek. A sikertelen átvitelek nem kerülnek újrapróbálásra. **Konfiguráció**: A TapHome alkalmazás három egyedi HTTP kérésfejlécet támogat „kulcs: érték” formátumban. **Adatszerkezet**: Meg egyezik a `getMultipleDevicesValues` végpont válaszformátumával.