Open API

Public information

This article is the open api document of Fox ESS Cloud Platform. Before using this api, please go to the api management of the cloud platform personal center to generate your api-key.
Please make sure to keep your API key safe to avoid any unauthorized access. If it gets lost or leaked, you can go to the personal center to get a new one, and the old key will no longer be valid.
The open API is designed in RESTful style, and the returned data are all in json format, and the encoding format is utf-8.
If you use script calling, be sure to modify your User-Agent.

Change Log：

Request domain：https://www.foxesscloud.com/

Request header requirements：

We support two types of authentication, private tokens and Oauth tokens. If you choose private token, please use token in header, if you choose Oauth token, please use Authorization in header, you can't use both at the same time.

OAuth Guide

This guide explains how to create an application client, obtain an OAuth token, and manage device binding. New integrations use the Client Credentials Grant for server-to-server communication. Once you have a valid access_token, you can use our APIs to onboard, check, update, and offboard devices.

VPP prerequisite: Create your client application in our v1 Platform and contact us with your clientId. We will enable VPP-specific features for your client before you begin the VPP integration flow below.

Existing authorization-code integration? Your current integration remains supported. See Legacy Authorization Code Flow below for the existing setup, token, and offboarding guidance.

Step 0: Create Your Client Application (Prerequisite)

Before using any OAuth flow, you must first register your application in our platform.

How to Create a Client

1. Log in to our v1 Platform.
2. Click your avatar in the top-right corner.
3. Select "User Profile".
4. In the left navigation menu, go to "API Management" → "Authorization Token".
5. Click "Create Client Side".
6. Fill in the form as shown below:
   • Client Name: A descriptive name for your application (e.g., MyVPPApp).
   • Redirect Address: The exact callback URL where users will be redirected after authorization. (This becomes your redirect_uri)
   • Scopes: Select the permissions your app needs:
     • data_access: Grants read access to device data.
     • device_control: Grants control permissions for devices.
     • (These selections become your scope parameter)
   • Click "Save".

Critical Notes

• After creation, the system will display your client_id and client_secret.
• The client_secret is shown only once. Please copy and store it securely.
• If you lose the client_secret, we recommend you delete the old client and create a new one.

Mapping to API Parameters:

• client_id in the API = The Client ID generated on this page.
• client_secret in the API = The Client Secret shown after creation.
• redirect_uri in the API = The Redirect Address you entered.
• scope in the API = The scopes you selected (e.g., data_access,device_control).

https://{domain}/h5/auth/foxessIndex?
    response_type=code&
    client_id={your_client_id}&
    redirect_uri={your_redirect_uri}&
    scope={your_scopes}

{your_redirect_uri}?code={authorization_code}&deviceSn={device_serial_number}

POST https://{domain}/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&

client_id={your_client_id}&

client_secret={your_client_secret}&

code=ABC123&

redirect_uri={your_redirect_uri}

GET https://{api_domain}/op/v0/device/boarding/status?sn=YOUR_DEVICE_SN
Authorization: Bearer YOUR_ACCESS_TOKEN
Signature: Encrypt the string url+"\r\n"+ YOUR_ACCESS_TOKEN +"\r\n"+timestamp with md5

POST https://{api_domain}/op/v0/device/boarding/status/set
Authorization: Bearer YOUR_ACCESS_TOKEN
Signature: Encrypt the string url+"\r\n"+ YOUR_ACCESS_TOKEN +"\r\n"+timestamp with md5
Content-Type: application/json
{
    "sn": "YOUR_DEVICE_SN",
    "status": 1
}

POST https://{domain}/oauth2/refresh
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&

client_id={your_client_id}&

client_secret={your_client_secret}&

refresh_token={your_refresh_token}

VPP Device Enrollment and Operations

For VPP integrations, the end user selects a device on the FoxESS H5 page. After a successful callback, the device is already bound to your VPP. Your backend then obtains an OAuth token with its client credentials to operate the device.

Step 1: Redirect User to Device Selection

Redirect the user to the FoxESS H5 page. The user signs in, reviews eligible devices, and confirms the device to enroll.

scope = The permissions required from the end user (for example, data_access,device_control).

URL Example:

https://{domain}/h5/auth/foxessIndex?
    response_type=code&
    client_id={your_client_id}&
    redirect_uri={your_redirect_uri}&
    scope={your_scopes}

After the user confirms their selection, the browser returns to your redirect_uri with the selected device SN.

Callback Example:

{your_redirect_uri}?deviceSn={device_serial_number}

Step 2: Obtain an OAuth Token

Your application server uses the Client Credentials Grant with its client_id and client_secret to request an OAuth token directly.

Request Example:

POST https://{domain}/oauth2/client_token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&

client_id={your_client_id}&

client_secret={your_client_secret}

Note: The OAuth token is valid for 24 hours. To obtain a new token after expiration, repeat this request.

Step 3: Check and Update Device Boarding Status (Optional)

Use your OAuth token and the device SN returned by the H5 callback to query or update the boarding status of an enrolled device.

Check Status:

GET https://{api_domain}/op/v0/device/boarding/status?sn=YOUR_DEVICE_SERIAL_NUMBER
Authorization: Bearer YOUR_ACCESS_TOKEN
Signature: Encrypt the string url+"\r\n"+ YOUR_ACCESS_TOKEN +"\r\n"+timestamp with md5

Update Status:

POST https://{api_domain}/op/v0/device/boarding/status/set
Authorization: Bearer YOUR_ACCESS_TOKEN
Signature: Encrypt the string url+"\r\n"+ YOUR_ACCESS_TOKEN +"\r\n"+timestamp with md5
Content-Type: application/json
{
    "sn": "YOUR_DEVICE_SN",
    "status": 1
}

Step 4: Offboard Devices (Optional)

Request Example:

POST https://{api_domain}/op/v0/vpp/oauth2/client/offboard
Authorization: Bearer YOUR_ACCESS_TOKEN
Signature: Encrypt the string url+"\r\n"+ YOUR_ACCESS_TOKEN +"\r\n"+timestamp with md5
Content-Type: application/json
{
    "deviceSN": "DEVICE_SN"
}

Step 5: Obtain a New OAuth Token

After the token expires, repeat Step 2 to obtain a new OAuth token.

Access frequency limit：

• Each inverter under a single account has a total of 1440 interface calls per day.
• The query interface is limited to once per second, and each interface is calculated separately.
• Inserting update interfaces is limited to once every 2 seconds, and each interface is calculated separately.

This limit is calculated based on various factors such as server performance, and the Company reserves the right of final interpretation

Common error solutions：

40256 The request header parameters are missing. Please check whether the request headers are consistent with the document requirements.
40257 The request body parameters are invalid. Please check whether the request body is consistent with the document requirements.
40400 The number of requests is too frequent. Please reduce the frequency of access.

Code example：

import json
import time
import urllib3
import requests
import hashlib
import os
from json import JSONDecodeError
"""debug mode"""
debug = False
"""request interval (second)"""
sleep_time = 0
"""domain name, do not modify it unless necessary"""
domain = 'https://portal.foxesscloud.us'
"""your key"""
key = ''
class GetAuth:
def get_signature(self, token, path, lang='en'):

"""

This function is used to generate a signature consisting of URL, token, and timestamp, and return a dictionary containing the signature and other information.

:param token: your key

:param path:  your request path

:param lang: language, default is English.

:return: with authentication header

"""

timestamp = round(time.time() * 1000)

signature = fr'{path}\r\n{token}\r\n{timestamp}'
result = {
    'token': token,
    'lang': lang,
    'timestamp': str(timestamp),
    'signature': self.md5c(text=signature),
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) '
                  'Chrome/117.0.0.0 Safari/537.36'
}
return result

            
@staticmethod

                def md5c(text="", _type="lower"):

                res = hashlib.md5(text.encode(encoding='UTF-8')).hexdigest()

                if _type.eq("lower"):

                return res

                else:

                return res.upper()
            
def save_response_data(response, filename):
            
"""Create the 'data' directory if it doesn't exist"""
            
os.makedirs('data', exist_ok=True)
            
"""Concatenate the directory path and filename to create the full file path"""

                file_path = os.path.join('data', filename)
            
"""Get the current timestamp"""

                timestamp = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
            
"""Check if the status code is 200"""

                if response.status_code == 200:

                """Save the response data and timestamp to a dictionary"""

                try:

                response_json = response.json()

                except JSONDecodeError:

                response_json = response.text
            
data = {
    'response': response_json,
    'timestamp': timestamp
}
"""Write the dictionary as JSON to the file"""
with open(file_path, 'w', encoding='utf-8') as file:
    json.dump(data, file, ensure_ascii=False, indent=4)

			
else:

				"""Save the status code, response text, and timestamp to a dictionary"""

				data = {

				'status_code': response.status_code,

				'response_text': response.text,

				'timestamp': timestamp

				}

				"""Write the dictionary as JSON to the file"""

				with open(file_path, 'w', encoding='utf-8') as file:

				json.dump(data, file, ensure_ascii=False, indent=4)
			
print(f'{timestamp}: [{filename}] successfully saved')
			
urllib3.disable_warnings()
			
def fr_requests(method, path, param=None):
			
url = domain + path
			
headers = GetAuth().get_signature(token=key, path=path)
			
time.sleep(sleep_time)
			
if method == 'get':

				response = requests.get(url=url, params=param, headers=headers, verify=False)
			
elif method == 'post':

				response = requests.post(url=url, json=param, headers=headers, verify=False)

				else:

				raise Exception('request method error')
			
if debug:

				result = {'url': url, 'method': method, 'param': param, 'headers': headers, 'response': response.text}

				print(json.dumps(result, indent=1))

				print('-------------------------' * 5)

				return response
			
class Plant:
			
@staticmethod

				def plant_list():

				path = '/op/v0/plant/list'

				request_param = {'currentPage': 1, 'pageSize': 10}

				response = fr_requests('post', path, request_param)

				save_response_data(response, 'plant_list_response.json')

				return response
			
@staticmethod

				def plant_detail():

				path = '/op/v0/plant/detail'

				request_param = {'id': 'abc'}

				response = fr_requests('get', path, request_param)

				save_response_data(response, 'plant_detail_response.json')

				return response
			
class Device:
			
@staticmethod
			
def device_list():
			
path = '/op/v0/device/list'
			
request_param = {'currentPage': 1, 'pageSize': 500}
			
response = fr_requests('post', path, request_param)
			
save_response_data(response, 'device_list_response.json')
			
return response
			
@staticmethod

				def device_detail():

				path = '/op/v0/device/detail'

				request_param = {'sn': 'sn'}

				response = fr_requests('get', path, request_param)

				save_response_data(response, 'device_detail_response.json')

				return response
			
@staticmethod

				def variable_get():

				path = '/op/v0/device/variable/get'

				response = fr_requests('get', path)

				save_response_data(response, 'device_variable_get_response.json')

				return response
			
@staticmethod

				def real_query():

				path = '/op/v0/device/real/query'

				request_param = {'sn': 'sn', 'variables': []}

				response = fr_requests('post', path, request_param)

				save_response_data(response, 'device_real_query_response.json')

				return response
			
@staticmethod

				def history_query():

				path = '/op/v0/device/history/query'

				"""get the current millisecond level timestamp"""

				end_time = int(time.time() * 1000)

				"""timestamp 24 hours ago"""

				begin_time = end_time - 3600000

				request_param = {'sn': 'sn', 'variables': [], 'begin': begin_time, 'end': end_time}

				response = fr_requests('post', path, request_param)

				save_response_data(response, 'device_history_query_response.json')

				return response
			
@staticmethod

				def report_query():

				path = '/op/v0/device/report/query'

				request_param = {"sn": "sn",

				"year": 2024, "month": 1, 'day': 17, "dimension": "day",

				"variables": ["generation", "feedin", "gridConsumption",

				"chargeEnergyToTal", "dischargeEnergyToTal"]}

				response = fr_requests('post', path, request_param)

				save_response_data(response, 'device_report_query_response.json')

				return response
			
@staticmethod

				def device_generation():

				path = '/op/v0/device/generation'

				request_param = {'sn': 'sn'}

				response = fr_requests('get', path, request_param)

				save_response_data(response, 'device_generation_response.json')

				return response
			
@staticmethod

				def device_bat_soc_get():

				path = '/op/v0/device/battery/soc/get'

				request_param = {'sn': 'sn'}

				response = fr_requests('get', path, request_param)

				save_response_data(response, 'device_bat_soc_get_response.json')

				return response
			
@staticmethod

				def device_bat_soc_set():

				path = '/op/v0/device/battery/soc/set'

				request_param = {'sn': 'sn', 'minSoc': 10, 'minSocOnGrid': 10}

				response = fr_requests('post', path, request_param)

				save_response_data(response, 'device_bat_soc_set_response.json')

				return response
			
@staticmethod

				def device_bat_force_charge_time_get():

				path = '/op/v0/device/battery/forceChargeTime/get'

				request_param = {'sn': 'sn'}

				response = fr_requests('get', path, request_param)

				save_response_data(response, 'device_bat_force_charge_time_get_response.json')

				return response
			
@staticmethod

				def device_bat_force_charge_time_set():

				path = '/op/v0/device/battery/forceChargeTime/set'

				request_param = {"sn": "sn", "enable1": True, "enable2": False,

				"startTime1": {"hour": 12, "minute": 0}, "endTime1": {"hour": 14, "minute": 56},

				"startTime2": {"hour": 2, "minute": 0}, "endTime2": {"hour": 4, "minute": 0}}

				"""

				request_param = {"sn": "sn", "enable1": False, "enable2": False,

				"startTime1": {"hour": 11, "minute": 1}, "endTime1": {"hour": 15, "minute": 57},

				"startTime2": {"hour": 3, "minute": 1}, "endTime2": {"hour": 5, "minute": 1}}

				"""

				response = fr_requests('post', path, request_param)

				save_response_data(response, 'device_bat_force_charge_time_set_response.json')

				return response
			
@staticmethod

				def device_scheduler_get_flag():

				path = '/op/v0/device/scheduler/get/flag'

				request_param = {'deviceSN': 'sn'}

				response = fr_requests('post', path, request_param)

				save_response_data(response, 'device_scheduler_get_flag_response.json')

				return response
			
@staticmethod

				def device_scheduler_set_flag():

				path = '/op/v0/device/scheduler/set'

				request_param = {'deviceSN': 'sn', 'enable': 0}

				response = fr_requests('post', path, request_param)

				save_response_data(response, 'device_scheduler_set_flag_response.json')

				return response
			
@staticmethod

				def device_scheduler_get():

				path = '/op/v0/device/scheduler/get'

				request_param = {'deviceSN': 'sn'}

				response = fr_requests('post', path, request_param)

				save_response_data(response, 'device_scheduler_get_response.json')

				return response
			
@staticmethod

				def device_scheduler_enable():

				path = '/op/v0/device/scheduler/enable'

				request_param1 = {"deviceSN": "sn",

				"groups": [{"enable": 1, "startHour": 0, "startMinute": 0, "endHour": 1, "endMinute": 59,

				"workMode": "SelfUse", "minSocOnGrid": 11, "fdSoc": 12, "fdPwr": 5001},

				{"enable": 1, "startHour": 2, "startMinute": 1, "endHour": 3, "endMinute": 0,

				"workMode": "SelfUse", "minSocOnGrid": 21, "fdSoc": 22, "fdPwr": 5002},

				{"enable": 1, "startHour": 3, "startMinute": 1, "endHour": 3, "endMinute": 58,

				"workMode": "Feedin", "minSocOnGrid": 31, "fdSoc": 32, "fdPwr": 5003},

				{"enable": 1, "startHour": 4, "startMinute": 1, "endHour": 4, "endMinute": 58,

				"workMode": "Backup", "minSocOnGrid": 41, "fdSoc": 42, "fdPwr": 5004},

				{"enable": 1, "startHour": 5, "startMinute": 1, "endHour": 5, "endMinute": 58,

				"workMode": "ForceCharge", "minSocOnGrid": 51, "fdSoc": 52, "fdPwr": 5005},

				{"enable": 1, "startHour": 6, "startMinute": 1, "endHour": 6, "endMinute": 58,

				"workMode": "ForceDischarge", "minSocOnGrid": 61, "fdSoc": 62, "fdPwr": 5006},

				{"enable": 1, "startHour": 7, "startMinute": 0, "endHour": 7, "endMinute": 59,

				"workMode": "ForceDischarge", "minSocOnGrid": 71, "fdSoc": 72, "fdPwr": 0},

				{"enable": 1, "startHour": 8, "startMinute": 0, "endHour": 23, "endMinute": 59,

				"workMode": "ForceDischarge", "minSocOnGrid": 81, "fdSoc": 82, "fdPwr": 6000}]}

				request_param2 = {"deviceSN": "sn",

				"groups": [{"enable": 0, "startHour": 0, "startMinute": 0, "endHour": 0, "endMinute": 1,

				"workMode": "ForceCharge", "minSocOnGrid": 10, "fdSoc": 0, "fdPwr": 0},

				{"enable": 0, "startHour": 3, "startMinute": 2, "endHour": 4, "endMinute": 1,

				"workMode": "ForceCharge", "minSocOnGrid": 22, "fdSoc": 23, "fdPwr": 5003},

				{"enable": 0, "startHour": 4, "startMinute": 2, "endHour": 4, "endMinute": 59,

				"workMode": "Backup", "minSocOnGrid": 32, "fdSoc": 32, "fdPwr": 5004},

				{"enable": 0, "startHour": 5, "startMinute": 2, "endHour": 5, "endMinute": 59,

				"workMode": "Feedin", "minSocOnGrid": 42, "fdSoc": 42, "fdPwr": 5005},

				{"enable": 0, "startHour": 6, "startMinute": 2, "endHour": 6, "endMinute": 59,

				"workMode": "SelfUse", "minSocOnGrid": 52, "fdSoc": 52, "fdPwr": 5006},

				{"enable": 0, "startHour": 7, "startMinute": 1, "endHour": 7, "endMinute": 59,

				"workMode": "SelfUse", "minSocOnGrid": 62, "fdSoc": 62, "fdPwr": 5007},

				{"enable": 0, "startHour": 8, "startMinute": 1, "endHour": 8, "endMinute": 3,

				"workMode": "SelfUse", "minSocOnGrid": 72, "fdSoc": 72, "fdPwr": 0},

				{"enable": 0, "startHour": 22, "startMinute": 59, "endHour": 23, "endMinute": 59,

				"workMode": "SelfUse", "minSocOnGrid": 100, "fdSoc": 100, "fdPwr": 6000}]}

				response = fr_requests('post', path, request_param2)

				save_response_data(response, 'device_scheduler_set_response.json')

				return response
			
class Module:
			
@staticmethod
			
def module_list():
			
path = '/op/v0/module/list'
			
request_param = {'currentPage': 1, 'pageSize': 10}
			
response = fr_requests('post', path, request_param)
			
save_response_data(response, 'module_list_response.json')
			
return response
			
class User:
			
@staticmethod
			
def user_get_access_count():
			
path = '/op/v0/user/getAccessCount'
			
response = fr_requests('get', path)
			
save_response_data(response, 'user_get_access_count_response.json')
			
return response
			
if name == 'main':
			
plant = Plant()
			
"""
			
plant.plant_list()
			
plant.plant_detail()
			
"""
			
device = Device()

				"""

				device.device_list()

				device.device_detail()

				device.variable_get()

				device.real_query()

				device.history_query()

				device.report_query()

				device.device_generation()
			
device.device_bat_soc_set()

				time.sleep(3)

				device.device_bat_soc_get()
			
device.device_bat_force_charge_time_set()

				time.sleep(3)

				device.device_bat_force_charge_time_get()
			
device.device_scheduler_set_flag()

				time.sleep(3)

				device.device_scheduler_get_flag()

				device.device_scheduler_enable()

				time.sleep(3)

				device.device_scheduler_get()

				"""
			
module = Module()

				"""

				module.module_list()

				"""
			
user = User()

				"""

				user.user_get_access_count()

				"""

				

Variable table：

The table presented below offers a comprehensive overview of the variables that can be accessed through the API. It is important to note that the availability of these variables may differ depending on the specific device being utilized. Therefore, the variables listed in the table are subject to change based on the device in use.

PV (Photovoltaic)

Grid

Loads

Inverter

Battery

Meter

EPS (Emergency Power Supply)

Heat Pump（For Kafka）

Appendix For Enum Variable

Kafka Integration Documentation

1. Overview

This document provides guidance for customers to integrate with our Kafka messaging service.

After completing the integration, customers can use the Kafka protocol to:

• Subscribe to data

2. Integration Process

2.1 Integration Steps

The customer integration workflow is as follows:

1. Submit an integration request (provide company/system information)
2. We create a Kafka non-production environment:
   • Account (Username / Password)
   • Topic and Group ID
   • Permissions (Read)
3. We provide the integration details
4. Customer completes SDK/client integration
5. Joint debugging and testing
6. Create Kafka production environment
7. Release to production

3. Integration Information Description

We will provide the following information:

4. Client Integration Examples

4.1 Java Example

# kafka.properties
## ============================== Common Config ==============================
bootstrap.servers=xxxxxxxxxxxxxxxxxxxxx
topic=xxx
group.id=xxx
======================= Configure Based on Your Setup =====================
SSL endpoint config
ssl.truststore.location=/xxxx/only.4096.client.truststore.jks
Must be KafkaOnsClient, do not modify
ssl.truststore.password=KafkaOnsClient
Hostname verification (leave empty)
ssl.endpoint.identification.algorithm=
java.security.auth.login.config=/xxxx/kafka_client_jaas.conf
SASL PLAIN
java.security.auth.login.config.plain=/xxxx/kafka_client_jaas_plain.conf
SASL SCRAM
java.security.auth.login.config.scram=/xxxx/kafka_client_jaas_scram.conf

### Java Kafka Consumer Example (with Detailed Comments)

import java.util.ArrayList;
import java.util.List;
import java.util.Properties;

import org.apache.kafka.clients.consumer.ConsumerConfig;
import org.apache.kafka.clients.consumer.ConsumerRecord;
import org.apache.kafka.clients.consumer.ConsumerRecords;
import org.apache.kafka.clients.consumer.KafkaConsumer;
import org.apache.kafka.clients.producer.ProducerConfig;

/*
 * For SSL endpoint instances, uncomment the following three lines.
 * For SASL endpoint instances, uncomment the first two lines below.
 */
// import org.apache.kafka.clients.CommonClientConfigs;
// import org.apache.kafka.common.config.SaslConfigs;
// import org.apache.kafka.common.config.SslConfigs;

public class KafkaConsumerDemo {

    public static void main(String args[]) {

        // Set the JAAS configuration file path
        /*
         * For SSL endpoint instances, uncomment the following line:
         * JavaKafkaConfigurer.configureSasl();
         */

        /*
         * For SASL PLAIN mechanism instances, uncomment the following line:
         * JavaKafkaConfigurer.configureSaslPlain();
         */

        /*
         * For SASL SCRAM mechanism instances, uncomment the following line:
         * JavaKafkaConfigurer.configureSaslScram();
         */

        // Load kafka.properties
        Properties kafkaProperties = JavaKafkaConfigurer.getKafkaProperties();

        Properties props = new Properties();

        // Set bootstrap servers (Kafka endpoint)
        props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG,
                kafkaProperties.getProperty("bootstrap.servers"));

        // Default session timeout (30 seconds)
        props.put(ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG, 30000);

        /*
         * For SSL endpoint instances, uncomment the following configurations:
         *
         * Set SSL truststore path (replace XXX with your actual path)
         * props.put(SslConfigs.SSL_TRUSTSTORE_LOCATION_CONFIG,
         *         kafkaProperties.getProperty("ssl.truststore.location"));
         *
         * Truststore password (must remain unchanged)
         * props.put(SslConfigs.SSL_TRUSTSTORE_PASSWORD_CONFIG, "KafkaOnsClient");
         *
         * Security protocol
         * props.put(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG, "SASL_SSL");
         *
         * SASL mechanism
         * props.put(SaslConfigs.SASL_MECHANISM, "PLAIN");
         *
         * Max interval between polls
         * props.put(ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG, 30000);
         *
         * Fetch size configuration (important for public network access)
         * props.put(ConsumerConfig.MAX_PARTITION_FETCH_BYTES_CONFIG, 32000);
         * props.put(ConsumerConfig.FETCH_MAX_BYTES_CONFIG, 32000);
         */

        /*
         * For SASL PLAIN mechanism instances, uncomment:
         *
         * props.put(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG, "SASL_PLAINTEXT");
         * props.put(SaslConfigs.SASL_MECHANISM, "PLAIN");
         * props.put(ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG, 30000);
         */

        /*
         * For SASL SCRAM mechanism instances, uncomment:
         *
         * props.put(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG, "SASL_PLAINTEXT");
         * props.put(SaslConfigs.SASL_MECHANISM, "SCRAM-SHA-256");
         * props.put(ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG, 30000);
         */

        // Maximum number of records per poll
        // Avoid setting too large to prevent rebalance delays
        props.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, 30);

        // Deserialization
        props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG,
                "org.apache.kafka.common.serialization.StringDeserializer");
        props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG,
                "org.apache.kafka.common.serialization.StringDeserializer");

        // Consumer group ID
        props.put(ConsumerConfig.GROUP_ID_CONFIG,
                kafkaProperties.getProperty("group.id"));

        // Create Kafka consumer instance
        KafkaConsumer<String, String> consumer =
                new KafkaConsumer<>(props);

        // Subscribe to topics (supports multiple topics)
        List<String> subscribedTopics = new ArrayList<>();

        String topicStr = kafkaProperties.getProperty("topic");
        String[] topics = topicStr.split(",");

        for (String topic : topics) {
            subscribedTopics.add(topic.trim());
        }

        consumer.subscribe(subscribedTopics);

        // Start consuming messages
        while (true) {
            try {
                ConsumerRecords<String, String> records = consumer.poll(1000);

                // Process records within session timeout
                for (ConsumerRecord<String, String> record : records) {
                    System.out.println(String.format(
                            "Consume partition:%d offset:%d",
                            record.partition(),
                            record.offset()));
                }

            } catch (Exception e) {
                try {
                    Thread.sleep(1000);
                } catch (Throwable ignore) {
                }
                e.printStackTrace();
            }
        }
    }
}

4.2 Golang Example

// kafka.json
{
  "topic": "XXX",
  "group.id": "XXX",
  "bootstrap.servers": "XXX:XX,XXX:XX,XXX:XX",
  "security.protocol": "sasl_ssl",
  "sasl.mechanism": "XXX",
  "sasl.username": "XXX",
  "sasl.password": "XXX"
}

// main.go
package main
import (

"encoding/json"

"fmt"

"github.com/confluentinc/confluent-kafka-go/kafka"

"os"

"path/filepath"

)

type KafkaConfig struct {

Topic      string json:"topic"

GroupId    string json:"group.id"

BootstrapServers    string json:"bootstrap.servers"

SecurityProtocol string json:"security.protocol"

SaslMechanism string json:"sasl.mechanism"

SaslUsername string json:"sasl.username"

SaslPassword string json:"sasl.password"

}
// config should be a pointer to structure, if not, panic

func loadJsonConfig() *KafkaConfig {

workPath, err := os.Getwd()

if err != nil {

panic(err)

}

configPath := filepath.Join(workPath, "conf")

fullPath := filepath.Join(configPath, "kafka.json")

file, err := os.Open(fullPath);

if (err != nil) {

msg := fmt.Sprintf("Can not load config at %s. Error: %v", fullPath, err)

panic(msg)

}
defer file.Close()

decoder := json.NewDecoder(file)
var config = &KafkaConfig{}
err = decoder.Decode(config);
if (err != nil) {
    msg := fmt.Sprintf("Decode json fail for config file at %s. Error: %v", fullPath, err)
    panic(msg)
}
json.Marshal(config)
return  config

            
}
            
func doInitConsumer(cfg *KafkaConfig) *kafka.Consumer {

                fmt.Print("init kafka consumer, it may take a few seconds to init the connection\n")

                //common arguments

                var kafkaconf = &kafka.ConfigMap{

                "api.version.request": "true",

                "auto.offset.reset": "latest",

                "heartbeat.interval.ms": 3000,

                "session.timeout.ms": 30000,

                "max.poll.interval.ms": 120000,

                "fetch.max.bytes": 1024000,

                "max.partition.fetch.bytes": 256000}

                kafkaconf.SetKey("bootstrap.servers", cfg.BootstrapServers);

                kafkaconf.SetKey("group.id", cfg.GroupId)
            
switch cfg.SecurityProtocol {
case "plaintext" :
    kafkaconf.SetKey("security.protocol", "plaintext");
case "sasl_ssl":
    kafkaconf.SetKey("security.protocol", "sasl_ssl");
    kafkaconf.SetKey("ssl.ca.location", "./conf/ca-cert.pem");
    kafkaconf.SetKey("sasl.username", cfg.SaslUsername);
    kafkaconf.SetKey("sasl.password", cfg.SaslPassword);
    kafkaconf.SetKey("sasl.mechanism", cfg.SaslMechanism);
    kafkaconf.SetKey("ssl.endpoint.identification.algorithm", "None");
    kafkaconf.SetKey("enable.ssl.certificate.verification", "false")
case "sasl_plaintext":
    kafkaconf.SetKey("security.protocol", "sasl_plaintext");
    kafkaconf.SetKey("sasl.username", cfg.SaslUsername);
    kafkaconf.SetKey("sasl.password", cfg.SaslPassword);
    kafkaconf.SetKey("sasl.mechanism", cfg.SaslMechanism)

default:
    panic(kafka.NewError(kafka.ErrUnknownProtocol, "unknown protocol", true))
}

consumer, err := kafka.NewConsumer(kafkaconf)
if err != nil {
    panic(err)
}
fmt.Print("init kafka consumer success\n")
return consumer;

            
}
            
func main() {
            
// Choose the correct protocol
// 9092 for PLAINTEXT
// 9093 for SASL_SSL, need to provide sasl.username and sasl.password
// 9094 for SASL_PLAINTEXT, need to provide sasl.username and sasl.password
cfg := loadJsonConfig();
consumer := doInitConsumer(cfg)

consumer.SubscribeTopics([]string{cfg.Topic}, nil)

for {
    msg, err := consumer.ReadMessage(-1)
    if err == nil {
        fmt.Printf("Message on %s: %s\n", msg.TopicPartition, string(msg.Value))
    } else {
        // The client will automatically try to recover from all errors.
        fmt.Printf("Consumer error: %v (%v)\n", err, msg)
    }
}

consumer.Close()

            
}

                

4.3 Python Example

kafka_setting = {
    'sasl_plain_username': 'XXX',
    'sasl_plain_password': 'XXX',
    'bootstrap_servers': ["XXX", "XXX", "XXX"],
    'topic_name': 'XXX',
    'consumer_id': 'XXX'
}

from confluent_kafka import Consumer, KafkaError
import setting
conf = setting.kafka_setting
c = Consumer({

'bootstrap.servers': conf['bootstrap_servers'],

'group.id': conf['group_name'],

'auto.offset.reset': 'latest'

})
c.subscribe([conf['topic_name']])
while True:

msg = c.poll(1.0)
if msg is None:
    continue
if msg.error():
    if msg.error().code() == KafkaError._PARTITION_EOF:
        continue
    else:
        print("Consumer error: {}".format(msg.error()))
        continue

print('Received message: {}'.format(msg.value().decode('utf-8')))

            
c.close()

                

5. FAQ

5.1 Connection Failure

Check:

• Whether the port is open
• Whether the SASL configuration is correct

5.2 No Data Consumed

Check:

• Whether the Topic is correct
• Whether the Consumer Group conflicts
• Whether the offset is at the end (latest)

5.3 Permission Issues

Symptom:

Topic authorization failed

Solution:

Contact us to enable ACL permissions

Power Station

Create power station

Basic information

Path： /op/v0/plant/create

Method： POST

Interface description：

request body example:

{
  "devices": [
    {
      "sn": "*******"
    }
  ],
  "pileSN": "*************",
  "details": {
    "name": "name_51b2289bf18f",
    "type": 1,
    "countryCode": "CN",
    "city": "city_54049a6aad08",
    "address": "address_efdf02e2819d",
    "postcode": "213414",
    "price": 0.52,
    "currency": "CNY(¥)",
    "systemCapacity": 72.00
  },
  "timezone": "Asia/Shanghai",
  "position": {
    "x": "x_9e0c3cf37a91",
    "y": "y_6fa583b5fe21",
    "format": "format_b9434db57b54",
    "pid": "pid_169c8579050c"
  },
  "electricmeterSN": "*********************",
  "layoutByMini": {
    "direction": 1,
    "arrange": [
      {
        "sn": "***********",
        "horizontal": 2,
        "vertical": 3,
        "azimuth": 30,
        "dipAngle": 45,
        "direction": 1,
        "capacity": 30,
        "model": "model_71300e86ba58"
      }
    ]
  }
}

Request parameter

Headers

Body

Response Data

Delete power station

Basic information

Path： /op/v0/plant/delete

Method： POST

Interface description：

request body example:

{
  "stationID": "***********"
}

Request parameter

Headers

Body

Response Data

Edit power station

Basic information

Path： /op/v0/plant/update

Method： POST

Interface description：

request body example:

{
  "devices": [
    {
      "sn": "*******"
    }
  ],
  "pileSN": "*************",
  "details": {
    "stationID": "********************",
    "name": "name_51b2289bf18f",
    "type": 1,
    "countryCode": "CN",
    "city": "city_54049a6aad08",
    "address": "address_efdf02e2819d",
    "postcode": "213414",
    "price": 0.52,
    "currency": "CNY(¥)",
    "systemCapacity": 72.00
  },
  "timezone": "Asia/Shanghai",
  "position": {
    "x": "x_9e0c3cf37a91",
    "y": "y_6fa583b5fe21",
    "format": "format_b9434db57b54",
    "pid": "pid_169c8579050c"
  },
  "electricmeterSN": "*********************",
  "layoutByMini": {
    "direction": 1,
    "arrange": [
      {
        "sn": "***********",
        "horizontal": 2,
        "vertical": 3,
        "azimuth": 30,
        "dipAngle": 45,
        "direction": 1,
        "capacity": 30,
        "model": "model_71300e86ba58"
      }
    ]
  }
}

Request parameter

Headers

Body

Response Data

Get power station detail

Basic information

Path： /op/v0/plant/detail

Method： GET

Interface description：

Obtain details about a power station based on the power station ID

Request parameter

Headers

Query

Body

Response Data

Get power station list

Basic information

Path： /op/v0/plant/list

Method： POST

Interface description：

Obtain the list of power stations to which this account belongs
request body example:

{
  "currentPage": 1,
  "pageSize": 10
}

Request parameter

Headers

Body

Response Data

VPP

client mode offboard

Basic information

Path： /op/v0/vpp/oauth2/client/offboard

Method： POST

Interface description：

Request parameter

Headers

Body

Response Data

client mode onboard

Basic information

Path： /op/v0/vpp/oauth2/client/onboard

Method： POST

Interface description：

Request parameter

Headers

Body

Response Data

Inverter-V1

Get device detail

Basic information

Path： /op/v1/device/detail

Method： GET

Interface description：
Obtain inverter details

Request parameter

Headers

Query

Body

Response Data

Get device real-time data

Basic information

Path： /op/v1/device/real/query

Method： POST

Interface description：

Get the latest real-time data of the inverter. The sn array is mandatory and returns only the result set belonging to the current user. If no variable is specified, all variables are queried
request body example:

{
  "sns": ["***************","***************","***************"],
  "variables": ["pvPower","pv1Current"]
}

Request parameter

Headers

Body

Response Data

Inverter

Get device list

Basic information

Path： /op/v0/device/list

Method： POST

Interface description：

Obtain the list of inverters owned by this account
request body example:

{
  "currentPage": 1,
  "pageSize": 10
}

Request parameter

Headers

Body

Response Data

Get device detail (Deprecated)

Basic information

Path： /op/v0/device/detail

Method： GET

Interface description：

Obtain inverter details

Request parameter

Headers

Query

Body

Response Data

Get available variables

Basic information

Path： /op/v0/device/variable/get

Method： GET

Interface description：

Obtain variable tables for use by real-time data and historical data interfaces

Request parameter

Headers

Body

Response Data

Get error code information

Basic information

Path： /op/v0/device/fault/get

Method： GET

Interface description：

Obtain error code information

Request parameter

Headers

Body

Response Data

Get device real-time data (Deprecated)

Basic information

Path： /op/v0/device/real/query

Method： POST

Interface description：

Get the latest real-time data of the inverter, and get the real-time data of all devices under the name without specifying the SN
request body example:

{
  "sn": "***************",
  "variables": ["pvPower","pv1Current"]
}

Request parameter

Headers

Body

Response Data

Get device history data

Basic information

Path： /op/v0/device/history/query

Method： POST

Interface description：

The historical data within the specified 24 hours can be obtained（The begin time and end time are required). If no time period is specified, you can obtain the historical data of the last three days.
request body example:

{
  "sn": "***************",
  "variables": ["pvPower","pv1Current"],
  "begin": 1703548800000,
  "end": 1703635200000
}

Request parameter

Headers

Body

Response Data

Get device production report

Basic information

Path： /op/v0/device/report/query

Method： POST

Interface description：

Obtain the inverter electricity consumption report. Calculated according to the time zone of the power station to which the inverter belongs.The monthly electricity consumption of the year is obtained, the daily electricity consumption of the month is obtained, and the hourly electricity consumption of the day is obtained
request body example:

{
  "sn": "***************",
  "year": 2023,
  "month": 10,
  "day": 3,
  "dimension": "day",
  "variables": ["generation","feedin","gridConsumption","chargeEnergyToTal","dischargeEnergyToTal","PVEnergyTotal"]
}
{
  "sn": "***************",
  "year": 2023,
  "month": 10,
  "dimension": "month",
  "variables": ["generation","feedin","gridConsumption","chargeEnergyToTal","dischargeEnergyToTal","PVEnergyTotal"]
}
{
  "sn": "***************",
  "year": 2023,
  "dimension": "year",
  "variables": ["generation","feedin","gridConsumption","chargeEnergyToTal","dischargeEnergyToTal"]
}

Request parameter

Headers

Body

Response Data

Get device power generation

Basic information

Path： /op/v0/device/generation

Method： GET

Interface description：

Obtain the energy yield information of the inverter based on the time zone of the power station to which the inverter belongs

Request parameter

Headers

Query

Body

Response Data

Get the minimum soc settings for the battery of device

Basic information

Path： /op/v0/device/battery/soc/get

Method： GET

Interface description：

Obtain the inverter battery soc Settings

Request parameter

Headers

Query

Body

Response Data

Set the minmum soc for the battery of the device

Basic information

Path： /op/v0/device/battery/soc/set

Method： POST

Interface description：

Set the minmum soc for the battery of the device
request body example:

{
  "sn": "***************",
  "minSoc": 10,
  "minSocOnGrid": 10
}

Request parameter

Headers

Body

Response Data

Get the setting of battery charging time

Basic information

Path： /op/v0/device/battery/forceChargeTime/get

Method： GET

Interface description：

Obtain the setting of battery charging time

Request parameter

Headers

Query

Body

Response Data

Set the battery charging time

Basic information

Path： /op/v0/device/battery/forceChargeTime/set

Method： POST

Interface description：

Set the battery charging time. The period must be two periods. Both periods must be delivered
request body :

{
  "sn": "sn_4e50c9b8a5c3",
  "enable1": false,
  "enable2": false,
  "startTime1": {
    "hour": 0,
    "minute": 0
  },
  "endTime1": {
    "hour": 0,
    "minute": 0
  },
  "startTime2": {
    "hour": 0,
    "minute": 0
  },
  "endTime2": {
    "hour": 0,
    "minute": 0
  }
}

Request parameter

Headers

Body

Response Data