裕普智汇

REST API 文档

完整的 API 设计和接口规范，助您高效集成裕普智汇服务

API 概述

裕普智汇 API 基于 REST 架构风格设计，采用 HTTPS 协议传输数据，所有接口返回 JSON 格式响应。API 采用统一的认证机制和错误处理方式，支持请求限流和批量操作，方便与企业内部系统集成。

设计原则

资源导向

使用名词而非动词来定义接口，如 /projects、/devices

统一接口

通过 HTTP 方法表达操作：GET（查询）、POST（创建）、PUT（更新）、DELETE（删除）

无状态

每个请求都是独立的，服务器不保存客户端状态

分层系统

客户端无需了解底层实现细节

幂等性

GET、PUT、DELETE 操作具有幂等性，可安全重试

一致性

统一的错误格式、响应结构和命名规范

基础信息

API 地址https://api.yupu.cn/v1
协议HTTPS (TLS 1.2+)
数据格式JSON (application/json)
字符编码UTF-8
时间格式ISO 8601 (如 2026-04-09T10:30:00Z)

认证方式

所有 API 请求都需要在 Header 中包含认证信息。支持 API 密钥认证（适合服务端调用）和 JWT 令牌认证（适合前端调用）。API 密钥具有永久权限，JWT 令牌有效期为 24 小时。

请求与响应格式

请求体使用 JSON 格式，响应也统一采用 JSON 格式。分页查询使用 limit 和 offset 参数，排序使用 sort 参数。列表响应包含 data、total、page 等字段。

请求示例：

POST /api/v1/tasks
Content-Type: application/json
X-API-Key: your_api_key

{
  "project_id": 1,
  "type": "security_scan",
  "devices": [1, 2, 3],
  "options": {
    "scan_level": "full"
  }
}

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "tsk_abc123",
    "status": "pending",
    "created_at": "2026-04-09T10:30:00Z"
  }
}

接口端点

项目接口

GET/api/v1/projects获取项目列表
POST/api/v1/projects创建项目
GET/api/v1/projects/{id}获取项目详情
PUT/api/v1/projects/{id}更新项目
DELETE/api/v1/projects/{id}删除项目

设备接口

GET/api/v1/devices获取设备列表
POST/api/v1/devices添加设备
GET/api/v1/devices/{id}获取设备详情
PUT/api/v1/devices/{id}更新设备
DELETE/api/v1/devices/{id}删除设备

任务接口

GET/api/v1/tasks获取任务列表
POST/api/v1/tasks创建任务
GET/api/v1/tasks/{id}获取任务详情
POST/api/v1/tasks/{id}/cancel取消任务

报告接口

GET/api/v1/reports获取报告列表
GET/api/v1/reports/{id}获取报告详情
GET/api/v1/reports/{id}/download下载报告

错误码说明

错误码含义解决方法
0成功-
1001参数错误检查请求参数格式和必填项
1002认证失败检查 API 密钥或令牌是否正确
1003权限不足检查账户权限设置
2001资源不存在检查请求的资源ID是否正确
2002资源已存在检查是否重复创建
3001任务执行失败查看详细错误信息
4001请求过于频繁降低请求频率
5000服务器内部错误联系技术支持

常见问题

API 请求有频率限制吗？

默认每秒 10 次请求，企业账户可申请提升。如需更高频率，请联系销售。

如何处理网络错误？

建议实现指数退避重试策略，首次失败等待 1 秒，再次失败等待 2 秒，以此类推。

支持批量操作吗？

支持，部分接口支持传入 ID 数组进行批量操作，详情见各接口文档。

响应数据有压缩吗？

支持 gzip 压缩，发送请求时在 Header 中添加 Accept-Encoding: gzip。

← 返回文档中心