Dispositivi Esposti

API TapHome

Integrazione dei dispositivi TapHome in altre applicazioni tramite API. Supporto HTTP, JSON, comunicazione locale e cloud, autenticazione con token Bearer e gestione dei dispositivi.

Panoramica

L’API TapHome consente l’integrazione dei dispositivi TapHome in applicazioni di terze parti tramite richieste HTTP e risposte JSON. Il sistema opera tramite https://api.taphome.com/api/TapHomeApi/v1/.

Le caratteristiche principali includono:

  • Accesso alle risorse basato su HTTP con codici di stato adeguati
  • Documentazione Swagger standard disponibile su https://api.taphome.com/api/doc
  • Risposte JSON codificate in UTF-8
  • Supporto dell’API di rete locale (Core 2021.3+) tramite HTTP senza Swagger UI

Vantaggio della rete locale: l’accesso diretto via LAN/VPN riduce la latenza ed elimina la dipendenza da Internet. Le unità Core richiedono una configurazione IP fissa o mDNS.

Autenticazione

L’API TapHome utilizza un’autenticazione HTTP personalizzata basata su token di tipo bearer (non credenziali username/password).

Formato dell’intestazione

1

Authorization: TapHome {token}

Esempio di richiesta

1
2
3

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

Esempio cURL

1

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

Gestione dei token

I token si trovano nell’app TapHome: Impostazioni → Esponi dispositivi → TapHome API

Utilizza il menu contestuale (tre puntini) per generare nuovi token di accesso. La generazione di nuovi token invalida quelli precedenti. Un’alternativa tramite parametro di query è disponibile solo per le chiamate GET (avviso di sicurezza: evitare di condividere URL contenenti token).

In caso di compromissione di un token è necessaria una rigenerazione immediata; contemporaneamente resta attivo solo un token.

Riferimento API

Recupera informazioni sulla posizione

Recupera i metadati della posizione dell’unità di controllo e ne verifica lo stato di connettività.

Variante 1

1

GET /api/TapHomeApi/v1/location

Variante 2

1

POST /api/TapHomeApi/v1/location

Parametri: Nessuno

Risposta:

1
2
3
4
5

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

Errori HTTP:

  • 401 Non autorizzato
  • 404 Non trovato (posizione scollegata dal cloud)
  • 405 Metodo non consentito
  • 500 Errore interno del server

Scopri dispositivi

Recupera i dispositivi esposti e i relativi tipi di valore supportati, inclusi attributi in sola lettura come lo stato del dispositivo.

Variante 1

1

GET /api/TapHomeApi/v1/discovery

Variante 2

1

POST /api/TapHomeApi/v1/discovery

Parametri: Nessuno

Risposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

{
  "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
}

Errori di stato HTTP:

  • 401 Non autorizzato
  • 404 Non trovato (posizione scollegata dal cloud)
  • 405 Metodo non consentito
  • 500 Errore interno del server

Ottieni valore del dispositivo

Recupera tutti i valori correnti per un dispositivo specificato, inclusi ID e nomi dei tipi. I valori sono numerici (double). Alcune proprietà sono in sola lettura.

Le richieste frequenti (intervalli inferiori a 500 ms) possono restituire valori memorizzati nella cache; confrontare i timestamp solo per l’uguaglianza.

Variante 1

1

GET /api/CloudApi/v1/getDeviceValue/{deviceId}

Variante 2

1

POST /api/CloudApi/v1/getDeviceValue

Parametri: ID del dispositivo nel percorso o nel corpo JSON

Risposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{
  "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
}

Errori di stato HTTP:

  • 401 Non autorizzato
  • 403 Forbidden (dispositivo non esposto)
  • 404 Non trovato (posizione scollegata dal cloud)
  • 405 Metodo non consentito
  • 500 Errore interno del server

Ottieni valori di più dispositivi

Recupera tutti i valori correnti per più dispositivi contemporaneamente. Riduce l’utilizzo della banda rispetto alle richieste individuali. Richiede Core 2021.3 o versioni successive.

1

POST /api/CloudApi/v1/getMultipleDevicesValues

Parametri:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
 "devices": [
    {
      "deviceId": 1,
      "valueTypeId": 7
    },
    {
      "deviceId": 2
    }
  ],
  "timestamp": 855000000000
}

Risposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

{
 "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
}

Errori di stato HTTP:

  • 401 Non autorizzato
  • 403 Forbidden (dispositivo non esposto)
  • 404 Non trovato (posizione scollegata dal cloud)
  • 405 Metodo non consentito
  • 500 Errore interno del server

Ottieni tutti i valori di tutti i dispositivi

Recupera informazioni complete sullo stato di tutti i dispositivi esposti in una singola richiesta. Richiede Core 2021.3 o versioni successive.

Variante 1

1

GET /api/CloudApi/v1/getAllDevicesValues

Variante 2

1

POST /api/CloudApi/v1/getAllDevicesValues

Risposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

{
 "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
}

Errori di stato HTTP:

  • 401 Non autorizzato
  • 403 Forbidden (dispositivo non esposto)
  • 404 Non trovato (posizione scollegata dal cloud)
  • 405 Metodo non consentito
  • 500 Errore interno del server

Ottieni un valore di un singolo dispositivo

Recupera un valore di un singolo dispositivo senza requisiti di elaborazione JSON. Adatto per implementazioni semplici. Risposta numerica (double) formattata come stringa con notazione decimale.

1

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

Parametri: ID del dispositivo nel percorso, ID del tipo di valore e token nella query string

Risposta:

1

1.27

I valori sconosciuti restituiscono NaN. Le richieste frequenti (sotto i 500 ms) possono restituire dati memorizzati nella cache.

Errori di stato HTTP:

  • 401 Non autorizzato
  • 403 Forbidden (dispositivo non esposto)
  • 404 Non trovato (posizione scollegata dal cloud)
  • 405 Metodo non consentito
  • 500 Errore interno del server

Imposta valore del dispositivo

Modifica uno o più valori del dispositivo in base agli identificatori di tipo. I valori non specificati rimangono invariati. Tipo numerico (double).

Modifiche frequenti (intervalli inferiori a 500 ms) producono una risposta HTTP 503.

Variante 1

1

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

Supporta fino a tre assegnazioni di valore contemporanee.

Variante 2

1

POST /api/TapHomeApi/v1/setDeviceValue

Parametri:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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

Risposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

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

Errori di stato HTTP:

  • 401 Non autorizzato
  • 403 Forbidden (dispositivo non esposto)
  • 404 Non trovato (posizione scollegata dal cloud)
  • 405 Metodo non consentito
  • 500 Errore interno del server
  • 503 Servizio non disponibile (frequenza eccessiva delle impostazioni; riprovare più tardi)

Webhook

La funzionalità Webhook consegna i cambiamenti di stato dei dispositivi esposti tramite HTTP POST a un URL configurato all’interno di ambienti LAN o Internet. Consente una sincronizzazione più efficiente rispetto al polling periodico.

Limitazione: si attiva con intervalli massimi di 300 ms. In caso di transizioni rapide dei valori viene inviata solo l’ultima modifica; i valori intermedi precedenti vengono scartati. Le trasmissioni non riuscite non vengono ritentate.

Configurazione: l’app TapHome supporta fino a tre intestazioni HTTP personalizzate nel formato “chiave: valore”.

Struttura dati: identica al formato di risposta dell’endpoint getMultipleDevicesValues.