---
title: "TapHome API"
description: "Integrați dispozitivele TapHome în orice aplicație prin REST API. Autentificare, controlul dispozitivelor, webhook-uri și documentație Swagger."
url: "https://taphome.com/ro/docs/expose-devices/taphome-api/"
language: ro
lastmod: 2026-11-06
generator: hugo
ai:
  topics: ["rest-api","api-integration","device-control","authentication","webhook","smart-home-api"]
  questions: ["Unde găsesc tokenul TapHome API în aplicație?","Cum autentific cererile către TapHome API?","Care este URL-ul de bază al TapHome API în cloud?","Cum obțin toate valorile dispozitivelor într-o singură cerere API?","Cum configurez notificări webhook pentru modificările dispozitivelor?","Funcționează webhook-ul fără acces la cloud, doar prin rețeaua locală?","Ce versiune de firmware Core este necesară pentru API în rețeaua locală?","Ce limite de frecvență se aplică pentru endpointul setDeviceValue din TapHome API?"]
---

# TapHome API

Prin TapHome API puteți integra dispozitivele TapHome în orice aplicație terță, de exemplu pentru controlul vocal cu Apple Siri.

Ultima actualizare: 2026-11-06

TapHome API este o interfață HTTP cu răspunsuri JSON, prin care o aplicație terță poate citi și modifica valorile dispozitivelor TapHome. Funcționează cu dispozitivele pe care le expuneți în aplicația TapHome și oferă endpointuri pentru descoperirea dispozitivelor, citirea valorilor și setarea lor, precum și un webhook care trimite modificările de stare la un URL configurat de dumneavoastră. Aveți nevoie de un token de acces, pe care îl generați în aplicația TapHome la **Setări → Expuneți dispozitivele → TapHome API** și îl trimiteți în antetul Authorization al fiecărei cereri. Rezultatul este că o aplicație externă poate monitoriza și controla dispozitivele expuse prin `https://api.taphome.com/api/TapHomeApi/v1/` sau, dacă Core-ul o permite, prin rețeaua locală.

## Prezentare generală

TapHome API permite integrarea dispozitivelor TapHome în aplicații terțe prin cereri pe protocolul HTTP și răspunsuri JSON. Sistemul funcționează prin `https://api.taphome.com/api/TapHomeApi/v1/`

Caracteristici principale:
- acces la resurse prin HTTP, cu coduri de stare corespunzătoare
- documentație Swagger standard disponibilă la `https://api.taphome.com/api/doc`
- răspunsuri JSON codificate în UTF-8
- suport pentru API în rețeaua locală (Core 2021.3 sau mai nou) prin HTTP, fără interfața Swagger

**Avantajul rețelei locale**: accesul direct prin LAN/VPN reduce latența și elimină dependența de internet. Unitățile Core necesită o adresă IP fixă sau configurare mDNS.

**Notă de securitate**: API-ul din rețeaua locală și webhook-ul funcționează prin HTTP simplu și presupun că rețeaua locală este de încredere. În clădirile cu rețea partajată sau cu mai mulți utilizatori, de exemplu hoteluri sau birouri cu Wi-Fi pentru oaspeți, amplasați unitatea Core într-un segment de rețea dedicat, separat de rețeaua pentru oaspeți. Consultați [Arhitectura rețelei](https://taphome.com/ro/docs/configuration/network-architecture/#local-connection).

## Autentificare

TapHome API folosește o autentificare HTTP proprie, cu tokenuri bearer (nu cu nume de utilizator și parolă).

### Formatul antetului
```text
Authorization: TapHome {token}
```

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

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

### Gestionarea tokenurilor

Tokenurile se găsesc în aplicația TapHome: **Setări → Expuneți dispozitivele → TapHome API**

Folosiți meniul contextual (cele trei puncte) pentru a genera tokenuri de acces noi. Generarea unui token nou invalidează tokenurile anterioare. Alternativa cu parametru de interogare este disponibilă doar pentru apelurile GET (avertisment de securitate: nu partajați URL-uri care conțin tokenuri).

Un token compromis trebuie regenerat imediat; la un moment dat este activ un singur token.

## Referința API

### Obținerea informațiilor despre locație

Returnează metadatele locației unității de control și verifică starea conexiunii.

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

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

**Parametri**: niciunul

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

**Erori HTTP**:
- 401 Unauthorized (neautorizat)
- 404 Not Found (locația este deconectată de la cloud)
- 405 Method Not Allowed (metodă nepermisă)
- 500 Internal Server Error (eroare internă a serverului)

### Descoperirea dispozitivelor

Returnează dispozitivele expuse și tipurile de valori acceptate de acestea, inclusiv proprietățile doar pentru citire, precum Device Status.

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

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

**Parametri**: niciunul

**Răspuns**:
```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
}
```

**Erori HTTP**:
- 401 Unauthorized (neautorizat)
- 404 Not Found (locația este deconectată de la cloud)
- 405 Method Not Allowed (metodă nepermisă)
- 500 Internal Server Error (eroare internă a serverului)

### Obținerea valorilor unui dispozitiv

Returnează toate valorile actuale ale dispozitivului indicat, inclusiv ID-urile și numele tipurilor. Valorile sunt numerice (tip double). Unele proprietăți sunt doar pentru citire.

Cererile frecvente (la intervale sub 500 ms) pot returna valori din cache; comparați marcajele de timp (timestamp) doar pentru egalitate.

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

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

**Parametri**: ID-ul dispozitivului în calea URL sau în corpul JSON

**Răspuns**:
```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
}
```

**Erori HTTP**:
- 401 Unauthorized (neautorizat)
- 403 Forbidden (dispozitivul nu este expus)
- 404 Not Found (locația este deconectată de la cloud)
- 405 Method Not Allowed (metodă nepermisă)
- 500 Internal Server Error (eroare internă a serverului)

### Obținerea valorilor mai multor dispozitive

Returnează simultan toate valorile actuale ale mai multor dispozitive. Consumă mai puțină lățime de bandă decât cererile individuale. Necesită Core 2021.3 sau mai nou.

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

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

**Răspuns**:
```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
}
```

**Erori HTTP**:
- 401 Unauthorized (neautorizat)
- 403 Forbidden (dispozitivul nu este expus)
- 404 Not Found (locația este deconectată de la cloud)
- 405 Method Not Allowed (metodă nepermisă)
- 500 Internal Server Error (eroare internă a serverului)

### Obținerea tuturor valorilor tuturor dispozitivelor

Returnează într-o singură cerere starea completă a tuturor dispozitivelor expuse. Necesită Core 2021.3 sau mai nou.

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

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

**Răspuns**:
```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
}
```

**Erori HTTP**:
- 401 Unauthorized (neautorizat)
- 403 Forbidden (dispozitivul nu este expus)
- 404 Not Found (locația este deconectată de la cloud)
- 405 Method Not Allowed (metodă nepermisă)
- 500 Internal Server Error (eroare internă a serverului)

### Obținerea unei singure valori a dispozitivului

Returnează o singură valoare a dispozitivului, fără a fi necesară procesarea JSON. Ideal pentru implementări simple. Răspunsul numeric (double) este formatat ca șir de caractere, cu punct zecimal.

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

**Parametri**: ID-ul dispozitivului în cale, ID-ul tipului de valoare și tokenul în parametrii de interogare

**Răspuns**:
```text
1.27
```

Pentru valorile necunoscute se returnează `NaN`. Cererile frecvente (la intervale sub 500 ms) pot returna date din cache.

**Erori HTTP**:
- 401 Unauthorized (neautorizat)
- 403 Forbidden (dispozitivul nu este expus)
- 404 Not Found (locația este deconectată de la cloud)
- 405 Method Not Allowed (metodă nepermisă)
- 500 Internal Server Error (eroare internă a serverului)

### Setarea valorii dispozitivului

Modifică una sau mai multe valori ale dispozitivului, după identificatorul tipului. Valorile neindicate rămân neschimbate. Tip numeric (double).

Modificările frecvente (la intervale sub 500 ms) duc la răspunsul HTTP 503.

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

Se pot seta simultan până la trei valori.

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

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

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

**Erori HTTP**:
- 401 Unauthorized (neautorizat)
- 403 Forbidden (dispozitivul nu este expus)
- 404 Not Found (locația este deconectată de la cloud)
- 405 Method Not Allowed (metodă nepermisă)
- 500 Internal Server Error (eroare internă a serverului)
- 503 Service Unavailable (valorile se setează prea des; reîncercați mai târziu)

## Webhook

Funcția webhook trimite modificările de stare ale dispozitivelor expuse prin HTTP POST la un URL configurat, în rețeaua LAN sau pe internet. Permite o sincronizare mai eficientă decât interogarea periodică.

**Se trimite direct, nu prin cloud**: webhook-ul este un HTTP POST *de ieșire*, pe care unitatea Core îl trimite direct la URL-ul configurat; datele nu trec niciodată prin serverele cloud TapHome. Dacă destinația funcționează în aceeași rețea locală, webhook-ul se livrează local prin LAN, fără să treacă prin internet. Comutatoarele **Activați accesul la cloud** și **Activați accesul local** de pe pagina Expuneți dispozitivele controlează doar apelurile API *de intrare* către unitatea Core; ele nu dezactivează webhook-ul.

**Limitarea frecvenței**: modificările se grupează și se trimit cel mai devreme după aproximativ 350 ms. La schimbări rapide ale valorii se trimite doar ultima modificare; valorile intermediare anterioare se elimină. Trimiterile eșuate nu se repetă.

**Configurare**: aplicația TapHome acceptă trei antete HTTP personalizate ale cererii, în formatul „key: value”.

**Structura datelor**: identică cu formatul răspunsului endpointului `getMultipleDevicesValues`.
