API Integration Manual
For
Daikin DKN Cloud Wi-Fi Adaptor
IM-DKNAPI-201908
Страница 1: ...API Integration Manual For Daikin DKN Cloud Wi Fi Adaptor IM DKNAPI 201908 ...
Страница 2: ...et 3 2 2 Oauth2 Authorization Code Grant Type 4 2 2 1 Refresh Token 5 2 3 Open API OAuth2 Implementation 5 2 3 1 Web Interface 5 2 3 2 Programmatic Interface 7 2 4 Oauth2 Best Practices 10 3 API 12 3 1 Status Requests 12 3 1 1 Devices 12 3 1 2 Device State 14 3 2 Command Requests 14 3 2 1 Device State 15 3 2 2 Device Setpoint 15 3 2 3 Device Mode 15 3 2 4 Device Speed 16 4 Errors 17 ...
Страница 3: ...for Daikin DKN Cloud Wi Fi Adaptor 2 1 INTRODUCTION The following document describes the use of the DKN Cloud NA third party API further on called Open API including the authentication flow and all available requests actions ...
Страница 4: ...then issues access tokens to the application In the Open API implementation the DKN Cloud NA ecosystem fulfills both the resource and authorization server roles Client Third Party Application The client is the third party application that wants to access the user s account Before it may do so it must be authorized by the user and the authorization must be validated by the Server 2 1 2 Third Party ...
Страница 5: ...ser s web browser and receiving API authorization codes that are routed through the user agent Nevertheless it can also be used with other server side services which lack of web interface programmatic interface Here describes the authorization code flow The above diagram represents a typical authorization flow Here is a more detailed explanation of the steps in the diagram 1 The application reques...
Страница 6: ...API OAuth2 Implementation As prerequisites users must have a valid account in both environments third party application and DKN Cloud NA the third party application must be registered as an authorized entity by DKN Cloud NA meaning that the third party will have a valid client_id client_secret token pair and for third party applications with web interface a valid Redirect URI Since the authenticat...
Страница 7: ...tate STATE_TOKEN this parameter preserves as an encoded format some state object set by the client in the Authorization request and makes it available to the client in the response Used to mitigate CSRF attacks explained later in more detail When the user clicks the link they must first log in to the service to authenticate their identity unless they are already logged in In case the user isn t lo...
Страница 8: ...tic interface access since they are the same for both flows 2 3 2 Programmatic Interface This interface basically performs the actions described above Login and Authorize but without the need of a browser only through HTTPS requests This method is suited for the integration in home automated systems BMS We will describe the structure and format of each of the requests Step 1 and 2 Login REQUEST PO...
Страница 9: ...e property redirectUri The value of this property will be one of the registered redirect URLs of the entity plus the code parameter same format as described in the Web interface process Example response redirectUri https example com code 9zHBr2TwEkUanHTlLGvs5EjCPOvdBAHF The remaining requests are common for both interfaces Step 4 Application Requests Access Token The value of code is used by the t...
Страница 10: ...ud NA environment through the Open API endpoints on behalf of the user When the access token expires DKN Cloud NA will respond with 401 error codes to every request with the following JSON body _error_description The access token is invalid or has expired error invalid_token The third party service will then need to request a new access token for the user In order to do so the service must use the...
Страница 11: ...application redirects the user agent to the DKN Cloud NA authorization URL It s recommended not to ask another service for this URL because the request could be intercepted by a malicious entity and return a different authorization URL This could lead to redirecting the user agent to a fake website where the user would perform the authorization flow leaving authorization codes and access tokens ex...
Страница 12: ... OAuth Authorization Server they send the respective request to and from the same user agent this Authorization Request was initiated with Clients must memorize which Authorization Server they sent an Authorization Request to and bind this information to the user agent browser sent from and ensure any sub sequent messages are sent to the same Authorization Server ...
Страница 13: ...ion json The headers will be omitted in the following descriptions All responses are in JSON format 3 1 Status Requests 3 1 1 Devices REQUEST GET https dkncloudna com api v1 open devices BODY none RESPONSE Example response _id 5cd51f1684c09013f6765d9c name Test group devices mac AA BB CC DD EE 0D icon 1 name Test timezoneId Europe Madrid units 0 schedules devices AA BB CC DD EE 0D hour 14 minutes ...
Страница 14: ...ices advanced user has access to every device in the installation as well as adding deleting users to it o schedules Array of JSON objects representing all the schedules an installation has configured devices array of devices to which the schedule is applied hour running hour 24h format 0 23 minutes 0 59 power if the schedule turns on or off the ACs Values on turns on the ACs off turns off the ACs...
Страница 15: ...warningStr string o mode device s current operation mode o power true if on false if off o setpoint setpoint for the current operation mode o temperature room temperature o speed fan speed o isConnected if device is online or not connected to the cloud o error AC unit s error code If there s no error this field will not be returned o errorStr ASCII representation of the error If there s no error t...
Страница 16: ...na com api v1 open INSTALLTION_ID MAC setpoint BODY JSON Properties o value Number value of the setpoint EXAMPLE PUT https dkncloudna com api v1 open 5cd51f1684c09013f6765d9c AA BB CC DD EE 0D setpoint In case the value is out of range the request will return the following error o Response code 400 o Body _id outOfRange msg Value out of range data validRange minimumValue value 18 maximumValue valu...
Страница 17: ...he AC fan s speed REQUEST PUT https dkncloudna com api v1 open INSTALLTION_ID MAC speed BODY JSON Properties o value Number value representing a valid speed EXAMPLE PUT https dkncloudna com api v1 open 5cd51f1684c09013f6765d9c AA BB CC DD EE 0D speed In case the speed value is not valid the request returns the following error o Response code 400 o Body _id speedNotValid msg Speed value not valid d...
Страница 18: ...SON msg Malformed JSON badParams Returned when the request body parameters don t meet the interface wrong parameters wrong type missing values Error code 400 Example response _id badParams msg Bad body parameters commandNotSupported Returned when the device doesn t support the requested command Error code 400 Example response _id commandNotSupported msg Command not supported databaseErr Returned w...
Страница 19: ...rror msg Error in the AC unit ERROR_ASCII notAuthorized Returned when the user doesn t have permission to act over the specified device Example response _id notAuthorized msg Error in the AC unit ERROR_ASCII socketTimeout Returned when there has been an internal error when communicating with other services very unusual Error code 500 Example response _id socketTimeout msg SocketTimeout with Device...
Страница 20: ...cal and national regulations and with the instructions in this installation manual Improper installation may cause electric shock or fire Only use specified accessories and parts for installation Failure to use specified parts may result in electric shock fire or controller damage Do not disassemble reconstruct or repair Electric shock or fire may occur Only use specified wiring and verify all wir...
