HTTP API Integration Overview

Understand the workflow, authentication modes, signing algorithm, integration notes, and SDK entry point.

The Smart Inspection Platform HTTP API is a public interface based on the HTTP protocol (hereinafter referred to as the OpenAPI). It enables third-party systems to interact with the Smart Inspection Platform and provides the capabilities required for custom integrations.

The OpenAPI provides the following core capabilities:

• HTTP communication: Uses standard HTTP to simplify communication between client applications and the Smart Inspection Platform.
• Authentication and authorization: Provides authentication and authorization mechanisms for secure OpenAPI access.
• Core platform capabilities: Exposes key Smart Inspection Platform features, including system, monitoring, task, device, and data management.
• Comprehensive developer resources: Provides detailed documentation and sample code for common integration requirements.

The following diagram shows how the Smart Inspection Platform OpenAPI interacts with a third-party system:

Workflow

The following diagram shows the OpenAPI integration workflow:

Authentication

Signature Authentication

When signature authentication is used, every request must include the generated authentication parameters: the signature (sign), timestamp (timestamp), nonce (nonce), and application key (appKey, which identifies the client). The application secret (secretKey) participates in signature generation locally and must never be sent with the request.

Generate the signature as follows:

Combine the original business parameters (for example, dogCode, command, type, and value) with the current timestamp (timestamp), a nonce (nonce), the application key (appKey, which identifies the client), and the application secret (secretKey). Sort the key-value pairs in ascending lexicographical order by key. Format each pair as key=value, then join the pairs with &. Calculate the MD5 digest of the resulting UTF-8 string, render it as a hexadecimal string, and convert it to uppercase. Do not include a pair whose value is null or a blank string.

#String after sorting
sortStr=appKey=123&command=4&dogCode=001&nonce=kwnHHRwBTRqRaQpt9Krbp2vsjUN3aNvV&secretKey=kQwIOrYvnXmSDkwEiFngrKidMcdrgKor&timestamp=1770283714727&type=2&value=0.6
#Generated signature
sign=4B288C90527FF99B11D364E698744201

The following example shows one way to generate a signature. Implement this logic in the client application:

private static String getSign(Map<String, Object> params) {
    List<Map.Entry<String, Object>> entries = new ArrayList<Map.Entry<String, Object>>(params.entrySet());
    Collections.sort(entries, new Comparator<Map.Entry<String, Object>>() {
        public int compare(Map.Entry<String, Object> arg0, Map.Entry<String, Object> arg1) {
            return (arg0.getKey()).compareTo(arg1.getKey());
        }
    });
    StringBuilder sb = new StringBuilder();
    for (Map.Entry<String, Object> entry : entries) {
        String key = entry.getKey();
        Object value = entry.getValue();
        if (value == null || StrUtil.isBlankIfStr(value)) {
            continue;
        }
        if ("sign".equals(key)) {
            continue;
        }
        sb.append(key).append("=");
        sb.append(value);
        sb.append("&");
    }
    // Remove the trailing ampersand.
    if (sb.length() > 0) {
        sb.deleteCharAt(sb.length() - 1);
    }
    String sortStr = sb.toString();
    // Calculate the MD5 digest, convert it to hexadecimal, and uppercase the result.
    String sign = DigestUtils.md5DigestAsHex(sortStr.getBytes()).toUpperCase();
    return sign;
}

Original business parameters:

{
  "dogCode": "001",
  "type": 2,
  "command": 4,
  "value": "0.6"
}

Add the timestamp (timestamp), nonce (nonce), application key (appKey, which identifies the client), and application secret (secretKey) to the original parameters. Generate sign according to the preceding rules. The complete parameter set used to generate the signature is shown below:

{
  "dogCode": "001",
  "type": 2,
  "command": 4,
  "value": "0.6",
  "appKey": "123",
  "secretKey": "kQwIOrYvnXmSDkwEiFngrKidMcdrgKor",
  "timestamp": "1770355654092",
  "nonce": "g9undAg90K7xBCLUx2NXDDETwQbh9uQ1",
  "sign": "8700F12469316AF6382CE8664CC8C4B3"
}

• appKey: Identifies the third-party client.
• secretKey: Local signing input only; do not include it in the actual request.
• timestamp: Current timestamp; it expires after 15 minutes by default.
• nonce: Random value that makes the request usable only once.
• sign: Generated as described above.

Call the OpenAPI endpoint with the signed request parameters. The process is illustrated below.

Security note: The diagram includes secretKey in its signing data. secretKey is local signing input only and must not be included in the HTTP request; the server retrieves it by appKey when recalculating the signature.

Note: Under Smart Inspection Platform > System Management > Parameter Settings, http_sign_invalid_time controls the signature lifetime (default: 15 minutes), and http_can_repeat controls whether the same request parameters may be reused. When repeated requests are disabled (false, the default), each signed request can be used only once. Reusing it results in an invalid-signature error.

Token Authentication

Token-based authentication is available starting with v1.3.1 and provides a simpler authentication workflow.

In Token mode, the client does not calculate a signature, timestamp, or nonce. It only sends a valid access token in the request header, reducing integration complexity.

Place the Token in the HTTP request header when calling an OpenAPI endpoint:

Header: X-Access-Token: <your_access_token>

Important Notes

• Signature mode uses a dynamic signature and nonce to provide stronger replay-attack protection. Use it when the integration has stricter security requirements.
• Token mode simplifies integration and reduces client-side implementation overhead. It is suitable for rapid development and resource-constrained devices. Select the mode that best fits the deployment.
• Do not mix authentication modes. A request must use either a Token or signature parameters, never both.
• Authentication credentials (appKey, secretKey, and accessToken) are issued through an authorization code. Their validity cannot exceed the authorization code’s overall validity period. Reauthorize the integration after they expire.

Required Integration Information

• OpenAPI endpoint: IP address + port 23288.
• RocketMQ NameServer: IP address + port 29876.
• Authentication credentials: a Token or an appKey / secretKey pair.

SDK

The official Java SDK is available with Smart Inspection Platform v1.3.1 and later.

For custom integrations built with JDK 17 and Spring Boot 3, we recommend the official station-openapi-devkit. The SDK covers all 27 HTTP operations currently exposed by the platform, provides consistent data models, pagination, response parsing, and exception handling, and supports both signature and token authentication.

• Simplified integration: Encapsulates HTTP calls, authentication parameter construction, and response parsing to reduce repetitive integration code.
• Reliable calls: Provides timeout configuration, controlled retries, explicit handling for unknown write or control results, and streaming file downloads.
• Complete resources: Includes bilingual documentation, a runnable Spring Boot Sample, and optional RocketMQ message integration.

Project: station-openapi-devkit

Sample: Spring Boot Sample

Ready to integrate? Go to SDK Development for project resources, quickstart, authentication, and advanced guides.