--- title: "TapHome API" description: "Integrujte zariadenia TapHome do ľubovoľnej aplikácie cez REST API. Autentifikácia, ovládanie zariadení, webhooky a Swagger dokumentácia." url: "https://taphome.com/sk/docs/expose-devices/taphome-api/" language: sk lastmod: 2026-11-06 generator: hugo ai: topics: ["rest-api","api-integration","device-control","authentication","webhook","smart-home-api"] questions: ["Kde v aplikácii nájdete svoj TapHome API token?","Ako sa autentifikujú požiadavky na TapHome API?","Aká je základná URL pre cloudové TapHome API?","Ako získať všetky hodnoty zariadení jedným API volaním?","Ako nastaviť webhook notifikácie pre zmeny zariadení?","Aká verzia firmvéru Core je potrebná pre API v lokálnej sieti?","Aké limity rýchlosti požiadaviek (rate limits) platia pre endpoint setDeviceValue v TapHome API?","Funguje webhook bez prístupu do cloudu, iba cez lokálnu sieť?"] --- # 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. Posledná aktualizácia: 2026-11-06 TapHome API je rozhranie HTTP s odpoveďami vo formáte JSON, ktoré aplikácii tretej strany umožňuje čítať a meniť hodnoty zariadení TapHome. Pracuje so zariadeniami, ktoré zverejníte v aplikácii TapHome, a ponúka koncové body na zistenie zariadení, čítanie hodnôt a nastavovanie hodnôt, ako aj webhook, ktorý posiela zmeny stavu na vami nastavenú adresu URL. Potrebujete prístupový token, ktorý vygenerujete v aplikácii TapHome v časti **Nastavenia → Zverejniť zariadenia → TapHome API** a pošlete ho v hlavičke Authorization každej požiadavky. Výsledkom je, že externá aplikácia môže sledovať a ovládať zverejnené zariadenia cez `https://api.taphome.com/api/TapHomeApi/v1/` alebo, ak to Core podporuje, cez miestnu sieť. ## 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 alebo novší) 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. **Bezpečnostná poznámka**: API lokálnej siete a webhook bežia cez nešifrované HTTP a predpokladajú, že lokálna sieť je dôveryhodná. Na zdieľaných lokalitách alebo lokalitách pre viacerých nájomníkov — napríklad v hoteloch alebo kanceláriách s hosťovskou Wi-Fi — umiestnite Core do vyhradeného sieťového segmentu oddeleného od hosťovskej siete. Pozrite si [Architektúra siete](https://taphome.com/sk/docs/configuration/network-architecture/#local-connection). ## Autentifikácia TapHome API používa vlastnú HTTP autentifikáciu pomocou bearer tokenov (nie prihlasovacie meno a heslo). ### Formát hlavičky ```http Authorization: TapHome {token} ``` ### Príklad požiadavky ```http GET /api/TapHomeApi/v1/location HTTP/1.1 Host: api.taphome.com Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32 ``` ### Príklad cURL ```bash curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://api.taphome.com/api/TapHomeApi/v1/location" ``` ### Správa tokenov 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** ```http GET /api/TapHomeApi/v1/location ``` **Variant 2** ```http POST /api/TapHomeApi/v1/location ``` **Parametre**: Žiadne **Odpoveď**: ```json { "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** ```http GET /api/TapHomeApi/v1/discovery ``` **Variant 2** ```http POST /api/TapHomeApi/v1/discovery ``` **Parametre**: Žiadne **Odpoveď**: ```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 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** ```http GET /api/CloudApi/v1/getDeviceValue/{deviceId} ``` **Variant 2** ```http POST /api/CloudApi/v1/getDeviceValue ``` **Parametre**: ID zariadenia v URL ceste alebo v tele JSON **Odpoveď**: ```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 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ší. ```http POST /api/CloudApi/v1/getMultipleDevicesValues ``` **Parametre**: ```json { "devices": [ { "deviceId": 1, "valueTypeId": 7 }, { "deviceId": 2 } ], "timestamp": 855000000000 } ``` **Odpoveď**: ```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 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** ```http GET /api/CloudApi/v1/getAllDevicesValues ``` **Variant 2** ```http POST /api/CloudApi/v1/getAllDevicesValues ``` **Odpoveď**: ```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 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. ```http 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ď**: ```text 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** ```http 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** ```http POST /api/TapHomeApi/v1/setDeviceValue ``` **Parametre**: ```json { "deviceId": 2, "values": [ { "valueTypeId": 46, "value": 0.1 }, { "valueTypeId": 10, "value": 0.2 } ] } ``` **Odpoveď**: ```json { "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. **Odosielané priamo, nie cez cloud**: Webhook je *odchádzajúci* HTTP POST, ktorý Core posiela priamo na nakonfigurovanú URL — dáta nikdy neprechádzajú cez cloudové servery TapHome. Ak cieľ beží v rovnakej lokálnej sieti, webhook je doručený lokálne cez LAN, bez cesty cez internet. Prepínače **Cloudový prístup** a **Lokálny prístup** na stránke Zverejniť zariadenia riadia iba *prichádzajúce* volania API do Core; nevypínajú webhook. **Obmedzovanie frekvencie**: Zmeny sú zoskupované do dávok a odosielané najskôr po približne 350 ms. Pri rýchlych zmenách hodnôt sa odošle iba najnovšia zmena; predchádzajúce priebežné hodnoty 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`.