API 概览

NOLUX 提供 RESTful API 接口，支持外部系统集成和二次开发。本文档介绍 API 的通用规范。

基础信息

项目	说明
基础 URL	https://api.nolux.cn/api/v1
协议	HTTPS（强制）
数据格式	JSON
字符编码	UTF-8
时区	UTC（响应中的时间戳均为 ISO 8601 格式）
API 版本	v1（通过 URL 路径区分）

认证方式

所有 API 请求（除登录接口外）需在请求头中携带 JWT Access Token：

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

详细的认证流程参见 认证 API。

请求格式

通用请求头

Content-Type: application/json
Authorization: Bearer {access_token}
X-Tenant-ID: {tenant_id}
Accept-Language: zh-CN

请求头	必填	说明
Authorization	是	JWT Access Token
Content-Type	是	固定为 application/json
X-Tenant-ID	否	租户 ID（多租户用户切换租户时使用）
Accept-Language	否	响应语言，默认 zh-CN

请求体规范

• POST、PUT、PATCH 请求使用 JSON 格式的请求体
• GET、DELETE 请求使用 URL 查询参数
• 所有字段名使用 snake_case 命名
• 日期时间格式：2026-03-14T10:30:00Z（ISO 8601）
• 金额单位：分（integer），显示时自行转换为元

响应格式

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "uuid-string",
    "name": "示例数据"
  }
}

列表响应（分页）

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {"id": "1", "name": "项目 A"},
      {"id": "2", "name": "项目 B"}
    ],
    "total": 100,
    "page": 1,
    "page_size": 20,
    "pages": 5
  }
}

错误响应

{
  "code": 422,
  "message": "参数校验失败",
  "errors": [
    {
      "field": "email",
      "message": "邮箱格式不正确"
    }
  ]
}

分页

列表接口统一支持分页查询：

参数	类型	默认值	说明
page	integer	1	页码，从 1 开始
page_size	integer	20	每页条数，最大 100
sort_by	string	created_at	排序字段
sort_order	string	desc	排序方向：asc / desc

示例：

GET /api/v1/products?page=2&page_size=50&sort_by=name&sort_order=asc

筛选

列表接口支持通过查询参数进行筛选：

GET /api/v1/orders?status=paid&channel=tmall&date_from=2026-03-01&date_to=2026-03-14

常用筛选参数：

参数	说明	示例
status	状态筛选	status=active
channel	渠道筛选	channel=tmall
date_from	开始日期	date_from=2026-03-01
date_to	结束日期	date_to=2026-03-14
keyword	关键词搜索	keyword=面膜

错误码

HTTP 状态码

状态码	说明
200	请求成功
201	创建成功
204	删除成功（无返回体）
400	请求参数错误
401	未认证（Token 缺失或过期）
403	无权限（RBAC 校验失败）
404	资源不存在
409	资源冲突（如重复创建）
422	参数校验失败
429	请求频率超限
500	服务器内部错误

业务错误码

错误码	说明
AUTH_001	用户名或密码错误
AUTH_002	账号已被禁用
AUTH_003	Refresh Token 已过期
TENANT_001	租户不存在
TENANT_002	租户已暂停
QUOTA_001	API 调用配额已用尽
QUOTA_002	AI Token 配额已用尽
QUOTA_003	连接器数量已达上限
PERM_001	无操作权限
PERM_002	数据范围越权

限流

API 根据订阅方案实施请求频率限制：

方案	限流策略
Starter	1,000 次/日，60 次/分钟
Growth	10,000 次/日，300 次/分钟
Enterprise	100,000 次/日，1,000 次/分钟
Custom	按协议配置

限流响应头：

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1710410400

超出限流时返回 429 Too Many Requests：

{
  "code": 429,
  "message": "请求频率超限，请稍后重试",
  "retry_after": 30
}

SDK 与工具

API 文档

NOLUX 提供交互式 API 文档：

• Swagger UI：https://api.nolux.cn/docs
• ReDoc：https://api.nolux.cn/redoc
• OpenAPI 规范：https://api.nolux.cn/openapi.json

cURL 示例

# 获取商品列表
curl -X GET "https://api.nolux.cn/api/v1/products?page=1&page_size=20" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

建议

在开发过程中，建议使用 Swagger UI 进行接口调试，它提供了完整的请求/响应示例和在线测试功能。

---

相关文档

• 认证 API — 登录与 Token 管理
• 连接器 API — 连接器管理接口
• AI 服务 API — AI 模型路由接口