Lompat ke konten
Beranda » Dokumentasi Taphome » Integrasi TapHome dengan Sistem Lain » TapHome API

TapHome API

Dengan TapHome API, Anda dapat menghubungkan perangkat TapHome ke berbagai aplikasi pihak ketiga, termasuk kendali suara dengan Apple Siri.

Jika Anda ingin berkomunikasi langsung dengan Control Unit dalam jaringan lokal (LAN) atau VPN, maka Integration Protocol berikut dapat digunakan: AMX, Lutron, Crestron, Control4, Clipsal.

TapHome API – Gambaran Umum

TapHome API menyediakan fungsi yang memungkinkan pengembang mengirim permintaan dan menerima respons melalui protokol HTTP, sehingga kompatibel dengan hampir semua bahasa pemrograman.

Cara Mengakses API

  • Kirim HTTP request ke server TapHome API.
  • Server merespons dengan data yang diminta.
  • Semua sumber daya dapat diakses melalui:
    https://api.taphome.com/api/TapHomeApi/v1/.
  • API dapat mengembalikan berbagai status HTTP, misalnya:
    • 200 → Permintaan sukses
    • 400 → Permintaan tidak valid

Struktur Permintaan

Fitur Baru (TapHome Core 2021.3)

  • TapHome API dapat diakses via jaringan lokal (LAN), mengurangi latensi komunikasi dan membuat sistem independen dari koneksi internet.
  • Spesifikasi autentikasi, permintaan, dan respons tetap identik dengan versi cloud.
  • API lokal hanya mendukung HTTP, tanpa antarmuka pengguna Swagger.

ℹ️ Gunakan TapHome API lokal jika memungkinkan.
Waktu respons lebih cepat, dan kemungkinan kegagalan permintaan jauh lebih rendah dibandingkan dengan cloud, di mana data harus berpindah dari rumah ke cloud lalu kembali melalui internet. Saat menggunakan TapHome API lokal, unit Core harus memiliki alamat IP tetap atau menggunakan mDNS.

Otentikasi Permintaan TapHome API

TapHome API menggunakan skema HTTP kustom berdasarkan Basic access authentication tanpa memerlukan cookie, session identifier, atau halaman login.

Namun, TapHome API tidak menggunakan pasangan login/password, melainkan token rahasia bersama untuk otentikasi.

Custom authentication HTTP header is formed as follows:

Authorization: TapHome {token}

Example of authentication HTTP request:

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

Example using curl:

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

Proses Autentikasi dalam TapHome API

Ketika sistem menerima permintaan yang diautentikasi, ia akan mengambil token yang diklaim oleh pengguna dan menggunakannya untuk mengidentifikasi lokasi unit TapHome Control.

  • Jika token tidak cocok dengan catatan TapHome, maka permintaan akan dihentikan, dan sistem mengembalikan pesan kesalahan (biasanya HTTP 401).

Alternatif Autentikasi dengan Query Parameter

  • Token dapat dimasukkan dalam parameter query untuk permintaan HTTP GET saja.
  • Peringatan: Disarankan tidak membagikan URL ini kepada pihak ketiga, karena token dapat digunakan untuk mengakses dan mengontrol perangkat yang diekspos oleh Control unit.

Cara Mendapatkan Token di TapHome API

  1. Buka aplikasi TapHome, lalu masuk ke Settings → Expose Devices → TapHome API.
  2. Klik menu konteks (tiga titik di pojok kanan atas).
  3. Pilih opsi “Create new access token” untuk menghasilkan token baru.
  4. Peringatan: Setiap kali Anda membuat token baru, semua perintah URL lama akan berhenti berfungsi.
  5. Klik panah di sebelah token, dan wizard akan menyalin token secara otomatis ke clipboard.

Jika token telah dikompromikan dan perlu dicabut, Anda dapat menghasilkan token baru menggunakan TapHome.
Catatan penting: Hanya satu token yang aktif dalam sistem pada satu waktu, sehingga token lama akan otomatis tidak berlaku setelah pembuatan token baru.

TapHome API Reference

Get Location Info

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

Variant 1
GET /api/TapHomeApi/v1/location

Parameters: none

Variant 2
POST /api/TapHomeApi/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/TapHomeApi/v1/discovery

Parameters: none

Variant 2
POST /api/TapHomeApi/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 values of multiple devices

Gets all current values for given devices and their types. The response value elements are comprised of Value Type ID, Value Type Name and the actual value. Some values may be read-only (e.g. Device Status). Value Type ID is optional. This function requires Core version 2021.3 or newer.

Consider getting multiple values at once with a single API call to save bandwidth and send a reasonable number of requests to the TapHome API server.


POST ​/api​/CloudApi​/v1​/getMultipleDevicesValue​s

Parameters:

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

Example response:

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

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 all values of all devices

Gets all current values of all devices at once. The response value elements consist of a value type id, a value type name, and an actual value. Some values may be read-only (eg Device Status). This feature requires Core version 2021.3 or later.

Consider getting multiple values at once with a single API call to save bandwidth and send a reasonable number of requests to the TapHome API server.

Variant 1
GET ​/api​/CloudApi​/v1​/getAllDevicesValue​s

Variant 2
POST ​/api​/CloudApi​/v1​/getAllDevicesValue​s

Example response:

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

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/TapHomeApi/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/TapHomeApi/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.

Webhook

Fungsi Webhook dalam TapHome API

Webhook digunakan untuk mengirim perubahan nilai perangkat yang diekspos melalui protokol HTTP. Webhook memanggil URL yang telah dikonfigurasi dan mengirimkan status terbaru perangkat, baik dalam jaringan LAN maupun melalui internet.

Keuntungan Menggunakan Webhook

  • Sinkronisasi lebih efisien dibandingkan polling berkala.
  • Respons lebih cepat, karena sistem hanya mengirim data ketika terjadi perubahan.
  • Dapat dikombinasikan dengan polling berkala dalam interval panjang (misalnya setiap beberapa menit) sebagai cadangan jika webhook gagal.
  • Hanya satu webhook tersedia, baik untuk API lokal maupun cloud.

Batasan Pengiriman Data

  • Webhook diaktifkan maksimal setiap 300 ms, menghindari overload sistem penerima atau pelanggaran kebijakan fair-use.
  • Jika nilai perangkat berubah dalam 300 ms, hanya nilai terakhir yang dikirim.
    • Contoh: Jika perubahan terjadi dari 1 → 2 → 3 … → 100, maka webhook hanya mengirim nilai 100.
  • Jika pengiriman gagal, webhook tidak melakukan retry otomatis.

Format dan Konfigurasi Webhook

  • Metode HTTP: Webhook selalu menggunakan HTTP POST.
  • Header HTTP Kustom: Aplikasi memungkinkan konfigurasi hingga tiga header request kustom dalam format "key: value".
  • Struktur Data: Data yang dikirim memiliki format identik dengan pemanggilan “getMultipleDevicesValues”.