---
title: "TapHome API"
description: "Povežite uređaje TapHome s bilo kojom aplikacijom putem REST API-ja. Autentifikacija, upravljanje uređajima, webhookovi i dokumentacija Swagger."
url: "https://taphome.com/hr/docs/expose-devices/taphome-api/"
language: hr
lastmod: 2026-11-06
generator: hugo
ai:
  topics: ["rest-api","api-integration","device-control","authentication","webhook","smart-home-api"]
  questions: ["Gdje u aplikaciji mogu pronaći svoj TapHome API token?","Kako autentificirati zahtjeve prema TapHome API-ju?","Koji je osnovni URL TapHome API-ja u oblaku?","Kako jednim API zahtjevom dohvatiti sve vrijednosti uređaja?","Kako postaviti webhook obavijesti o promjenama uređaja?","Radi li webhook bez pristupa oblaku, samo preko lokalne mreže?","Koja je verzija firmvera centralne jedinice Core potrebna za API u lokalnoj mreži?","Koja ograničenja učestalosti zahtjeva vrijede za krajnju točku setDeviceValue u TapHome API-ju?"]
---

# TapHome API

Pomoću TapHome API-ja uređaje TapHome možete povezati s bilo kojom aplikacijom treće strane, na primjer s glasovnim upravljanjem Apple Siri.

Posljednje ažuriranje: 2026-11-06

TapHome API je HTTP sučelje s odgovorima u formatu JSON koje aplikaciji treće strane omogućuje čitanje i promjenu vrijednosti uređaja TapHome. Radi s uređajima koje izložite u aplikaciji TapHome i nudi krajnje točke za otkrivanje uređaja, čitanje vrijednosti i postavljanje vrijednosti, kao i webhook koji promjene stanja šalje na URL koji ste postavili. Potreban vam je pristupni token koji generirate u aplikaciji TapHome u izborniku **Postavke → Izložite uređaje → TapHome API** i šaljete ga u zaglavlju Authorization svakog zahtjeva. Rezultat je da vanjska aplikacija može nadzirati izložene uređaje i upravljati njima preko `https://api.taphome.com/api/TapHomeApi/v1/` ili, ako ga Core podržava, preko lokalne mreže.

## Pregled

TapHome API omogućuje povezivanje uređaja TapHome s aplikacijama trećih strana putem zahtjeva preko protokola HTTP i odgovora u formatu JSON. Sustav radi putem adrese `https://api.taphome.com/api/TapHomeApi/v1/`.

Glavne značajke:
- pristup resursima putem HTTP-a s odgovarajućim statusnim kodovima
- standardna dokumentacija Swagger dostupna na adresi `https://api.taphome.com/api/doc`
- odgovori u formatu JSON s kodiranjem UTF-8
- podrška za API u lokalnoj mreži (Core 2021.3 ili noviji) putem HTTP-a, bez sučelja Swagger UI

**Prednost lokalne mreže**: izravan pristup preko LAN-a/VPN-a smanjuje kašnjenje i uklanja ovisnost o internetu. Centralne jedinice Core trebaju fiksnu IP adresu ili konfiguraciju mDNS.

**Sigurnosna napomena**: API u lokalnoj mreži i webhook rade preko nešifriranog HTTP-a i pretpostavljaju da je lokalna mreža pouzdana. Na zajedničkim lokacijama ili lokacijama s više korisnika, na primjer u hotelima ili uredima s Wi-Fi mrežom za goste, centralnu jedinicu Core postavite u zaseban mrežni segment odvojen od mreže za goste. Pogledajte [Mrežnu arhitekturu](https://taphome.com/hr/docs/configuration/network-architecture/#local-connection).

## Autentifikacija

TapHome API koristi vlastitu HTTP autentifikaciju s bearer tokenima (bez korisničkog imena i lozinke).

### Format zaglavlja
```text
Authorization: TapHome {token}
```

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

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

### Upravljanje tokenima

Tokene ćete pronaći u aplikaciji TapHome: **Postavke → Izložite uređaje → TapHome API**

Nove pristupne tokene generirajte pomoću kontekstnog izbornika (tri točke). Generiranjem novog tokena prethodni prestaju vrijediti. Kao alternativa, token se može poslati kao parametar upita, ali samo kod poziva GET (sigurnosno upozorenje: ne dijelite URL-ove koji sadrže token).

Ugroženi token odmah treba ponovno generirati. Istodobno je aktivan samo jedan token.

## Referentna dokumentacija API-ja

### Dohvaćanje informacija o lokaciji

Dohvaća metapodatke o lokaciji centralne jedinice i provjerava stanje povezanosti.

**Varijanta 1**
```text
GET /api/TapHomeApi/v1/location
```

**Varijanta 2**
```text
POST /api/TapHomeApi/v1/location
```

**Parametri**: nema

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

**Pogreške (HTTP statusni kodovi)**:
- 401 Neovlašten pristup
- 404 Nije pronađeno (lokacija nije povezana s oblakom)
- 405 Metoda nije dopuštena
- 500 Interna pogreška poslužitelja

### Otkrivanje uređaja

Dohvaća izložene uređaje i vrste vrijednosti koje podržavaju, uključujući svojstva samo za čitanje kao što je stanje uređaja (Device Status).

**Varijanta 1**
```text
GET /api/TapHomeApi/v1/discovery
```

**Varijanta 2**
```text
POST /api/TapHomeApi/v1/discovery
```

**Parametri**: nema

**Odgovor**:
```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
}
```

**Pogreške (HTTP statusni kodovi)**:
- 401 Neovlašten pristup
- 404 Nije pronađeno (lokacija nije povezana s oblakom)
- 405 Metoda nije dopuštena
- 500 Interna pogreška poslužitelja

### Dohvaćanje vrijednosti uređaja

Dohvaća sve trenutačne vrijednosti navedenog uređaja, uključujući ID-ove i nazive vrsta vrijednosti. Vrijednosti su brojčane (tip double). Neka su svojstva samo za čitanje.

Česti zahtjevi (u razmacima kraćim od 500 ms) mogu vratiti vrijednosti iz predmemorije. Vremenske oznake uspoređujte samo na jednakost.

**Varijanta 1**
```text
GET /api/CloudApi/v1/getDeviceValue/{deviceId}
```

**Varijanta 2**
```text
POST /api/CloudApi/v1/getDeviceValue
```

**Parametri**: ID uređaja u putanji URL-a ili u tijelu zahtjeva u formatu JSON

**Odgovor**:
```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
}
```

**Pogreške (HTTP statusni kodovi)**:
- 401 Neovlašten pristup
- 403 Zabranjeno (uređaj nije izložen)
- 404 Nije pronađeno (lokacija nije povezana s oblakom)
- 405 Metoda nije dopuštena
- 500 Interna pogreška poslužitelja

### Dohvaćanje vrijednosti više uređaja

Istodobno dohvaća sve trenutačne vrijednosti više uređaja. U usporedbi s pojedinačnim zahtjevima smanjuje prijenos podataka. Potreban je Core 2021.3 ili noviji.

```text
POST /api/CloudApi/v1/getMultipleDevicesValues
```

**Parametri**:
```json
{
 "devices": [
    {
      "deviceId": 1,
      "valueTypeId": 7
    },
    {
      "deviceId": 2
    }
  ],
  "timestamp": 855000000000
}
```

**Odgovor**:
```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
}
```

**Pogreške (HTTP statusni kodovi)**:
- 401 Neovlašten pristup
- 403 Zabranjeno (uređaj nije izložen)
- 404 Nije pronađeno (lokacija nije povezana s oblakom)
- 405 Metoda nije dopuštena
- 500 Interna pogreška poslužitelja

### Dohvaćanje svih vrijednosti svih uređaja

Jednim zahtjevom dohvaća potpune informacije o stanju svih izloženih uređaja. Potreban je Core 2021.3 ili noviji.

**Varijanta 1**
```text
GET /api/CloudApi/v1/getAllDevicesValues
```

**Varijanta 2**
```text
POST /api/CloudApi/v1/getAllDevicesValues
```

**Odgovor**:
```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
}
```

**Pogreške (HTTP statusni kodovi)**:
- 401 Neovlašten pristup
- 403 Zabranjeno (uređaj nije izložen)
- 404 Nije pronađeno (lokacija nije povezana s oblakom)
- 405 Metoda nije dopuštena
- 500 Interna pogreška poslužitelja

### Dohvaćanje jedne vrijednosti uređaja

Dohvaća jednu vrijednost uređaja bez potrebe za obradom JSON-a. Idealno za jednostavne implementacije. Brojčani odgovor (double) vraća se kao tekst s decimalnom točkom.

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

**Parametri**: ID uređaja u putanji, ID vrste vrijednosti i token u nizu upita

**Odgovor**:
```text
1.27
```

Za nepoznate vrijednosti vraća se `NaN`. Česti zahtjevi (u razmacima kraćim od 500 ms) mogu vratiti podatke iz predmemorije.

**Pogreške (HTTP statusni kodovi)**:
- 401 Neovlašten pristup
- 403 Zabranjeno (uređaj nije izložen)
- 404 Nije pronađeno (lokacija nije povezana s oblakom)
- 405 Metoda nije dopuštena
- 500 Interna pogreška poslužitelja

### Postavljanje vrijednosti uređaja

Mijenja jednu ili više vrijednosti uređaja prema identifikatoru vrste. Vrijednosti koje nisu navedene ostaju nepromijenjene. Brojčani tip (double).

Česte promjene (u razmacima kraćim od 500 ms) vraćaju odgovor HTTP 503.

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

Podržava postavljanje najviše triju vrijednosti istodobno.

**Varijanta 2**
```text
POST /api/TapHomeApi/v1/setDeviceValue
```

**Parametri**:
```json
{
  "deviceId": 2,
  "values": [
    {
      "valueTypeId": 46,
      "value": 0.1
    },
    {
      "valueTypeId": 10,
      "value": 0.2
    }
  ]
}
```

**Odgovor**:
```json
{
  "deviceId": 2,
  "valuesChanged": [
    {
      "typeId": 46,
      "result": "changed"
    },
    {
      "typeId": 10,
      "result": "notchanged"
    },
    {
      "typeId": 7,
      "result": "failed"
    }
  ],
  "timestamp": 855000000000
}
```

**Pogreške (HTTP statusni kodovi)**:
- 401 Neovlašten pristup
- 403 Zabranjeno (uređaj nije izložen)
- 404 Nije pronađeno (lokacija nije povezana s oblakom)
- 405 Metoda nije dopuštena
- 500 Interna pogreška poslužitelja
- 503 Usluga nije dostupna (prečesto postavljanje vrijednosti; pokušajte ponovno kasnije)

## Webhook

Funkcija webhook šalje promjene stanja izloženih uređaja zahtjevom HTTP POST na konfigurirani URL u lokalnoj mreži (LAN) ili na internetu. U usporedbi s periodičnim ispitivanjem omogućuje učinkovitiju sinkronizaciju.

**Šalje se izravno, ne preko oblaka**: webhook je *odlazni* zahtjev HTTP POST koji centralna jedinica Core šalje izravno na konfigurirani URL. Podaci nikad ne prolaze kroz poslužitelje TapHome u oblaku. Ako je odredište u istoj lokalnoj mreži, webhook se isporučuje lokalno preko LAN-a, bez prolaska kroz internet. Prekidači **Pristup u oblaku** i **Lokalni pristup** na stranici Izložite uređaje upravljaju samo *dolaznim* API pozivima prema centralnoj jedinici Core. Webhook ne isključuju.

**Ograničavanje učestalosti**: promjene se skupljaju i šalju najranije nakon približno 350 ms. Kod brzih promjena vrijednosti šalje se samo posljednja promjena, a prethodne međuvrijednosti se odbacuju. Neuspjela slanja ne ponavljaju se.

**Konfiguracija**: aplikacija TapHome podržava tri prilagođena zaglavlja HTTP zahtjeva u formatu „ključ: vrijednost”.

**Struktura podataka**: ista kao format odgovora krajnje točke `getMultipleDevicesValues`.
