# 后台接入

鉴权、接口调用与回调，国内与海外域名与限速差异，日志与监控。

## 鉴权

所有 API 请求都需要进行身份验证。

### API 密钥

在请求头中包含您的 API 密钥：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

### 请求签名

对于敏感操作，需要使用签名验证：

```javascript
const crypto = require('crypto')

function generateSignature(params, secret) {
    const sortedParams = Object.keys(params)
        .sort()
        .map(key => `${key}=${params[key]}`)
        .join('&')
    
    return crypto
        .createHmac('sha256', secret)
        .update(sortedParams)
        .digest('hex')
}
```

## 接口调用

### RESTful API

基础 URL：
- 国内：`https://api.jueyuan.com`
- 海外：`https://api-global.jueyuan.com`

### 示例请求

```javascript
const axios = require('axios')

const client = axios.create({
    baseURL: 'https://api.jueyuan.com',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
})

// 获取设备列表
const devices = await client.get('/v1/devices')

// 发送消息到设备
await client.post('/v1/devices/device-id/messages', {
    type: 'text',
    content: 'Hello World'
})
```

### 限速说明

不同接口有不同的限速策略：

- **普通接口**：100 次/分钟
- **高频接口**：1000 次/分钟
- **批量接口**：10 次/分钟

超过限速会返回 `429 Too Many Requests` 错误。

## 回调处理

### Webhook 配置

在开发者平台配置 Webhook URL，系统会在事件发生时调用该 URL。

### 回调验证

```javascript
const crypto = require('crypto')

function verifyCallback(signature, payload, secret) {
    const hash = crypto
        .createHmac('sha256', secret)
        .update(JSON.stringify(payload))
        .digest('hex')
    
    return hash === signature
}
```

### 回调事件

常见回调事件：

- `device.connected` - 设备连接
- `device.disconnected` - 设备断开
- `message.received` - 收到消息
- `voice.recognized` - 语音识别完成

## 日志与监控

### 日志查询

```javascript
// 查询设备日志
const logs = await client.get('/v1/devices/device-id/logs', {
    params: {
        startTime: '2024-01-01T00:00:00Z',
        endTime: '2024-01-02T00:00:00Z',
        level: 'error'
    }
})
```

### 监控指标

- API 调用次数
- 错误率
- 响应时间
- 设备在线率