🔧 硬件控制系统 API 文档

版本 1.0 | 生产就绪
接口地址: https://hcs.bjblk.store/api

🔐 认证方式

接口类型认证要求请求头
公开接口无需认证不需要
安全接口需要 API KeyX-API-Key: your-api-key-here

📋 选择函数

当前选择:
描述: -

🌐 公开接口 无需认证

POST /external/execute

请求体

{
  "function_name": "light_on",
  "source_app": "YourAppName"
}

参数说明

参数名类型必填说明
function_namestring函数名称,从下方列表中选择
source_appstring您的应用标识符(最大50字符)
param_stringstring直接命令参数(高级用户使用)

响应示例(成功)

{
  "success": true,
  "param_string": "P1:1,0,3",
  "function_name": "light_on",
  "message": "Command received and logged"
}

响应示例(失败)

{
  "success": false,
  "error": "Function 'light_on' not found"
}

📱 代码示例

curl -X POST https://hcs.bjblk.store/api/external/execute \
  -H "Content-Type: application/json" \
  -d '{"function_name": "light_on", "source_app": "MyApp"}'
fetch('https://hcs.bjblk.store/api/external/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
        function_name: 'light_on', 
        source_app: 'MyApp' 
    })
})
.then(res => res.json())
.then(console.log)
.catch(console.error);
// Android with OkHttp
OkHttpClient client = new OkHttpClient();

JSONObject json = new JSONObject();
json.put("function_name", "light_on");
json.put("source_app", "MyApp");

RequestBody body = RequestBody.create(
    json.toString(),
    MediaType.parse("application/json")
);

Request request = new Request.Builder()
    .url("https://hcs.bjblk.store/api/external/execute")
    .post(body)
    .build();

client.newCall(request).enqueue(new Callback() {
    public void onResponse(Call call, Response response) {
        Log.d("HCS", response.body().string());
    }
    public void onFailure(Call call, IOException e) {
        Log.e("HCS", e.getMessage());
    }
});
// iOS Swift
let url = URL(string: "https://hcs.bjblk.store/api/external/execute")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")

let body: [String: Any] = [
    "function_name": "light_on",
    "source_app": "MyApp"
]
request.httpBody = try? JSONSerialization.data(withJSONObject: body)

let task = URLSession.shared.dataTask(with: request) { data, _, error in
    guard let data = data else { return }
    print(String(data: data, encoding: .utf8) ?? "")
}
task.resume()
// HarmonyOS ArkTS
import http from '@ohos.net.http';

let httpRequest = http.createHttp();
let body = {
    function_name: 'light_on',
    source_app: 'MyApp'
};

httpRequest.request('https://hcs.bjblk.store/api/external/execute', {
    method: http.RequestMethod.POST,
    header: { 'Content-Type': 'application/json' },
    extraData: JSON.stringify(body)
}, (err, data) => {
    if (!err && data.responseCode === 200) {
        console.info(JSON.parse(data.result));
    }
});
# Python
import requests

response = requests.post(
    'https://hcs.bjblk.store/api/external/execute',
    json={'function_name': 'light_on', 'source_app': 'MyApp'}
)
print(response.json())

⚠️ 错误码

HTTP状态错误码说明
200success请求成功
400invalid_requestJSON格式错误或缺少参数
401unauthorizedAPI Key 无效或缺失
404not_found函数名称不存在
429rate_limited请求频率超限(100次/分钟)
500server_error服务器内部错误

🚦 频率限制

接口限制
/external/execute100 次/分钟
/command-mappings1000 次/分钟
/external/execute-secure50 次/分钟

🔧 Hardware Control System API Documentation

Version 1.0 | Production Ready
Base URL: https://hcs.bjblk.store/api

🔐 Authentication

Endpoint TypeAuthenticationHeader
Public FunctionsNo AuthenticationNone required
Secure FunctionsAPI Key RequiredX-API-Key: your-api-key-here

📋 Select Function

Selected: None
Description: -

🌐 Public Endpoint No Auth

POST /external/execute

Request Body

{
  "function_name": "light_on",
  "source_app": "YourAppName"
}

Parameters

ParameterTypeRequiredDescription
function_namestringYesFunction name from available list
source_appstringYesYour application identifier (max 50 chars)
param_stringstringNoDirect command (advanced users only)

Response (Success)

{
  "success": true,
  "param_string": "P1:1,0,3",
  "function_name": "light_on",
  "message": "Command received and logged"
}

Response (Function Not Found)

{
  "success": false,
  "error": "Function 'light_on' not found"
}

📱 Code Examples

curl -X POST https://hcs.bjblk.store/api/external/execute \
  -H "Content-Type: application/json" \
  -d '{"function_name": "light_on", "source_app": "MyApp"}'
fetch('https://hcs.bjblk.store/api/external/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
        function_name: 'light_on', 
        source_app: 'MyApp' 
    })
})
.then(res => res.json())
.then(console.log)
.catch(console.error);
// Android with OkHttp
OkHttpClient client = new OkHttpClient();

JSONObject json = new JSONObject();
json.put("function_name", "light_on");
json.put("source_app", "MyApp");

RequestBody body = RequestBody.create(
    json.toString(),
    MediaType.parse("application/json")
);

Request request = new Request.Builder()
    .url("https://hcs.bjblk.store/api/external/execute")
    .post(body)
    .build();

client.newCall(request).enqueue(new Callback() {
    public void onResponse(Call call, Response response) {
        Log.d("HCS", response.body().string());
    }
    public void onFailure(Call call, IOException e) {
        Log.e("HCS", e.getMessage());
    }
});
// iOS Swift
let url = URL(string: "https://hcs.bjblk.store/api/external/execute")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")

let body: [String: Any] = [
    "function_name": "light_on",
    "source_app": "MyApp"
]
request.httpBody = try? JSONSerialization.data(withJSONObject: body)

let task = URLSession.shared.dataTask(with: request) { data, _, error in
    guard let data = data else { return }
    print(String(data: data, encoding: .utf8) ?? "")
}
task.resume()
// HarmonyOS ArkTS
import http from '@ohos.net.http';

let httpRequest = http.createHttp();
let body = {
    function_name: 'light_on',
    source_app: 'MyApp'
};

httpRequest.request('https://hcs.bjblk.store/api/external/execute', {
    method: http.RequestMethod.POST,
    header: { 'Content-Type': 'application/json' },
    extraData: JSON.stringify(body)
}, (err, data) => {
    if (!err && data.responseCode === 200) {
        console.info(JSON.parse(data.result));
    }
});
# Python
import requests

response = requests.post(
    'https://hcs.bjblk.store/api/external/execute',
    json={'function_name': 'light_on', 'source_app': 'MyApp'}
)
print(response.json())

⚠️ Error Codes

HTTP StatusCodeDescription
200successRequest successful
400invalid_requestMalformed JSON or missing parameters
401unauthorizedInvalid or missing API key
404not_foundFunction name not found
429rate_limitedRate limit exceeded (100 requests/minute)
500server_errorInternal server error

🚦 Rate Limits

EndpointLimit
/external/execute100 requests per minute
/command-mappings1000 requests per minute
/external/execute-secure50 requests per minute