开放 API 接口文档

## 认证方式

所有接口都需要在 URL 路径中传递 API Key 进行认证。

```
GET https://xiao.wisg.cn/api/v1/{apikey}/...
```

其中 `{apikey}` 为用户的 API Key。

---

## 1. 查询设备列表

### 接口地址
```
GET /v1/{apikey}/devices
```

### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| udid | string | 否 | 设备 UDID |
| phoneNumber | string | 否 | 设备号码 |
| online | boolean | 否 | 在线状态筛选，true-在线，false-离线 |

### 响应示例
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "udid": "device001",
      "imei": "123456789012345",
      "iccid": "89860112345678901234",
      "deviceName": "设备1",
      "phoneNumber": "13800138000",
      "model": "iPhone 12",
      "version": "1.0.0",
      "online": true,
      "rsrp": -85
    }
  ]
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | number | 设备ID |
| udid | string | 设备 UDID |
| imei | string | 设备 IMEI |
| iccid | string | SIM 卡 ICCID |
| deviceName | string | 设备名称 |
| phoneNumber | string | 设备号码 |
| model | string | 设备型号 |
| version | string | 设备版本 |
| online | boolean | 在线状态 |
| rsrp | number | 信号强度 (RSRP) |

---

## 2. 查询通道模板列表

### 接口地址
```
GET /v1/{apikey}/channels
```

### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | string | 否 | 通道类型 |
| name | string | 否 | 通道名称（支持模糊查询） |

### 响应示例
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "默认通道",
      "type": "default",
      "detail": "默认通道配置"
    }
  ]
}
```

---

## 3. 查询接收短信

### 接口地址
```
GET /v1/{apikey}/messages/received
```

### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|---------|------|
| udid | string | 否 | - | 设备 UDID |
| address | string | 否 | - | 发送方号码 |
| keyword | string | 否 | - | 短信内容关键词（支持模糊查询） |
| limit | number | 否 | 10 | 返回条数限制 |
| offset | number | 否 | 0 | 偏移量 |

### 响应示例
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "udid": "device001",
      "address": "13800138000",
      "body": "验证码123456",
      "timestamp": "2024-01-01 10:00:00"
    }
  ]
}
```

### 说明
- 如果不传 `udid` 参数，则查询当前用户所有设备的接收短信
- 如果传入 `udid`，则只查询指定设备的接收短信
- `keyword` 参数会对短信内容进行模糊匹配

---

## 4. 查询发送短信

### 接口地址
```
GET /v1/{apikey}/messages/sent
```

### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|---------|------|
| udid | string | 否 | - | 设备 UDID |
| address | string | 否 | - | 接收方号码 |
| keyword | string | 否 | - | 短信内容关键词（支持模糊查询） |
| status | string | 否 | - | 发送状态 |
| limit | number | 否 | 10 | 返回条数限制 |
| offset | number | 否 | 0 | 偏移量 |

### 响应示例
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "udid": "device001",
      "address": "13900139000",
      "body": "测试短信",
      "status": "success",
      "timestamp": "2024-01-01 10:00:00"
    }
  ]
}
```

### 说明
- 如果传入 `udid`，则只查询指定设备的发送短信
- `keyword` 参数会对短信内容进行模糊匹配
- `status` 参数用于筛选发送状态

---

## 5. 发送短信

### 接口地址
```
POST /v1/{apikey}/messages/send
```

### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| udidList | array | 是 | 设备 UDID 数组 |
| content | string | 是 | 短信内容 |
| address | string | 是 | 接收方号码 |

### 请求示例
```json
{
  "udidList": ["device001", "device002"],
  "content": "测试短信",
  "address": "13900139000"
}
```

### 响应示例
```json
{
  "success": true,
  "data": [
    {
      "udid": "device001",
      "msgId": "123",
      "success": true,
      "message": "发送成功"
    },
    {
      "udid": "device002",
      "msgId": "124",
      "success": true,
      "message": "发送成功"
    }
  ]
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| data | array | 发送结果数组 |
| data[].udid | string | 设备 UDID |
| data[].msgId | string | 短信 ID，用于查询发送状态 |
| data[].success | boolean | 是否发送成功 |
| data[].message | string | 结果消息 |

### 说明
- 支持向多个设备发送短信，使用数组传递 UDID
- 每个设备的发送结果独立返回
- `msgId` 可用于后续查询短信发送状态
- 如果设备不在线或无权限，对应的 `success` 为 `false`

---

## 6. 查询短信状态

### 接口地址
```
GET /v1/{apikey}/messages/status
```

### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| msgId | string | 是 | 短信 ID，多个 ID 使用逗号分隔 |

### 请求示例
```
GET /v1/your-apikey/messages/status?msgId=123,124,125
```

### 响应示例
```json
{
  "success": true,
  "data": {
    "123": "1",
    "124": "0",
    "125": "2"
  }
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| data | object | 短信状态对象，key 为 msgId，value 为状态 |

### 说明
- 支持批量查询多个短信的状态
- 状态值：
  - "1" 表示已发送
  - "0" 表示待发送
  - "2" 表示短信未找到
- 如果 msgId 不存在，返回 "2"（短信未找到）

---

## 错误响应

所有接口在发生错误时都会返回统一的错误格式：

```json
{
  "success": false,
  "message": "错误信息"
}
```

### 常见错误码

| HTTP 状态码 | 说明 |
|------------|------|
| 400 | 请求参数错误或设备不存在 |
| 401 | API Key 无效或已禁用 |
| 500 | 服务器内部错误 |

---

## 注意事项

1. 所有接口都需要在 URL 路径中传递有效的 API Key
2. API Key 必须处于启用状态才能使用
3. 每个用户只能查询自己的设备和数据
4. 分页参数 `limit` 和 `offset` 建议设置合理的值，避免一次性获取过多数据