Hľadaj
MENU
  • Výrazy
  • Architektúra systému podľa typu projektu
  • Používatelia a povolenia
  • Cloud API

    Using Cloud API it is possible to integrate TapHome devices into any 3rd party application. For example Apple Siri voice control.

    If you are interested in direct communication with Control unit within LAN or VPN, please consider using Integration Protocol (AMX, Lutron, Crestron, Control4, Clipsal)

    What is the Cloud API?

    Cloud API defines a set of functions to which the developers can perform requests and receive responses. The interaction is performed via the HTTP protocol. An advantage of such an approach is the wide usage of HTTP. That is why Cloud API can be used practically for any programming language.

    Common characteristics of TapHome Cloud API resources are as follows:

    • You access the resource by sending an HTTP request to the TapHome Cloud API server. The server replies with a response that contains the data you requested

    • All resources are located at https://cloudapi.taphome.com/api/cloudapi/v1/

    • All resources may return different HTTP status codes (e.g., HTTP Status Code 200 for success response or HTTP Status Code 400 for the bad request)

    • You request a particular resource by adding a particular path to the base URL that specifies the resource

    • Standard swagger documentation together with testing environment is provided at https://cloudapi.taphome.com/swagger

    • All responses are in Json format and use the UTF-8 character encoding

    Authenticating Cloud API Requests

    TapHome Cloud API uses a custom HTTP scheme based on a Basic access authentication. It doesn't require cookies, session identifier nor login pages. TapHome Cloud API however does not use login:password pair, but a shared secret called token.

    Custom authentication HTTP header is formed as follows:

    Authorization: TapHome {token}

    Example of authentication HTTP request:

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

    Example using curl:

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

    When the system receives an authenticated request, it fetches the token that you claim to have and uses it to identify a TapHome Control unit location. If the token does not match TapHome records, the request is dropped and the system responds with an error message (typically HTTP 401).

    Alternatively, it is also possible to put the token into the query parameters (for HTTP GET calls only). We strongly suggest not to provide such urls to third parties because the token may be used to access and control any device exposed by the Control unit.

    How to get the token

    In the TapHome app, go to Settings → Expose Devices → Cloud API → Token. Clicking the arrow next to the token Guid copies it to the clipboard.

    In case the token has been compromised and has to be revoked, a new token can be generated using the TapHome app. There is always only one token active.

    Cloud API Reference

    Get Location Info

    Gets Control unit location info. Use this call to check if the location is online.

    Variant 1
    GET /api/CloudApi/v1/location

    Parameters: none

    Variant 2
    POST /api/CloudApi/v1/location

    Parameters: none

    Example response:

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

    Possible HTTP status errors:

    • 401 Unauthorized

    • 404 Not Found - the location is not connected to cloud

    • 405 Method Not Allowed - the query or the parameters are invalid

    • 500 Internal Server Error

    Discover Devices

    Gets devices exposed by the Control unit. For each device a list of value types is provided (containing value type id and value type name). Some of the values may be read-only (e.g. Device Status).

    In order to set device values you have to provide the valueTypeId to identify the device property which will be set.

    Variant 1
    GET /api/CloudApi/v1/discovery

    Parameters: none

    Variant 2
    POST /api/CloudApi/v1/discovery

    Parameters: none

    Example response:

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

    Possible HTTP status errors:

    • 401 Unauthorized

    • 404 Not Found - the location is not connected to cloud

    • 405 Method Not Allowed - the query or the parameters are invalid

    • 500 Internal Server Error

    Get Device Value

    Gets all current values for a given device and their types. The value elements are comprised of value type id, value type name and the actual value. Some of the values may be read-only (e.g. Device Status).

    In order to set device values you have to provide the valueTypeId to identify the device property which will be set.

    The value type is always a number (double).

    Requesting the same value too frequently (less than 500 ms between the requests) may return a cached value instead of fetching each time the current value from the Control unit. Responses with equal timestamp fields refer to the same value. Do not assume the timestamp value is always growing, it should be compared for equality only.

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

    Parameters: device id in url path (e. g. “1”)

    Variant 2
    POST ​/api​/CloudApi​/v1​/getDeviceValue​

    Parameters:

    {
      "deviceId": 1
    }

    Example response:

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

    Possible HTTP status errors:

    • 401 Unauthorized

    • 403 Forbidden - the device is not exposed

    • 404 Not Found - the location is not connected to cloud

    • 405 Method Not Allowed - the query or the parameters are invalid

    • 500 Internal Server Error

    Get One Device Value

    Gets one current value for a given device and value type id as text - it does not require any JSON processing. This function is ideal for simple integrations. Typically, you’d also include the token in the query string as well, so all necessary parameters are provided in the url and setting the HTTP headers is not necessary.

    The reply is always a number (double), formatted to string using decimal point and not using any thousand separators nor the scientific notation. If the value is unknown, the reply is NaN.

    Requesting the same value too frequently (less than 500 ms between the requests) may return a cached value instead of fetching each time the current value from the Control unit.

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

    Parameters: device id in url path (e. g. “1”)
    query parameters - value type id (e. g. “42”)

    Example response:

    1.27

    Possible HTTP status errors:

    • 401 Unauthorized

    • 403 Forbidden - the device is not exposed

    • 404 Not Found - the location is not connected to cloud

    • 405 Method Not Allowed - the query or the parameters are invalid

    • 500 Internal Server Error

    Set Device Value

    Sets one or more values of a device with given types. Other device's values stay untouched.

    The value type is always a number (double).

    Setting the same value too frequently (less than 500 ms between the requests) results into HTTP 503 error.

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

    Parameters: device id in url path (e.g. “2”)
    query parameters - up to three values and their types (e.g. valueTypeId=46&value=0.1&valueTypeId2=10&value2=0.2)

    This function variant is ideal for simple integrations, it does not require any JSON processing. Typically, you’d also include the token in the query string as well, so all necessary parameters are provided in the url and setting the HTTP headers is not necessary.

    Variant 2
    POST /api/CloudApi/v1/setDeviceValue

    Parameters:

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

    Example response:

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

    Possible HTTP status errors:

    • 401 Unauthorized

    • 403 Forbidden - the device is not exposed

    • 404 Not Found - the location is not connected to cloud

    • 405 Method Not Allowed - the query or the parameters are invalid

    • 500 Internal Server Error

    • 503 Service not available - too frequent set-value requests. Try again later.