API 接口文档

---

一、通用约定

• 基础地址：https://api.　　.example.com/v1
• 鉴权方式：Bearer Token，请求头 Authorization: Bearer <access_token>
• 数据格式：请求与响应均为 application/json; charset=utf-8
• 时间格式：ISO 8601，如 2026-　-　T　　:　　:　　+08:00

二、端点总览

方法	路径	功能	鉴权	限流
POST	/	创建	必需	次/分
GET	/　　/{id}	查询单个	必需	次/分
GET	/	分页列表	必需	次/分
PUT	/　　/{id}	更新	必需	次/分
DELETE	/　　/{id}	删除　　（软删除）	必需	次/分

三、接口详情

3.1 创建　　

POST /v1/　　

请求参数

参数	类型	必填	说明
name	string	是	名称，长度 1—　　字符
type	enum	是	枚举值：　　/　　/
remark	string	否	备注，最长 　　字

响应字段

字段	类型	说明
code	int	0 表示成功，其余见错误码表
data.id	string	全局唯一标识
data.created_at	string	创建时间

调用示例

curl -X POST https://api.　　.example.com/v1/　　\
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "　　", "type": "　　"}'

3.2 查询　　

GET /v1/　　/{id}?with_details=true——路径参数 id 必填；查询参数说明：　

四、错误码

HTTP 状态	业务码	含义	处理建议
400	40001	参数校验失败	按 message 中的字段提示修正入参
401	40101	Token 无效或过期	刷新 Token 后重试
403	40301	无权限	联系管理员开通权限
404	40401	资源不存在	检查 id 是否正确
429	42901	触发限流	按 Retry-After 头退避重试