Zoeken
MENU
  • Tik op Home-apps
  • Uitdrukkingen
  • Systeemarchitectuur per projecttype
  • Gebruikers en machtigingen
  • TapHome API

    Met behulp van TapHome API is het mogelijk om TapHome-apparaten te integreren in een applicatie van derden. Bijvoorbeeld Apple Siri spraakbesturing.

    Als u geïnteresseerd bent in directe communicatie met de besturingseenheid binnen LAN of VPN, overweeg dan om te gebruiken

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

    Overzicht

    TapHome API definieert een set functies waarop de ontwikkelaars verzoeken kunnen uitvoeren en reacties kunnen ontvangen. De interactie wordt uitgevoerd via het HTTP-protocol. Een voordeel van een dergelijke benadering is het brede gebruik van HTTP. Daarom kan TapHome API praktisch voor elke programmeertaal worden gebruikt.

    TapHome TapHome API overzicht:

    • U krijgt toegang tot de bron door een HTTP-verzoek naar de TapHome TapHome API server te sturen. De server antwoordt met een antwoord dat de gevraagde gegevens bevat
    • Alle bronnen zijn te vinden op https://cloudapi.taphome.com/api/cloudapi/v1/
    • Alle bronnen kunnen verschillende HTTP-statuscodes retourneren (bijv. HTTP-statuscode 200 voor een succesvolle reactie of HTTP-statuscode 400 voor het slechte verzoek)
    • U vraagt een bepaalde bron aan door een bepaald pad toe te voegen aan de basis-URL die de bron aangeeft
    • Standaard swagger-documentatie samen met testomgeving wordt geleverd
    • Alle antwoorden zijn in Json-formaat en gebruiken de UTF-8-tekencodering

    TapHome Core versie 2021.3 introduceert een nieuwe functie: TapHome API via het lokale netwerk. Lokale toegang tot Core vermindert de communicatielatentie en maakt het systeem onafhankelijk van een internetverbinding. De specificatie (authenticatie, verzoeken, antwoorden) is identiek aan de cloudversie. TapHome API via het lokale netwerk ondersteunt alleen het HTTP-protocol en bevat niet de Swagger-gebruikersinterface.

    Authenticatie van TapHome API verzoeken

    TapHome TapHome API gebruikt een aangepast HTTP-schema op basis van een basis-toegangsverificatie. Het vereist geen cookies, sessie-ID of inlogpagina's. TapHome TapHome API echter geen login: wachtwoordpaar, maar een gedeeld geheim genaamd token.

    Aangepaste authenticatie HTTP-header wordt als volgt gevormd:

    Authorization: TapHome {token}

    Voorbeeld van authenticatie HTTP-verzoek:

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

    Voorbeeld met curl:

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

    Wanneer het systeem een geverifieerd verzoek ontvangt, haalt het het token op dat u beweert te hebben en gebruikt het om de locatie van een TapHome Control-eenheid te identificeren. Als het token niet overeenkomt met TapHome-records, wordt het verzoek verwijderd en reageert het systeem met een foutbericht (meestal HTTP 401).

    Als alternatief is het ook mogelijk om het token in de queryparameters te plaatsen (alleen voor HTTP GET-aanroepen). We raden u ten zeerste aan om dergelijke URL's niet aan derden te verstrekken, omdat het token kan worden gebruikt voor toegang tot en controle over elk apparaat dat door de besturingseenheid wordt weergegeven.

    Hoe u het token kunt krijgen

    Ga in de TapHome-app naar Instellingen → Apparaten TapHome API → TapHome API → Token. Door op de pijl naast het token te klikken, wordt deze naar het klembord gekopieerd.

    In het geval dat het token gecompromitteerd is en moet worden ingetrokken, kan een nieuw token worden gegenereerd met behulp van de TapHome-app. Er is altijd maar één token actief.

    TapHome API Referentie

    Ontvang locatiegegevens

    Krijgt locatie-informatie van de besturingseenheid. Gebruik deze oproep om te controleren of de locatie online is.

    Variant 1
    GET /api/CloudApi/v1/location

    Parameters: geen

    Variant 2
    POST /api/CloudApi/v1/location

    Parameters: geen

    Voorbeeld reactie:

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

    Mogelijke HTTP-statusfouten:

    • 401 Niet geautoriseerd

    • 404 niet gevonden - de locatie is niet verbonden met de cloud

    • 405-methode niet toegestaan - de query of de parameters zijn ongeldig

    • 500 Interne server fout

    Ontdek apparaten

    Laat apparaten blootleggen door de besturingseenheid. Voor elk apparaat wordt een lijst met waardetypes geleverd (met waardetype id en waardetype naam). Sommige waarden zijn mogelijk alleen-lezen (bijv. Apparaatstatus).

    Om apparaatwaarden in te stellen, moet u de waardeTypeId opgeven om de apparaateigenschap te identificeren die wordt ingesteld.

    Variant 1
    GET /api/CloudApi/v1/discovery

    Parameters: geen

    Variant 2
    POST /api/CloudApi/v1/discovery

    Parameters: geen

    Voorbeeld reactie:

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

    Mogelijke HTTP-statusfouten:

    • 401 Niet geautoriseerd

    • 404 niet gevonden - de locatie is niet verbonden met de cloud

    • 405-methode niet toegestaan - de query of de parameters zijn ongeldig

    • 500 Interne server fout

    Krijg apparaatwaarde

    Hiermee worden alle huidige waarden voor een bepaald apparaat en hun typen opgehaald. De waarde-elementen bestaan uit waardetype id, waardetype naam en de werkelijke waarde. Sommige waarden zijn mogelijk alleen-lezen (bijv. Apparaatstatus).

    Om apparaatwaarden in te stellen, moet u de waardeTypeId opgeven om de apparaateigenschap te identificeren die wordt ingesteld.

    Het waardetype is altijd een getal (dubbel).

    Te vaak dezelfde waarde opvragen (minder dan 500 ms tussen de verzoeken) kan een gecachte waarde retourneren in plaats van elke keer de huidige waarde van de besturingseenheid op te halen. Antwoorden met gelijke tijdstempelvelden verwijzen naar dezelfde waarde. Ga er niet vanuit dat de tijdstempelwaarde altijd groeit, deze moet alleen worden vergeleken voor gelijkheid.

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

    Parameters: apparaat-ID in url-pad (bijv. "1")

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

    Parameters:

    {
      "deviceId": 1
    }

    Voorbeeld reactie:

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

    Mogelijke HTTP-statusfouten:

    • 401 Niet geautoriseerd

    • 403 Verboden - het apparaat is niet zichtbaar

    • 404 niet gevonden - de locatie is niet verbonden met de cloud

    • 405-methode niet toegestaan - de query of de parameters zijn ongeldig

    • 500 Interne server fout

    Waarden van meerdere apparaten ophalen

    Krijgt alle huidige waarden voor bepaalde apparaten en hun typen. De responswaarde-elementen bestaan uit Waardetype-ID, Waardetypenaam en de werkelijke waarde. Sommige waarden kunnen alleen-lezen zijn (bijv. Apparaatstatus). Waardetype-ID is optioneel. Deze functie vereist Core versie 2021.3 of nieuwer.

    Overweeg om meerdere waarden tegelijk te krijgen met een enkele API-aanroep om bandbreedte te besparen en een redelijk aantal verzoeken naar de TapHome API server te sturen.


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

    Parameters:

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

    Voorbeeld reactie:

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

    Mogelijke HTTP-statusfouten:

    • 401 Niet geautoriseerd

    • 403 Verboden - het apparaat is niet zichtbaar

    • 404 niet gevonden - de locatie is niet verbonden met de cloud

    • 405-methode niet toegestaan - de query of de parameters zijn ongeldig

    • 500 Interne server fout

    Krijg alle waarden van alle apparaten

    Krijgt alle huidige waarden van alle apparaten tegelijk. De responswaarde-elementen bestaan uit een waardetype-ID, een waardetypenaam en een werkelijke waarde. Sommige waarden kunnen alleen-lezen zijn (bijv. Apparaatstatus). Voor deze functie is Core versie 2021.3 of hoger vereist.

    Overweeg om meerdere waarden tegelijk te krijgen met een enkele API-aanroep om bandbreedte te besparen en een redelijk aantal verzoeken naar de TapHome API server te sturen.

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

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

    Voorbeeld reactie:

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

    Mogelijke HTTP-statusfouten:

    • 401 Niet geautoriseerd

    • 403 Verboden - het apparaat is niet zichtbaar

    • 404 niet gevonden - de locatie is niet verbonden met de cloud

    • 405-methode niet toegestaan - de query of de parameters zijn ongeldig

    • 500 Interne server fout

    Krijg één apparaatwaarde

    Krijgt één huidige waarde voor een bepaald apparaat en waardetype-id als tekst - het vereist geen JSON-verwerking. Deze functie is ideaal voor eenvoudige integraties. Normaal gesproken neemt u het token ook op in de queryreeks, dus alle benodigde parameters staan in de url en het instellen van de HTTP-headers is niet nodig.

    Het antwoord is altijd een getal (dubbel), opgemaakt als tekenreeks met decimaalteken en zonder scheidingstekens voor duizendtallen of wetenschappelijke notatie. Als de waarde onbekend is, is het antwoord NaN.

    Te vaak dezelfde waarde opvragen (minder dan 500 ms tussen de verzoeken) kan een gecachte waarde retourneren in plaats van elke keer de huidige waarde van de besturingseenheid op te halen.

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

    Parameters: apparaat-ID in url-pad (bijv. "1") queryparameters - waardetype id (bijv. "42")

    Voorbeeld reactie:

    1.27

    Mogelijke HTTP-statusfouten:

    • 401 Niet geautoriseerd

    • 403 Verboden - het apparaat is niet zichtbaar

    • 404 niet gevonden - de locatie is niet verbonden met de cloud

    • 405-methode niet toegestaan - de query of de parameters zijn ongeldig

    • 500 Interne server fout

    Stel de apparaatwaarde in

    Stelt een of meer waarden van een apparaat in met bepaalde typen. De waarden van andere apparaten blijven ongewijzigd.

    Het waardetype is altijd een getal (dubbel).

    Het te vaak instellen van dezelfde waarde (minder dan 500 ms tussen de verzoeken) resulteert in een HTTP 503-fout.

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

    Parameters: apparaat-ID in url-pad (bijv. "2") queryparameters - maximaal drie waarden en hun typen (bijv. valueTypeId=46&waarde=0.1&valueTypeId2=10&waarde2=0.2)

    Deze functievariant is ideaal voor eenvoudige integraties, er is geen JSON-verwerking voor nodig. Normaal gesproken neemt u het token ook op in de queryreeks, dus alle benodigde parameters staan in de url en het instellen van de HTTP-headers is niet nodig.

    Variant 2
    POST /api/CloudApi/v1/setDeviceValue

    Parameters:

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

    Voorbeeld reactie:

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

    Mogelijke HTTP-statusfouten:

    • 401 Niet geautoriseerd

    • 403 Verboden - het apparaat is niet zichtbaar

    • 404 niet gevonden - de locatie is niet verbonden met de cloud

    • 405-methode niet toegestaan - de query of de parameters zijn ongeldig

    • 500 Interne server fout

    • 503 Service niet beschikbaar - te vaak ingestelde waarde-aanvragen. Probeer het later nog eens.