Specification

Environments

We understand that the development and testing process is a critical part of building and integrating with our smart energy management platform.

To facilitate this, we offer two distinct environments: sandbox and production. These environments serve specific purposes, each designed to help you build, test, integrate faster and more effectively with the HanChuESS Connect.

Sandbox	idaas-sandbox.hanchuess.com	Ideal playground for developers and partners who want to experiment with theHanChuESS Connect without touching real user data.
Production	idaas.hanchuess.com	The real deal. In this environment, you have access to actual data from customers assets. It is the place to go when you are ready to launch your application

EndPoints

Authenticate	https://{DOMAIN}/portal/{METHOD}
OpenAPI	https://{DOMAIN}/api/{METHOD}

{METHOD} is a sub-class url in each api reference.

Protocol

Https supported only, Use OAuth2.0 authentication mechanism.

Restriction

• The open API is designed in RESTful style.

• Request data format supports UTF-8, JSON format to return.

• Authenticate allow partner obtain token before invoke, modes supported in the following:

  • authorization_code

  • client_credentials

About our limits

Limits are designed to prevent API abuse, while minimizing impact on common customer usage patterns.

You may hit rate limits over shorter time intervals. For instance, a rate of 60 requests per minute (RPM) may be enforced as 1 request per second. Short bursts of requests at a high volume can surpass the rate limit and result in rate limiterrors.

We use the token bucket algorithm to do rate limiting. This means that your capacity is continuously replenished up to your maximum limit, rather than beingreset at fixed intervals.

All limits described here represent maximum allowed usage, not guaranteed minimums. These limits are intended to reduce unintentional overspend and ensurefair distribution of resources among users.

Request Header

Name	Necessary	Description
Content-Type	Y	Request type.
Authorization	Y	User Access token.
Accept-Language	N	I18N support, default en-US, optional zh-CN.
X-Signature	Y	Use HMAC256 to signature.
X-Timestamp	Y	Current timestamp in milliseconds.
X-Nonce	Y	Used once, random characters by UUIDv4.
X-Api-Version	N	Specified api version if needed.

Response Header

Name	Description
X-Request-Id	Troubleshooting when needed.
X-RateLimit-Remaining	Remaining tokens in bucket.
X-RateLimit-Replenish-Rate	Replenish token per request.
X-RateLimit-Burst-Capacity	Token bucket burst capacity.
X-RateLimit-Requested-Tokens	Token consumption in request.

Return Format

Parameter	Data Type	Decription
errno	string	See Errors for more details.
msg	string	Prompt or error message.
data	object	Response data in json format.

Signature

Restriction

Partners ought to generate different nonce per request, and server could tolerate max time within 60 seconds, otherwise, illegal request would receive 403 response from HanchuESS Connect.

Rule

Format	{HTTP_METHOD}:{API_METHOD}:{TIMESTAMP}:{NONCE}

{HTTP_METHOD} - POST/GET/DELETE/PATCH/PUT

{API_METHOD} - sub-class url in each api reference

{TIMESTAMP}: current timestamp in millieseconds

{NONCE}: random six characters in UUIDv4

Code Example

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class HmacDigest {
    private static final Logger log = LoggerFactory.getLogger(HmacDigest.class);

    public static String digestByHmac(String signStr, String secret, String algorithm) {
        if (signStr == null || secret == null || algorithm == null) {
            log.warn("Input parameters cannot be null");
            return null;
        }

        try {
            // 1. Key transformer
            SecretKeySpec secretKey = new SecretKeySpec(
                secret.getBytes(StandardCharsets.UTF_8), 
                algorithm
            );

            // 2. Initialization
            Mac mac = Mac.getInstance(algorithm);
            mac.init(secretKey);

            // 3. Digest caculation
            byte[] rawHmac = mac.doFinal(signStr.getBytes(StandardCharsets.UTF_8));

            // 4. Base64 encode
            return Base64.getEncoder().encodeToString(rawHmac);
        } catch (IllegalArgumentException e) {
            log.error("Invalid argument: {}", e.getMessage());
        } catch (java.security.NoSuchAlgorithmException e) {
            log.error("Unsupported algorithm: {}", algorithm);
        } catch (java.security.InvalidKeyException e) {
            log.error("Invalid key for algorithm: {}", algorithm);
        } catch (Exception e) {
            log.error("Unexpected error: {}", e.getMessage());
        }
        
        return null;
    }
}

JavaScript

Go

Python