开放平台API说明

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

# API开放平台使用说明

## 访问地址

- **管理端入口**：`/admin/openplatform`
- **API文档页面**：`/admin/openplatform/docs`
- **开放平台对接指南**：查看项目根目录下的 `docs/API_OPEN_PLATFORM_GUIDE.md`

## 主要功能

### 1. 应用管理

- 创建和管理第三方应用
- 查看应用基本信息
- 管理应用状态（审核、激活、禁用）
- 查看应用调用统计

### 2. 密钥管理

- 创建API密钥（测试/生产/沙箱）
- 配置密钥权限和IP白名单
- 查看密钥使用统计
- 撤销不需要的密钥

### 3. API文档

- 自动同步所有API接口文档
- 按分类和方法筛选接口
- 查看接口详细说明
- 导出OpenAPI规范

### 4. 使用统计

- 查看API调用统计
- 分析请求成功率
- 监控响应时间

## API路由

### 应用管理接口

```
GET    /api/openplatform/applications        # 获取应用列表
POST   /api/openplatform/applications        # 创建应用
PUT    /api/openplatform/applications/:id    # 更新应用
DELETE /api/openplatform/applications/:id    # 删除应用
```

### 密钥管理接口

```
GET    /api/openplatform/applications/:id/keys      # 获取密钥列表
POST   /api/openplatform/applications/:id/keys      # 创建密钥
DELETE /api/openplatform/keys/:id                   # 撤销密钥
```

### 文档接口

```
GET    /api/openplatform/docs/sync   # 获取OpenAPI规范
POST   /api/openplatform/docs/sync   # 同步API文档（仅管理员）
```

## API认证

### API密钥格式

```
keyId.keySecret
```

### 请求头格式

```
Authorization: Bearer keyId.keySecret
```

或

```
X-API-Key: keyId.keySecret
```

## 速率限制

- 默认小时限制：1000次/小时
- 默认每日限制：10000次/天
- 可在创建密钥时自定义限制

## 错误码

| 错误码 | 说明 |
|--------|------|
| 1000 | 服务器内部错误 |
| 1001 | 请求参数错误 |
| 2000 | 未授权访问 |
| 2001 | Token已过期 |
| 3000 | 资源不存在 |
| 4000 | 业务错误 |
| 5000 | 服务不可用 |

## 集成示例

### JavaScript/TypeScript

```typescript
// 获取工资条列表
const response = await fetch('http://localhost:5000/api/v1/salary-slips', {
  headers: {
    'Authorization': 'Bearer keyId.keySecret',
    'Content-Type': 'application/json'
  }
});

const result = await response.json();

if (result.success) {
  console.log('工资条列表:', result.data);
} else {
  console.error('请求失败:', result.error);
}
```

### cURL

```bash
# 获取工资条列表
curl -X GET "http://localhost:5000/api/v1/salary-slips" \
  -H "Authorization: Bearer keyId.keySecret"

# 创建工资条
curl -X POST "http://localhost:5000/api/v1/salary-slips" \
  -H "Authorization: Bearer keyId.keySecret" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": "uuid",
    "month": "2024-01",
    "totalSalary": 15000.00
  }'
```

### Python

```python
import requests

headers = {
    'Authorization': 'Bearer keyId.keySecret',
    'Content-Type': 'application/json'
}

response = requests.get(
    'http://localhost:5000/api/v1/salary-slips',
    headers=headers
)

result = response.json()

if result['success']:
    print('工资条列表:', result['data'])
else:
    print('请求失败:', result['error'])
```

## 开发建议

### 1. 安全性

- 不要在前端代码中暴露API密钥
- 使用HTTPS进行API调用
- 配置IP白名单限制访问来源
- 定期轮换API密钥

### 2. 错误处理

- 实现指数退避重试机制
- 记录所有API调用日志
- 监控错误率和错误类型

### 3. 性能优化

- 对不常变化的数据使用缓存
- 尽量使用批量接口
- 实现异步处理

### 4. 监控告警

- 监控API调用次数
- 监控接口响应时间
- 设置合适的告警阈值

## 更新日志

### v1.0.0 (2024-01-15)

- 初始版本发布
- 支持应用和密钥管理
- 支持API文档自动生成
- 支持API密钥认证
- 支持速率限制

## 技术支持

如有问题，请联系：

- **文档地址**：`docs/API_OPEN_PLATFORM_GUIDE.md`
- **示例代码**：参考本README中的集成示例

## 下一步

1. 访问 `/admin/openplatform` 创建应用
2. 生成API密钥
3. 阅读完整对接指南文档
4. 开始集成API到您的应用