开放平台API指南

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

---

# API开放平台对接指南

欢迎使用企业管理数字化中台API开放平台。本文档将指导您如何对接第三方应用到我们的平台。

## 目录

1. [快速开始](#快速开始)
2. [认证方式](#认证方式)
3. [API接口](#api接口)
4. [错误处理](#错误处理)
5. [最佳实践](#最佳实践)
6. [常见问题](#常见问题)

---

## 快速开始

### 1. 创建应用

1. 登录管理后台，进入「API开放平台」
2. 点击「创建应用」按钮
3. 填写应用信息：
   - 应用名称：您的应用名称
   - 应用描述：简要描述应用用途
   - 回调URL（可选）：用于OAuth授权回调
4. 提交申请后，等待管理员审核

### 2. 获取API密钥

应用审核通过后，您可以创建API密钥：

1. 选择已创建的应用
2. 点击「创建密钥」
3. 选择密钥类型：
   - **测试密钥**：用于开发测试环境
   - **生产密钥**：用于正式环境，请谨慎使用
   - **沙箱密钥**：用于沙箱环境测试
4. 系统将生成密钥，格式为：`keyId.keySecret`
   - **重要**：密钥只显示一次，请立即复制并妥善保存！

### 3. 发起API请求

使用获取的API密钥发起请求：

```bash
curl -X GET "http://localhost:5000/api/v1/salary-slips" \
  -H "Authorization: Bearer keyId.keySecret"
```

---

## 认证方式

### API密钥认证

所有API请求都需要在HTTP Header中携带API密钥：

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

或

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

**示例：**

```javascript
const response = await fetch('http://localhost:5000/api/v1/salary-slips', {
  headers: {
    'Authorization': 'Bearer keyId.keySecret'
  }
});
```

### IP白名单

为了提高安全性，您可以在创建密钥时配置IP白名单。只有来自白名单IP的请求才会被接受。

### 速率限制

每个API密钥都有速率限制：

- **小时限制**：默认1000次/小时
- **每日限制**：默认10000次/天

超出限制时，API将返回429状态码：

```json
{
  "success": false,
  "error": "API调用频率超过限制",
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "requestId": "1699999999-abc123"
}
```

---

## API接口

### 统一响应格式

所有API接口都返回统一的响应格式：

**成功响应：**

```json
{
  "success": true,
  "data": {
    // 响应数据
  },
  "timestamp": 1699999999999,
  "requestId": "1699999999-abc123"
}
```

**失败响应：**

```json
{
  "success": false,
  "error": "错误描述",
  "errorCode": "ERROR_CODE",
  "timestamp": 1699999999999,
  "requestId": "1699999999-abc123"
}
```

### 分页响应

对于列表数据，API返回分页响应：

```json
{
  "success": true,
  "data": {
    "items": [
      // 数据列表
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  },
  "timestamp": 1699999999999,
  "requestId": "1699999999-abc123"
}
```

### 主要接口

#### 1. 获取工资条列表

```
GET /api/v1/salary-slips
```

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | number | 否 | 页码，默认1 |
| pageSize | number | 否 | 每页数量，默认20 |
| status | string | 否 | 状态筛选 |
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |

**响应示例：**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "employeeId": "uuid",
        "employeeName": "张三",
        "month": "2024-01",
        "totalSalary": 15000.00,
        "status": "sent"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}
```

#### 2. 获取员工信息

```
GET /api/v1/employees/:id
```

**路径参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | 是 | 员工ID |

**响应示例：**

```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "张三",
    "email": "zhangsan@example.com",
    "phone": "13800138000",
    "department": "技术部",
    "position": "工程师"
  }
}
```

#### 3. 创建工资条

```
POST /api/v1/salary-slips
```

**请求体：**

```json
{
  "employeeId": "uuid",
  "month": "2024-01",
  "basicSalary": 10000.00,
  "performanceBonus": 3000.00,
  "overtimePay": 2000.00,
  "socialInsurance": 1500.00,
  "tax": 500.00,
  "totalSalary": 13000.00,
  "items": [
    {
      "name": "基本工资",
      "amount": 10000.00,
      "type": "income"
    }
  ]
}
```

#### 4. 发送工资条

```
POST /api/v1/salary-slips/:id/send
```

**请求体：**

```json
{
  "channels": ["email", "sms", "wechat"],
  "message": "您的工资条已生成"
}
```

---

## 错误处理

### 错误码

| 错误码 | 说明 | HTTP状态码 |
|--------|------|-----------|
| 1000 | 服务器内部错误 | 500 |
| 1001 | 请求参数错误 | 400 |
| 1002 | 缺少必要参数 | 400 |
| 2000 | 未授权访问 | 401 |
| 2001 | Token已过期 | 401 |
| 2002 | Token无效 | 401 |
| 2003 | 权限不足 | 403 |
| 3000 | 资源不存在 | 404 |
| 4000 | 业务错误 | 400 |
| 5000 | 服务不可用 | 503 |

### 错误处理示例

```javascript
try {
  const response = await fetch('http://localhost:5000/api/v1/employees/xxx', {
    headers: {
      'Authorization': 'Bearer keyId.keySecret'
    }
  });

const result = await response.json();

if (!result.success) {
    // 处理错误
    switch (result.errorCode) {
      case '2000':
        console.error('未授权访问，请检查API密钥');
        break;
      case '3000':
        console.error('资源不存在');
        break;
      default:
        console.error('请求失败:', result.error);
    }
  }
} catch (error) {
  console.error('网络错误:', error);
}
```

---

## 最佳实践

### 1. 安全性

- **保护密钥**：不要在前端代码中暴露API密钥
- **使用HTTPS**：生产环境必须使用HTTPS
- **IP白名单**：配置IP白名单限制访问来源
- **密钥轮换**：定期更换API密钥
- **最小权限原则**：只申请必要的权限

### 2. 错误处理

- **重试机制**：对于网络错误和5xx错误，实现指数退避重试
- **错误日志**：记录所有错误日志，便于排查问题
- **错误提示**：向用户展示友好的错误提示

### 3. 性能优化

- **使用缓存**：对不常变化的数据使用缓存
- **批量请求**：尽量使用批量接口减少请求次数
- **异步处理**：对于耗时操作使用异步接口

### 4. 监控告警

- **监控用量**：监控API调用次数和速率限制
- **性能监控**：监控接口响应时间
- **错误监控**：监控错误率和错误类型

---

## 常见问题

### Q1: API密钥泄露了怎么办？

A: 立即登录管理后台，撤销泄露的密钥，并创建新的密钥。同时检查是否有异常的API调用记录。

### Q2: 如何提高速率限制？

A: 联系平台管理员申请提升速率限制。请提供以下信息：
- 应用名称
- 预期调用量
- 使用场景说明

### Q3: 如何测试API？

A: 建议使用测试密钥在开发环境中测试，不要在生产环境中测试。

### Q4: 如何获取技术支持？

A: 如有问题，请通过以下方式联系我们：
- 邮箱：support@example.com
- 工单系统：在管理后台提交工单

### Q5: API是否支持Webhook？

A: 目前暂不支持Webhook，后续版本会考虑添加该功能。

---

## 更新日志

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

- 初始版本发布
- 支持工资条、员工等核心接口
- 支持API密钥认证

---

## 联系我们

如有任何问题或建议，欢迎联系我们：

- **邮箱**：support@example.com
- **官网**：https://www.example.com
- **文档地址**：https://docs.example.com

---

**最后更新时间**：2024-01-01