Frequently Asked Questions

General

How do I apply for API access?

The self-service registration feature is not yet available. All API access requests must be submitted via email. Please refer to the Quick Start page for details.

When submitting your request, please include the customer’s SolisCloud account (phone number or email address) and their role (Organization or Owner).

What is the difference between User-level Authorization and OAuth2.0 Authorization?

Item	User-level Authorization	OAuth2.0 Authorization
Target Users	Plant owners and installers	Third-party service providers and monitoring platforms
Account Required	SolisCloud login account	No account required
Authentication	Custom HMAC-SHA1 Signature	OAuth2.0 Bearer Token
Data Scope	Own or shared plants	Owner-authorized plants only

What are the API rate limits?

• Data access interfaces: 10 requests/second
• Device control interfaces (control / atRead / result): 2 requests/second
• Strategy interfaces (strategySetting / currentStrategyGet): 10 requests/second
• Plant month/year energy reports: 10 requests/second

If these limits do not meet your throughput requirements, please consider using Real-time Data Forwarding.

What is the data refresh frequency?

Device telemetry is updated every 5 minutes.

---

Authorization

HMAC-SHA1 Signature Algorithm: How to calculate request headers & troubleshoot sign errors

User-level Authorization (owners/installers) uses a custom HMAC-SHA1 signature. Each request must include the following 4 headers:

Header	Description
Content-MD5	MD5 of the body, converted to a 128-bit binary array, then Base64-encoded
Content-Type	Fixed value: application/json;charset=UTF-8
Date	GMT time, format EEE, d MMM yyyy HH:mm:ss 'GMT', within ±15 minutes
Authorization	API {apiId}:{sign}

The signing string joins the following with newline characters \n:

POST\n{Content-MD5}\n{Content-Type}\n{Date}\n{CanonicalizedResource}

Where:

• CanonicalizedResource is the target endpoint path, e.g. /v1/api/userStationList
• sign = Base64(HmacSHA1(apiSecret, signingString))

Signature Verification Tools

• Online HMAC tool: https://dinochiesa.github.io/hmachash/index.html — select HmacSHA1, use your KeySecret as the key, input the signing string, and Base64-encode the output to get sign
• Java full example download: Authorization.java

How to Verify Your Calculation

Reproduce the official example. For the body {"pageNo":1,"pageSize":10}, the Content-MD5 is always:

kxdxk7rbAsrzSIWgEwhH4w==

Compute MD5 + Base64 of {"pageNo":1,"pageSize":10} in your own code:

• If the result equals kxdxk7rbAsrzSIWgEwhH4w==, your Content-MD5 step is correct.
• If not, confirm you are hashing the raw body string (no URL encoding, no extra whitespace) and Base64-encoding the 128-bit binary digest.

sign error Troubleshooting Checklist

If the API returns sign error or signature validation failure, check each item:

• Authorization header format: API {apiId}:{sign} (note the space after API)
• Signing string sequence: POST\n{Content-MD5}\n{Content-Type}\n{Date}\n{CanonicalizedResource}
• Content-Type in the signing string must match the actual request header (application/json;charset=UTF-8)
• Date must be within ±15 minutes of server time, formatted as EEE, d MMM yyyy HH:mm:ss 'GMT'
• Content-MD5 must be the Base64-encoded MD5 hash of the raw request body (not a hex string)
• CanonicalizedResource must be the full endpoint path (including /v1/api/ or /v2/api/ prefix)

See the Authorization page for complete Python / Node.js / Java examples.

What should I do if my KeySecret is compromised?

Please log in to the SolisCloud web portal immediately, navigate to Service → API Management, and regenerate your API keys.

What should I do if my Access Token expires?

The OAuth2.0 Access Token is valid for 1 day, and the Refresh Token is valid for 30 days. Please refresh your Access Token proactively before the Refresh Token expires.

If the Refresh Token has also expired, the plant owner must complete the full authorization flow again.

How long is the authorization code valid?

The authorization code is valid for 30 minutes and can only be used once. Please exchange it for an Access Token promptly after receipt.

---

API Calling

What should I do if I receive a “time deviation too large” error?

User-level authorization requires the Date header to be within ±15 minutes of the server time. Please verify your local server clock and ensure the timestamp is formatted in GMT timezone as specified.

How do I query multiple devices in a single request?

Data access interfaces support batch queries via the snList parameter (inverters / collectors) or idList parameter (plants). Each call returns up to 100 devices. The cursor pagination parameter minId (starting ID) is now available; to page deeper, use the minId cursor (pass the last record's ID + 1). See Pagination for details.

What is the `modbusAddr` parameter in control interfaces?

modbusAddr (Modbus register address) identifies the register targeted by a control command. It must be used together with value (the value to write) and functionCode (function code: 03 / 04 / 06). Different register addresses map to different control functions (e.g., power limit adjustment, operating mode switch). For the full register address definitions, please refer to the register communication protocol section of the Device Control documentation.

Alternatively, you can use the atCommand parameter to pass through a raw AT command string.

About cid

The legacy cid (Control ID) based control approach is being phased out. New integrations should use the modbusAddr approach.

---

Plant Management

How do I create a plant and bind an inverter?

Use the addStationBindCollector endpoint to create a plant and bind a collector. To bind an inverter, use the addDevice endpoint.

How do I revoke plant sharing with a third party?

You may use the plant unbind or cancel-sharing endpoint via the API, or manage it manually through the SolisCloud App or web portal under plant sharing settings.

---

Real-time Data Forwarding

Which protocols are supported for real-time data forwarding?

RocketMQ, MQTT, and HTTP callback are all supported. Select the protocol that best fits your system architecture and business requirements.

Is there a rate limit for real-time data forwarding?

Real-time data forwarding delivers data at second-level intervals with no rate limit, making it suitable for high-frequency data acquisition and event-driven scenarios.

---

Troubleshooting

What should I do when the API returns a 404 error?

A 404 response indicates that the requested endpoint path does not exist. Common causes:

• Incorrect path: Verify the path exactly matches the documentation, including correct casing and slash usage
• Wrong API version: Path prefixes differ by authorization type and interface category — they must not be mixed:
  • User-level auth (HMAC): data access and plant management use /v1/api/; device control uses /v2/api/
  • OAuth2.0: data access uses /api/access_data/; device control uses /api/control_device/
• Authorization type mismatch: HMAC signature endpoints do not accept Bearer Tokens, and vice versa

What should I do when the API returns a 500 error?

A 500 response indicates a server-side error. Recommended steps:

1. Verify that all required parameters conform to the documentation (correct data types, formats, and mandatory fields)
2. Confirm the Content-MD5 value is calculated correctly (MD5 of the raw request body, then Base64-encoded)
3. Retry after a brief interval; if the issue persists, contact the integration team and provide a request sample with timestamp
4. Ensure the request body is valid JSON and that Content-Type is set to application/json;charset=UTF-8

What should I do when requests time out or receive no response?

• DNS resolution: Confirm you are connecting to the correct API domain (CN region: api.ginlong.com; Global: www.soliscloud.com)
• Network restrictions: Verify that your server’s firewall or outbound traffic rules permit HTTPS (port 443) connections to the API domain
• Rate limiting: Data access is limited to 10 req/sec; control interfaces to 2 req/sec — implement retry logic with appropriate backoff intervals
• Client timeout: Configure your HTTP client timeout to at least 30 seconds

What should I do when OAuth2.0 returns a 401 error or an invalid token response?

• Verify the Authorization header format: Bearer {access_token} (capital “B” in “Bearer”)
• The Access Token is valid for 1 day — use the Refresh Token to obtain a new one before expiry
• The Refresh Token is valid for 30 days — after expiry, the plant owner must re-authorize
• Confirm the token was issued by the correct environment (CN and Global domains maintain separate token namespaces)

---

Other

What languages are supported?

The developer platform documentation is currently available in Simplified Chinese and English. Certain API endpoints also support a lang parameter to control the language of returned data.