Access Guide

1. Overall Architecture

The NEXhome IoT cloud platform provides API calls and message subscription capabilities for access control and intercom systems. This allows third-party vendors to send access credentials, contact lists, announcements, elevator control configurations, and other information to devices. This enables users to perform tasks such as unlocking doors, making video calls, and remotely calling elevators via third-party apps. The overall architecture is as follows:

2. Integration Steps

• (1) Apply for Developer Access Credentials - Developers need to create an application on the NEXhome developer platform to obtain the corresponding access credentials.
• (2) Developers complete function development based on their own business scenarios. The main business process flows are listed below.
• (3) Developers can receive information such as door access records and call logs through the MQ message queue. This feature requires developers to apply for message subscription permissions on the NEXhome open platform and navigate to Application Management -> Details -> Message Subscription to enable the message subscription switch.

3. API Call Instructions

3.1 General Overview

• The APIs use the RESTful HTTPS protocol, and all APIs require common request parameters. Refer to the Common Request Headers section for details. The response structure is outlined in the Response section. Each API's business parameters are detailed in the corresponding request and response documentation.
• All characters use UTF-8 encoding.
• The Content-Type is uniformly set to application/json.
• For list request parameters, unless otherwise specified, the default maximum is 50 items.

3.2 Common Request Headers

The table below lists the common headers required for all API requests.

3.3 Signature Algorithm

To ensure API security, the platform uses a signature strategy. The signature algorithm is as follows:

Step 1: Concatenate the request method (EXPRESS IN UPPERCASE, GET/POST/PATCH/DELETE/PUT/...), request URI (Path), DEVELOPER-ID, APP-ID, APP-SECRET, REQUEST-ID, and TIMESTAMP into a string signString using the following format:

method={METHOD}&uri={URI}&developerId={DEVELOPER-ID}&appId={APP-ID}&appSecret={APP-SECRET}&requestId={REQUEST-ID}&time={TIMESTAMP}

Step 2: Encrypt the signString using MD5 to obtain a 32-character HEX string, then convert it to uppercase.

• Example(java):

public void testApiSign() {
    String requestUri = "/api/v1/cits/devices";
    String method = "GET";
    String developerId = "developerId";
    String appId = "appId ";
    String appSecret = "appSecret ";
    String requestId = "548221f51c1a72c2b2f6de2ba2334359";
    String timestamp = "1727843531000";
    String sign = "method=" + method
            + "&uri=" + requestUri
            + "&developerId=" + developerId
            + "&appId=" + appId
            + "&appSecret=" + appSecret
            + "&requestId=" + requestId
            + "&time=" + timestamp;
	//sign: A4C83B06E593277CE04E48512E01CA0B
    sign = DigestUtils.md5DigestAsHex(sign.getBytes()).toUpperCase();
}

• API signature SDK:​​ If your integration team uses Java for implementation, we can provide an SDK for seamless integration.

3.4 Response Description

Successful Response

In the case of success, the HTTP status code will be 200, and the body will return the specific data.

Example:

HTTP/1.1 200

{
  "id": 1,
  "name": "test"
}

Error Response

In case of an error, the HTTP status code will not be 2XX, and the body will include: code, message, status, domain, and details. The code is the HTTP status code, the message describes the error, the domain indicates the location of the error, and details may contain one or more errors.

Example:

HTTP/1.1 401

{
  "code": 401,
  "message": "User does not have permission to perform this operation",
  "status": "UNAUTHORIZED",
  "domain": "com.nexhome.apis.iotdomain.v1.authority",
  "details": [
    {
      "domain": "com.nexhome.apis.iotdomain.v1.commons",
      "errorCode": "REQUIRED",
      "message": "Required field not filled",
      "fieldPath": "name"
    }
  ]
}