TapHome API

En utilisant TapHome API il est possible d'intégrer des appareils TapHome dans n'importe quelle application tierce. Par exemple, la commande vocale Apple Siri.

Si vous êtes intéressé par une communication directe avec l'unité de contrôle au sein d'un LAN ou d'un VPN, veuillez envisager d'utiliser

Integration Protocol (AMX, Lutron, Crestron, Control4, Clipsal)

Aperçu

TapHome API définit un ensemble de fonctions auxquelles les développeurs peuvent exécuter des requêtes et recevoir des réponses. L'interaction est effectuée via le protocole HTTP. Un avantage d'une telle approche est la large utilisation de HTTP. C'est pourquoi TapHome API peut être utilisé pratiquement pour n'importe quel langage de programmation.

Présentation de TapHome TapHome API:

Vous accédez à la ressource en envoyant une requête HTTP au serveur TapHome TapHome API . Le serveur répond avec une réponse qui contient les données que vous avez demandées
Toutes les ressources se trouvent sur https://api.taphome.com/api/TapHomeApi/v1/
Toutes les ressources peuvent renvoyer des codes d'état HTTP différents (par exemple, le code d'état HTTP 200 pour une réponse réussie ou le code d'état HTTP 400 pour la mauvaise demande)
Vous demandez une ressource particulière en ajoutant un chemin particulier à l'URL de base qui spécifie la ressource
La documentation standard de swagger ainsi que l'environnement de test sont fournis
Toutes les réponses sont au format Json et utilisent l'encodage de caractères UTF-8

TapHome Core version 201.3 introduit une nouvelle fonctionnalité : TapHome API via le réseau local. L'accès à Core localement diminue la latence de communication et rend le système indépendant de la connexion Internet. La spécification (authentification, requêtes, réponses) est identique à la version cloud. TapHome API sur le réseau local ne prend en charge que le protocole HTTP et n'inclut pas l'interface utilisateur Swagger.

Authentification des TapHome API

TapHome TapHome API utilise un schéma HTTP personnalisé basé sur une authentification d'accès de base. Il ne nécessite pas de cookies, d'identifiant de session ni de pages de connexion. TapHome TapHome API n'utilise cependant pas la paire login: password, mais un secret partagé appelé token.

L'en-tête HTTP d'authentification personnalisée est formé comme suit:

Authorization: TapHome {token}

Exemple de requête HTTP d'authentification:

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

Exemple utilisant curl:

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

Lorsque le système reçoit une demande authentifiée, il récupère le jeton que vous prétendez avoir et l'utilise pour identifier un emplacement d'unité de contrôle TapHome. Si le jeton ne correspond pas aux enregistrements TapHome, la demande est abandonnée et le système répond avec un message d'erreur (généralement HTTP 401).

Alternativement, il est également possible de placer le jeton dans les paramètres de requête (pour les appels HTTP GET uniquement). Nous vous suggérons fortement de ne pas fournir de telles URL à des tiers car le jeton peut être utilisé pour accéder et contrôler tout appareil exposé par l'unité de contrôle.

Comment obtenir le jeton

Dans l'application TapHome, accédez à Paramètres → Exposer les appareils → TapHome API. Dans le menu contextuel (trois points en haut à droite), utilisez la fonction Créer un nouveau jeton d'accès. Attention - chaque fois que vous générez un nouveau jeton, les commandes URL d'origine cessent de fonctionner. Cliquez sur la flèche à côté du jeton et l'assistant le copiera dans le presse-papiers.

**Si le jeton a été compromis et doit être révoqué, un nouveau jeton peut être généré en utilisant TapHome. Un seul jeton est toujours actif.

TapHome API Référence

Obtenir des informations de localisation

Obtient les informations de localisation de l'unité de contrôle. Utilisez cet appel pour vérifier si l'emplacement est en ligne.

Variant 1
GET /api/TapHomeApi/v1/location

Paramètres: aucun

Variant 2
POST /api/TapHomeApi/v1/location

Paramètres: aucun

Exemple de réponse:

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

Erreurs d'état HTTP possibles:

401 Non autorisé
404 Not Found - l'emplacement n'est pas connecté au cloud
405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides
500 Erreur de serveur interne

Découvrir les appareils

Obtient les appareils exposés par l'unité de contrôle. Pour chaque périphérique, une liste de types de valeur est fournie (contenant l'identifiant du type de valeur et le nom du type de valeur). Certaines valeurs peuvent être en lecture seule (par exemple, l'état de l'appareil).

Afin de définir les valeurs de périphérique, vous devez fournir le valueTypeId pour identifier la propriété de périphérique qui sera définie.

Variant 1
GET /api/TapHomeApi/v1/discovery

Paramètres: aucun

Variant 2
POST /api/TapHomeApi/v1/discovery

Paramètres: aucun

Exemple de réponse:

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

Erreurs d'état HTTP possibles:

401 Non autorisé
404 Not Found - l'emplacement n'est pas connecté au cloud
405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides
500 Erreur de serveur interne

Obtenir la valeur de l'appareil

Obtient toutes les valeurs actuelles pour un appareil donné et leurs types. Les éléments de valeur sont composés de l'identifiant du type de valeur, du nom du type de valeur et de la valeur réelle. Certaines des valeurs peuvent être en lecture seule (par exemple, l'état de l'appareil).

Afin de définir les valeurs de périphérique, vous devez fournir le valueTypeId pour identifier la propriété de périphérique qui sera définie.

Le type de valeur est toujours un nombre (double).

Demander la même valeur trop fréquemment (moins de 500 ms entre les requêtes) peut renvoyer une valeur mise en cache au lieu de récupérer à chaque fois la valeur actuelle de l'unité de contrôle. Les réponses avec des champs d'horodatage égaux se réfèrent à la même valeur. Ne supposez pas que la valeur d'horodatage augmente constamment, elle doit être comparée uniquement pour l'égalité.

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

Paramètres: identifiant de l'appareil dans le chemin de l'URL (par exemple, «1»)

Variant 2
POST /api/CloudApi/v1/getDeviceValue

Paramètres:

{
  "deviceId": 1
}

Exemple de réponse:

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

Erreurs d'état HTTP possibles:

401 Non autorisé
403 Interdit - l'appareil n'est pas exposé
404 Not Found - l'emplacement n'est pas connecté au cloud
405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides
500 Erreur de serveur interne

Obtenir les valeurs de plusieurs appareils

Obtient toutes les valeurs actuelles pour les appareils donnés et leurs types. Les éléments de valeur de réponse sont constitués de l'ID du type de valeur, du nom du type de valeur et de la valeur réelle. Certaines valeurs peuvent être en lecture seule (par exemple, État de l'appareil). L'ID du type de valeur est facultatif. Cette fonction nécessite Core version 201.3 ou plus récente.

Envisagez d'obtenir plusieurs valeurs à la fois avec un seul appel d'API pour économiser de la bande passante et envoyer un nombre raisonnable de requêtes au serveur TapHome API

POST /api/CloudApi/v1/getMultipleDevicesValues

Paramètres:

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

Exemple de réponse:

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

Erreurs d'état HTTP possibles:

401 Non autorisé
403 Interdit - l'appareil n'est pas exposé
404 Not Found - l'emplacement n'est pas connecté au cloud
405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides
500 Erreur de serveur interne

Obtenez toutes les valeurs de tous les appareils

Obtient toutes les valeurs actuelles de tous les appareils à la fois. Les éléments de valeur de réponse se composent d'un identifiant de type de valeur, d'un nom de type de valeur et d'une valeur réelle. Certaines valeurs peuvent être en lecture seule (par exemple, État de l'appareil). Cette fonctionnalité nécessite Core version 201.3 ou ultérieure.

Envisagez d'obtenir plusieurs valeurs à la fois avec un seul appel d'API pour économiser de la bande passante et envoyer un nombre raisonnable de requêtes au serveur TapHome API

Variant 1
GET /api/CloudApi/v1/getAllDevicesValues

Variant 2
POST /api/CloudApi/v1/getAllDevicesValues

Exemple de réponse:

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

Erreurs d'état HTTP possibles:

401 Non autorisé
403 Interdit - l'appareil n'est pas exposé
404 Not Found - l'emplacement n'est pas connecté au cloud
405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides
500 Erreur de serveur interne

Obtenez une valeur d'appareil

Obtient une valeur actuelle pour un appareil donné et un identifiant de type de valeur sous forme de texte - il ne nécessite aucun traitement JSON. Cette fonction est idéale pour les intégrations simples. En règle générale, vous incluez également le jeton dans la chaîne de requête, de sorte que tous les paramètres nécessaires sont fournis dans l'URL et la définition des en-têtes HTTP n'est pas nécessaire.

La réponse est toujours un nombre (double), formaté en chaîne en utilisant la virgule décimale et en n'utilisant aucun millier de séparateurs ni la notation scientifique. Si la valeur est inconnue, la réponse est NaN.

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

Paramètres: identifiant de l'appareil dans le chemin de l'URL (par exemple, «1») paramètres de requête - id du type de valeur (par exemple «42»)

Exemple de réponse:

1.27

Erreurs d'état HTTP possibles:

401 Non autorisé
403 Interdit - l'appareil n'est pas exposé
404 Not Found - l'emplacement n'est pas connecté au cloud
405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides
500 Erreur de serveur interne

Définir la valeur de l'appareil

Définit une ou plusieurs valeurs d'un périphérique avec des types donnés. Les valeurs des autres appareils restent inchangées.

Le type de valeur est toujours un nombre (double).

La définition trop fréquente de la même valeur (moins de 500 ms entre les requêtes) entraîne une erreur HTTP 503.

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

Paramètres: identifiant de l'appareil dans le chemin de l'URL (par exemple "2") paramètres de requête - jusqu'à trois valeurs et leurs types (par exemple valueTypeId=46&value=0.1&valueTypeId2=10&value2=0.2)

Cette variante de fonction est idéale pour les intégrations simples, elle ne nécessite aucun traitement JSON. En règle générale, vous incluez également le jeton dans la chaîne de requête, de sorte que tous les paramètres nécessaires sont fournis dans l'URL et la définition des en-têtes HTTP n'est pas nécessaire.

Variant 2
POST /api/TapHomeApi/v1/setDeviceValue

Paramètres:

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

Exemple de réponse:

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

Erreurs d'état HTTP possibles:

401 Non autorisé
403 Interdit - l'appareil n'est pas exposé
404 Not Found - l'emplacement n'est pas connecté au cloud
405 Méthode non autorisée - la requête ou les paramètres ne sont pas valides
500 Erreur de serveur interne
503 Service non disponible - demandes de valeur de consigne trop fréquentes. Réessayez plus tard.