Home-SmartLink

HomeSmartlink 3rd Party API

API Partners - Intégrez vos systèmes avec Home SmartLink

version 0.3.3 - 21 octobre 2024 : add GetUsers

version 0.3.2 - 07 octobre 2024 : monitoring effacement

version 0.3.1 - 10 aout 2024 : correction orth

version 0.3 - 2 aout 2024 : suggestion d’api pour l’effacement

Constant

  • BaseUrl : The root url of the API. Transmitted when you register as a partner.
  • ClientId : Your unique identifier
  • ClientSecret : A private key generated to authenticate yourself as a partner.

Basic HTTP authentication

When calling the methods from this APi, you must provide an authentication string in the Authorization header.

The value of this string can be calculated using your CLientId and ClientSecret according the the Basic HTTP authentication protocol.

  • join both your clientId and ClientSecret with the character :, ie mycompany:12345667
  • encode the resulted string using Base64 encoding
  • prefix the resulted string with BASIC ie : Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • set this string as the value for the Authorization header field

JSON schemas

AuthDTO

{
    "type": "object",
    "description": "Authorisation response",
    "properties": {
        "type": {
            "type": "string",
            "description": "the auth challenge",
            "default": "BASIC"
        },
        "client": {
            "type": "string",
            "description": "The identifier partner"
        }
    },
    "required": [
        "type",
        "client"
    ]
}

DeviceDTO

{
    "type": "object",
    "description": "Provide information about a single device",
    "properties": {
        "header": {
            "type": "string",
            "description": "the device identifier"
        },
        "roomId": {
            "type": "integer",
            "description": "The room unique identifier in the home"
        },
        "roomName": {
            "type": "string",
            "description": "human readable, user defined room name"
        },
        "softwareVersion": {
            "type": "integer",
            "description": "Carrera soft version number"
        },
        "category": {
            "type": "string",
            "description": "\"None\", \"Heater\", \"TowelDryier\", \"Fireplace\", \"Gateway\", \"Module\", \"Furnace\""
        },
        "online": {
            "type": "boolean",
            "description": "wether or not the device as reported during the last 3 days",
            "default": false
        },
        "mode": {
                "type": "string",
                "description": "the current mode of the device. Can be Stop, Antifreeze, Manual or Prog. This value only appears if the device is online",
                default": null
         },
        "sp": {
                "type": "number",
                "description": "the current setpoint of the device. This value only appears if the device is online",
                default": 0
         },
        "pv": {
                "type": "string",
                "description": "the last read local value by the device. This value only appears if the device is online",
                default": 0
         },
        "lastUpdate": {
                "type": "date",
                "description": "date of the last device report. This value only appears if the device is online",
                default": 0
         },
        "weekSchedule": {
                "type": "Array<Array<RangeDTO>>",
                "description": "Week schedule. This value only appears if the device is online and in Prog mode. The array contains 7 subarray corresponding to the seven days starting by monday",
                default": []
         },
    },
    "required": [
        "header",
        "roomId",
        "roomName",
        "softwareVersion",
        "category",
        "online",
    ]
}

RangeDTO

{
    "type": "object",
    "description": "A start and end time during wich the device is in comfort mode",
    "required": [
        "start" : {
            "type": "int",
            "description": "hour * 60 + min",
            "default": 0
        },
        "end" : {
            "type": "int",
            "description": "hour * 60 + min",
            "default": 0
        },
    ]
}

InvitationDTO

{
    "type": "object",
    "properties": {
        "_id": {
            "type": "string",
             "description": "the homeId"
        },
        "email": {
            "type": "string"
        },
        "creationDate"  {
            "type": "string",
            "description": "the date of creation of the home object"
        }
        "role": {
            "type": "number",
            "description": "2 = admin"
        },

        "city": {
            "type": "string"
        },
        "gatewayEnabled": {
            "type": "boolean",
            "description": "wether the gateway is connected"
        },
        "hasGateway": {
            "type": "boolean",
            "description": "wether the room has a gateway configured"
        },
        "rooms": {
            "type": "array",
            "description": "list the room in the home",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "human readable, user defined room name"
                    },
                    "roomNumber": {
                        "type": "integer",
                        "description": "room identifier"
                    },
                    "deviceCount": {
                        "type": "string",
                        "description": "number of device in the room"
                    },
                    "accessories": {
                        "type": "array",
                        "description": "list of device identifier in the room",
                        "items": {
                            "type": "string"
                        }
                    }
                }
            }
        }
    }
}

DerogationDTO

{
    "type": "object",
    "properties": {
        "homeId": {
            "type": "string"
        },
        "roomId": {
            "type": "number"
        },
        "startTime": {
            "type": "integer",
            "description": "hours * 60 + minutes. i.e 8:30 => 8 x60 + 30 = 510",
            "default": "0",
            "minimum": 0,
            "multipleOf": 5
        },
        "endTime": {
            "type": "integer",
            "description": "hours * 60 + minutes. i.e 8:30 => 8 x60 + 30 = 510",
            "minimum": 0,
            "multipleOf": 5
        },
        "delta": {
            "type": "integer",
            "description": "A number of degres Celsius to INCREASE the setpoint of the heater. Use negative number to decrease the setpoint",
            "minimum": -5,
            "maximum": 5
        },
        "date": {
            "type": "string",
            "description": "day of the derogation. ISO8601 full-date format",
            "format": "full-date",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
        }
    },
    "required": [
        "homeId",
        "roomId",
        "startTime",
        "endTime",
        "delta",
        "date"
    ]
}

GatewayResponseDTO

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Informations on a gateway",
  "properties": {
    "token": {
      "type": "string"
      "description": "gateway identifier",
    },
    "version": {
      "type": "string",
      "description": "software version",
    },
    "lastPing": {
      "type": "string",
      "description": "iso date of the last time the gateway emmit a connect event to the MQTT server",
    },
    "installationDate": {
      "type": "string",
      "description": "gateway configuration date",
    }
  },
  "required": [
  ]
}

RequestReportDTO

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description" : "Data associated to a MQTT request",
  "properties": {
    "acknowledge": {
      "description" : "Wether the gateway as confirm receiving the message or not"
      "type": "boolean"
    },
    "homeId": {
      "description" : "target of the MQTT request"
      "type": "string"
    },
    "sendAt": {
      "type": "string"
    }
  }
}

MessageResponseDTO

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description" : "Data associated to a MQTT request",
  "properties": {
   "_created_at": {
      "type": "string"
    },
    "acknowledge": {
      "description" : "Wether the gateway as confirm receiving the message or not"
      "type": "boolean"
    },
    "_created_at": {
      "type": "string"
    }
  }
}

UserDTO

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description" : "Data associated to a MQTT request",
  "properties": {
    "homeId": {
      "description" : "user homeId"
      "type": "string"
    },
    "firstName": {
      "description" : "firstName"
      "type": "string"
    },
    "lastName": {
      "description" : "lastName"
      "type": "string"
    },
    "address": {
      "description" : "address"
      "type": "string"
    },
    "zipCode": {
      "description" : "zipCode"
      "type": "string"
    },
    "city": {
      "description" : "city"
      "type": "string"
    },
    "prmId": {
      "description" : "prm identifier"
      "type": "string"
    },
    "consentDate": {
      "description" : "ISODate: date of receiption of the user's consent"
      "type": "string"
    },
    "consentDate": {
      "description" : "contact email"
      "type": "string"
    },
  }
}

endpoints

GET DEVICES

description : Fetch the list of devices in a home

methods: POST

url : {BaseURL}/partners/1/config

headers :

  • Authorization : cf chapitre Authorization
  • Content-Type: application/json; charset=utf-8

body (json) :

{
  "homeId" : "String"
}

responseSuccess :

{
  "authorisation" : "AuthDTO",
  "reponse" : "Array<DeviceDTO>",
  "gateway" : "GatewayResponseDTO"
}

GET INVITATIONS

description : Fetch the list of home associated to a user

methods: POST

url : {BaseURL}/partners/1/invitations&nbsp;

headers :

  • Authorization : cf chapitre Authorization
  • Content-Type: application/json; charset=utf-8

body (json) :

{
  "email" : "johndoe@apple.com"
}

responseSuccess :

{
  "authorisation" : "AuthDTO",
  "reponse": "Array<InvitationDTO>"
}

SET DEROGATION

description : Schedule a list of derogation request. NB: All events in the payload must have the same start time and the end time.

methods: POST

url: {BaseURL}/partners/1/derogations

headers :

  • Authorization : cf chapitre Authorization
  • Content-Type: application/json; charset=utf-8

body (json) :

{
  "derogations" : "Array<DerogationDTO>"
}

responseSuccess :

{
  "authorisation" : "AuthDTO",
  "response" : "Array<string>",
  "startTrigger" : "[String] trigger identifier for the start of the derogations",
  "endTrigger" :  "[String] trigger identifier for the end of the derogations"
}

MONITORING

description : Returns the list of request emitted to the MQTT server for the events associated with a give trigger.

methods: POST

url: {BaseURL}/partners/1/report

headers :

  • Authorization : cf chapitre Authorization
  • Content-Type: application/json; charset=utf-8

body (json) :

{
  "trigger" :  "[String] trigger identifier"
}

responseSuccess :

{
  "authorisation": "AuthDTO",
  "response": {
    "summary": {
      "requested": "[Number] The total number of home with a requested derogation (target)",
      "sent": "[Number] total number of MQTT request sent. 1 per home",
      "received": "[Number] total number of MQTT request sent with confirmation of reception received",
      "first": "[String] DateTime of the first request sent",
      "last": "[String] DateTime of the last request sent"
    },
    "details": "Array<RequestReportDTO>"
  }
}

GET USERS

description : Returns the list of proof of consents per homeId with user personnal data.
Note that this method is paginated, use query paramaters page and size to browse the entire collection.

methods: GET

url: {BaseURL}/partners/1/users?page=...&size=...

urlParams

  • size : control the number of item to return
  • page : control the number of item to skip, query will skip the first (page - 1) * size items

headers :

  • Authorization : cf chapitre Authorization
  • Content-Type: application/json; charset=utf-8

responseSuccess :

{
  "authorisation": "AuthDTO",
  "response": "Array<UserDTO>"
}

DIAGNOSYS REQUEST

description : send a diagnosys request to a Home. The diagnosys is a 2 step operation. First step is sending a DIAGNOSYSREQEST to get a diagnosys id. After a recommanded titme of 5 minutes, you can send a DIAGNOSYSRESULT to get the full diagnosys.

methods: POST

url: {BaseURL}/partners/1/request

headers :

  • Authorization : cf chapitre Authorization
  • Content-Type: application/json; charset=utf-8

body (json) :

{
  "homeId" :  "[String] home identifier"
}

responseSuccess :

{
  "authorisation": "AuthDTO",
  "response": {
    "status": "[String] status [OK, NOK]",
    "messageId" : "[String] the diagnosys identifier"
  }
}

DIAGNOSYS RESUlT

description : read the content of a diagnosys. The diagnosys is a 2 step operation. First step is sending a DIAGNOSYSREQEST to get a diagnosys id. After a recommanded titme of 5 minutes, you can send a DIAGNOSYSRESULT to get the full diagnosys.

methods: PUT

url: {BaseURL}/partners/1/request

headers :

  • Authorization : cf chapitre Authorization
  • Content-Type: application/json; charset=utf-8

body (json) :

{
  "messageId" :  "[String] diagnosys identifier"
}

responseSuccess :

{
  "authorisation": "AuthDTO",
  "response": "MessageResponseDTO"
}