VerifyGuard API 文档

v1.2.0

构建安全、可靠的企业微信二次验证系统

📖 概述

本系统提供了完整的 RESTful API 接口，支持企业微信用户管理、状态查询和系统监控功能。所有 API 接口都采用统一的 JSON 格式响应，并使用 HTTPS 协议进行加密传输，确保数据安全。

🔐 认证鉴权

为了保证接口安全，VerifyGuard API 支持两种认证方式：Session 认证（浏览器环境）和 Bearer Token 认证（API 调用）。

个人访问令牌 (PAT)

在进行 API 调用时，推荐使用个人访问令牌 (Personal Access Token) 进行身份验证。您可以在 个人中心 生成 PAT。

Authorization: Bearer <your_personal_access_token>

调用示例

curl -H "Authorization: Bearer 8f3...a1b" https://your-domain.com/api/index.php?path=user/info&userid=zhangsan

ℹ️ 基础信息

API 版本 v1.2.0
基础 URL https://your-domain.com/api.php
响应格式 JSON
字符编码 UTF-8

📝 更新日志

v1.2.0 (2025-12-02)

  • ✨ 新增系统更新日志管理功能，支持后台可视化增删改查
  • 📝 前端首页新增更新日志时间轴展示
  • 🎨 管理后台UI样式深度标准化，移除冗余内联样式
  • 📚 API文档同步更新，新增版本记录与更新日志章节
  • 🔧 优化系统配置文件结构

v1.1.0 (2025-11-30)

  • ✨ 新增全站水印功能，支持显示用户身份信息
  • 🔐 新增身份验证页面，增强登录安全性
  • 🎨 全新UI设计，统一移动端和PC端视觉风格
  • 📱 优化移动端登录申请流程
  • 🛠️ 修复审批状态同步问题

📄 响应格式

所有 API 接口都返回以下格式的 JSON 响应：

{ "success": true, "message": "操作成功", "timestamp": 1640995200, "data": { // 具体的响应数据 } }

字段说明

字段 类型 说明
success Boolean 表示操作是否成功
message String 响应消息，用于提示用户
timestamp Integer 服务器响应时间戳
data Object/Array 具体的业务数据

🔍 系统状态查询

GET /api.php?path=status

获取系统运行状态、配置信息和 API 状态。

响应示例

{ "success": true, "message": "系统状态获取成功", "timestamp": 1640995200, "data": { "system": { "name": "VerifyGuard", "version": "1.2.0", "php_version": "8.0.0", "server_time": "2024-01-01 12:00:00" }, "api": { "access_token_valid": true, "last_error": null } } }

👤 用户信息查询

GET /api.php?path=user/info

根据用户 ID 获取详细信息。

请求参数

参数名 类型 必填 说明
userid String 必填 企业微信用户 ID

响应示例

{ "success": true, "message": "用户信息获取成功", "data": { "userid": "zhangsan", "name": "张三", "mobile": "13800138000", "department": [1, 2], "position": "产品经理", "email": "zhangsan@company.com", "avatar": "http://wx.qlogo.cn/..." } }

➕ 创建用户

POST /api.php?path=user/create

在企业微信中创建新用户。

请求参数

参数名 类型 必填 说明
userid String 必填 用户 ID，唯一标识
name String 必填 用户姓名
mobile String 必填 手机号码
department Array 必填 部门 ID 列表

✏️ 更新用户

PUT POST /api.php?path=user/update

更新企业微信用户的信息。

请求参数

请求体应为 JSON 格式。

参数名 类型 必填 说明
userid String 必填 用户 ID
name String 可选 新姓名
mobile String 可选 新手机号
department Array 可选 新部门 ID 列表

🗑️ 删除用户

DELETE POST /api.php?path=user/delete

删除企业微信用户。

请求参数

参数名 类型 必填 说明
userid String 必填 要删除的用户 ID

🏢 部门列表查询

GET /api.php?path=department/list

获取企业微信部门列表。

请求参数

参数名 类型 必填 说明
department_id Integer 可选 部门 ID。如果不填，默认获取全量组织架构

🔐 认证状态查询

GET /api.php?path=auth/status

查询用户的认证状态及基本信息。

请求参数

参数名 类型 必填 说明
userid String 必填 用户 ID

响应示例

{ "success": true, "message": "认证状态查询成功", "data": { "userid": "zhangsan", "exists": true, "status": "active", "check_time": "2024-01-01 12:00:00", "user_info": { "userid": "zhangsan", "name": "张三", "enable": 1 } } }

📊 系统日志查询

GET /api.php?path=logs

查询系统的运行日志。

请求参数

参数名 类型 必填 说明
limit Integer 可选 返回日志条数，默认 50，最大 100
level String 可选 日志级别过滤 (all, INFO, ERROR, WARNING)

⚠️ 错误处理

当 API 请求失败时，success 字段将为 false，并且 message 字段会包含错误描述。HTTP 状态码通常也会指示错误类型。

HTTP 状态码 说明
200 请求成功
400 请求参数错误或无效请求
401 未授权（如 Access Token 无效）
403 禁止访问
404 资源未找到
405 请求方法不允许
500 服务器内部错误

🛡️ 安全注意事项

  • 请确保 API 接口仅通过 HTTPS 协议访问。
  • 建议对 API 访问进行 IP 白名单限制。
  • 敏感操作（如用户创建、删除）应严格控制权限。
  • 定期轮换 API 密钥和 Access Token。

💡 使用示例

以下是使用 PHP cURL 调用 API 的示例：

$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://your-domain.com/api.php?path=user/info&userid=zhangsan"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $output = curl_exec($ch); curl_close($ch); $result = json_decode($output, true); if ($result['success']) { print_r($result['data']); } else { echo "Error: " . $result['message']; }