🔌 智香外部应用集成

📝 开发者注册

注册后我们将发送 App ID 和 App Secret 到您的邮箱。

公司名称 *

联系邮箱 *

应用ID (App ID) * 您的应用唯一标识符

应用版本 (App Version) * 您应用的当前版本号

集成用途说明 *

预计月调用量 < 1,000次 1,000 - 10,000次 10,000 - 100,000次 > 100,000次

📧 注册并获取API密钥

🔌 API端点

POST https://真香.cn/api/external/execute

🔐 认证方式

使用 Bearer Token 进行认证：

Authorization: Bearer <your_app_secret>

📤 请求体

{
    "app_id": "com.yourapp",           // 您的应用ID
    "function_name": "start_heater",   // 函数名称（从映射表中获取）
    "user_id": 12345,                  // 目标用户ID（可选）
    "device_id": "DEVICE_001",         // 目标设备ID（可选）
    "parameters": {                    // 自定义参数（可选）
        "temperature": 75,
        "duration": 10
    }
}

📥 响应

{
    "success": true,
    "message": "Command executed successfully",
    "execution_time_ms": 150,
    "command_sent": "P1:1G100C3",
    "log_id": 12345
}

⚡ 限流规则

限制类型	数值
默认限流	100次/分钟
突发峰值	10次/秒
升级限流	联系客服获取更高额度

⚠️ 错误码说明

错误码	说明	解决方案
401	未授权	App Secret 无效或缺失
403	应用未授权	管理员尚未批准您的应用
404	函数不存在	function_name 未在 command_mappings 中配置
422	版本不兼容	用户应用版本过低，需升级
429	超出限流	请降低请求频率
500	服务器错误	请稍后重试

💻 JavaScript (Node.js / Browser)

// Node.js (using axios)
const axios = require('axios');

const APP_ID = 'com.yourapp';
const APP_SECRET = 'your_app_secret_here';

async function executeCommand(functionName, userId, parameters = {}) {
    try {
        const response = await axios.post(
            'https://真香.cn/api/external/execute',
            {
                app_id: APP_ID,
                function_name: functionName,
                user_id: userId,
                parameters: parameters
            },
            {
                headers: {
                    'Authorization': `Bearer ${APP_SECRET}`,
                    'Content-Type': 'application/json'
                }
            }
        );

        console.log('✅ Success:', response.data);
        return response.data;
    } catch (error) {
        console.error('❌ Error:', error.response?.data || error.message);
        throw error;
    }
}

// 使用示例
executeCommand('start_heater', 12345, { temperature: 75 })
    .then(result => console.log('Command executed in', result.execution_time_ms, 'ms'));

🐍 Python

import requests

APP_ID = 'com.yourapp'
APP_SECRET = 'your_app_secret_here'

def execute_command(function_name, user_id, parameters=None):
    url = 'https://真香.cn/api/external/execute'
    headers = {
        'Authorization': f'Bearer {APP_SECRET}',
        'Content-Type': 'application/json'
    }
    payload = {
        'app_id': APP_ID,
        'function_name': function_name,
        'user_id': user_id,
        'parameters': parameters or {}
    }

    response = requests.post(url, json=payload, headers=headers)

    if response.status_code == 200:
        print('✅ Success:', response.json())
        return response.json()
    else:
        print('❌ Error:', response.status_code, response.text)
        return None

# 使用示例
execute_command('start_heater', 12345, {'temperature': 75})

📱 cURL

curl -X POST https://真香.cn/api/external/execute \
    -H "Authorization: Bearer your_app_secret_here" \
    -H "Content-Type: application/json" \
    -d '{
        "app_id": "com.yourapp",
        "function_name": "start_heater",
        "user_id": 12345,
        "parameters": {
            "temperature": 75
        }
    }'

📋 可用函数示例

// 从 command_mappings 表中获取
{
    "function_name": "start_heater",
    "param_string": "P1:1G100C3",
    "description": "启动加热器"
},
{
    "function_name": "stop_heater",
    "param_string": "P1:0G0C0",
    "description": "停止加热器"
},
{
    "function_name": "start_vibration",
    "param_string": "P2:1G50C5",
    "description": "启动震动"
}

联系管理员获取完整的函数列表

❓ 常见问题

如何开始接入？

填写上方的注册表单，我们会在24小时内将 App ID 和 App Secret 发送到您的邮箱。

什么是 function_name？

function_name 是管理员在 command_mappings 表中预先配置的函数名称。每个函数名称对应一个硬件指令（param_string）。

如何获取可用函数列表？

联系管理员，他们会提供当前可用的 function_name 列表及其对应的硬件动作说明。

App Secret 是什么？

App Secret 是您应用的认证密钥，用于签名API请求。请妥善保管，不要泄露。

如果用户应用版本过低会怎样？

指令会被拒绝，返回错误码422（版本不兼容）。用户需要升级应用版本。

调用频率限制是多少？

默认限制为100次/分钟。如需更高额度，请联系客服。

如何获得技术支持？

邮箱：api-support@zdht.com | 微信：zdht_support