API接口文档

通用说明

所有 API 均以 JSON 格式交互，请求头需声明 Content-Type: application/json（GET 请求除外）。

AppId / AppSecret 获取：登录管理后台 →「系统 / API 应用」创建或编辑一个应用，获取 app_id 与 app_secret。应用需处于「启用」状态方可调用。

响应格式

所有接口统一返回如下 JSON 结构：

{
  "code": 200,                  // 业务状态码，200 表示成功，其他见错误码表
  "message": "success",         // 文案描述
  "data": { ... } | null,       // 业务数据，失败时为 null
  "timestamp": 1777710860       // 服务器 Unix 时间戳
}

鉴权方式

除「获取访问令牌」接口外，其余接口均需在请求头携带访问令牌：

Authorization: Bearer {access_token}

access_token 通过「1. 获取访问令牌」接口获取，有效期 7200 秒（2 小时），过期后需重新获取。

错误码

错误响应示例：

{
  "code": 401,
  "message": "访问令牌无效或已过期",
  "data": null,
  "timestamp": 1777710860
}

限流策略

IP 白名单

业务接口启用 IP 白名单校验。每个应用在后台「API 应用」编辑处可配置：

• 全部放行（all）：允许任意 IP 调用
• 白名单（whitelist）：仅允许配置的 IP 列表调用，其他 IP 返回 403 IP地址不在白名单中

⚠ 未配置白名单时默认拒绝所有 IP 调用。新接入方需先在后台配置 IP 白名单。

1. 获取访问令牌

使用 AppId 和 AppSecret 获取访问令牌，用于后续接口的 Bearer 认证。

请求参数

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "access_token": "eyJhcHBfaWQiOiJ0ZXN0X2FwcF8wMDEiLCJpc3IiOiJHSi1BUEkiLCJleHAiOjE3Nzc3MjAwMDB9.abc123xxx",
    "expires_in": 7200,
    "token_type": "Bearer"
  },
  "timestamp": 1777710860
}

错误响应

// 401 应用ID不存在或密钥错误
{ "code": 401, "message": "应用ID不存在" | "应用密钥错误", "data": null, "timestamp": ... }

// 403 应用已被禁用
{ "code": 403, "message": "应用已被禁用", "data": null, "timestamp": ... }

// 429 限流（5分钟内失败次数过多）
{ "code": 429, "message": "请求过于频繁，已锁定 5 分钟", "data": null, "timestamp": ... }

2. 用户注册

请求头

请求参数

成功响应

{
  "code": 200,
  "message": "注册成功",
  "data": {
    "user_id": 123,
    "name": "testuser",
    "email": "test@example.com",
    "phone": "13800138000",
    "cert_status": "uncertified"
  },
  "timestamp": 1777710860
}

错误响应

// 422 参数验证失败（邮箱已被注册/格式错误、密码不足6位等）
{ "code": 422, "message": "The email has already been taken.", "data": null, "timestamp": ... }

3. 用户登录

请求头

请求参数

成功响应

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user_id": 123,
    "name": "testuser",
    "email": "test@example.com",
    "cert_status": "approved",
    "user_token": "eyJ1c2VyX2lkIjoxMjMsInVzZXJuYW1lIjoidGVzdCJ9.abc123xxx"
  },
  "timestamp": 1777710860
}

user_token：用户登录凭据，有效期 24 小时，由应用方自行保管。可用于后续业务上下文（如调用前端 API 时携带）。

错误响应

// 401 账号或密码错误（不区分用户是否存在，安全考虑统一文案）
{ "code": 401, "message": "账号或密码错误", "data": null, "timestamp": ... }

// 422 参数验证失败（邮箱格式错误、字段缺失）
{ "code": 422, "message": "The email must be a valid email address.", "data": null, "timestamp": ... }

4. 查询用户认证状态

请求头

请求参数（Query String）

请求示例：GET /api/users/cert-status?user_id=123

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "user_id": 123,
    "name": "testuser",
    "email": "test@example.com",
    "cert_status": "approved",
    "cert_status_desc": "已认证",
    "cert_time": "2026-05-03 15:00:00"
  },
  "timestamp": 1777710860
}

认证状态枚举：
uncertified 未认证
pending 审核中
approved 已认证（响应附 cert_time）
rejected 已拒绝

错误响应

// 422 用户ID不存在
{ "code": 422, "message": "The selected user id is invalid.", "data": null, "timestamp": ... }

5. 批量查询用户认证状态

请求头

请求参数

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 3,
    "users": [
      { "user_id": 123, "cert_status": "approved", "cert_status_desc": "已认证" },
      { "user_id": 124, "cert_status": "pending", "cert_status_desc": "审核中" },
      { "user_id": 125, "cert_status": "rejected", "cert_status_desc": "已拒绝" }
    ]
  },
  "timestamp": 1777710860
}

cert_status 枚举同「4. 查询用户认证状态」：uncertified / pending / approved / rejected。

错误响应

// 422 数组超限或不存在的ID
{ "code": 422, "message": "The user ids may not have more than 100 items.", "data": null, "timestamp": ... }