Cloud integration

• 1: Authorization
• 2: Discovery
• 3: Query
• 4: Control
• 5: Event Report
• 6: Result

1 - Authorization

iZone Cloud API uses OAuth access token to authorize user access.

Get authorization code

At some stage, you have to send user to iZone worldwide login service with your developer key and parameters.

Authorization Endpoint: https://worldwide.izone.com.au/login

The request uses GET method, with parameters:

The login service asks the user to authorize your integration to use their iZone system. The user authenticates with login their worldwide account. iZone sends an authorization code back to your integration.

Get access token

Once you get an authorization code, use it to get an access token and refresh token.

Token Endpoint: https://worldwide.izone.com.au/token

The request uses POST method, with parameters:

If request format and parameters are all good, the response would be HTTP 200 OK, with payload like this:

{
  "access_token": "c3cda13u-393a-c832-112-946106e5bbab",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "c3cda13u-393a-c832-112-946106e5bbab",
  "scope": "query-control"
}

Use Access Token

The access token is required in every iZone Cloud API call. According to different types of iZone Cloud APIs:

• HTTPS API
  • Use “Bearer” authentication in headers. Authorization: Bearer access-token
• gRPC API
  • Use “accessToken” in gPRC proto.

2 - Discovery

Discover Device Command

HTTPS Request.

POST https://api.izone.com.au/dev

Request Body JSON:

An example of response would be like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "requestType": "Discover",
  "response": {
    "userID":string_userID,
    "devices":[
    {
        "componentId":"123456798_izone_systemsettings_0",
        "datagram":{
            "SysOn":1,
            "SysMode":2,
            "SysFan":3,
            ...
        }
    },
    ...]
}

Response contains requesting user’s string_userID and an array of all componentIds and their latest datagram.

Individual device states can be queried through Query.

Refer to Reference the detail datagram of different types of iZone components.

3 - Query

Query Device States Command

HTTPS Request.

POST https://api.izone.com.au/dev

Request Body JSON:

An example of response would be like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "requestType": "Query",
  "response": {
    "component":{
      "componentId":"123456798_izone_systemsettings_0",
      "datagram":{
          "SysOn":1,
          "SysMode":2,
          "SysFan":3,
          ...
      }
    }
  }
}

Where response is componentId:componentDatagram

Refer to Reference the detail datagram of different types of iZone components.

4 - Control

Control Device Command

HTTPS Request.

POST https://api.izone.com.au/dev

Request Body JSON:

An example of request body would like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "componentId": "123456798_izone_systemsettings_0",
  "requestType": "Control",
  "requestBody": {
    json_controlCommand
  }
}

where json_controlCommand is the one of control commands with target value.

An expected response would be like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "componentId": "123456798_izone_systemsettings_0",
  "requestType": "Control",
  "response": {
    "result":"OK"
  }
}

Refer to Reference the detail control actions dictionary of different types of iZone device control.

5 - Event Report

Event Report API

iZone Cloud provides event report service, which can notify your event API when iZone device states changed or user deleted their account.

Please talk to Smart Alec about details of your event API.

Sync Request Body JSON Format:

An example of requesting re-discover/refresh would like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "userId": string_userID,
  "requestType": "Sync",
}

This request notifies user string_userID’s account condition has changed. To re-discover the user’s devices of userID.

Event Report Body JSON Format:

An example of device event update would like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "requestType": "Event",
  "requestBody": {
    "devices":[
      {
        "componentId":"123456798_izone_systemsettings_0",
        "datagram":{
            "SysOn":1,
            "SysMode":2,
            "SysFan":3,
            ...
        }
      },
      ...
    ]
  }
}

where json_datagram is the one of iZone device datagram.

Refer to Reference the detail control actions dictionary of different types of iZone device control.

6 - Result

Result Messages

iZone Cloud would return message after API actions are called.

An example of result would be like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "response": {
    "result":message_string
  }
}

where message_string contains OK or error messages.