erpnew/docs/api_v2_wecom_binduser.md

企业微信用户绑定 API

接口说明

供企业微信服务端程序调用，将企业微信 OAuth2 获取的 user_id 与本系统的员工（Employee）绑定。调用方需提供本系统的用户名和密码进行身份验证，验证通过后完成绑定。

接口信息

• URL: /api/v2/wecom/binduser/
• 方法: POST
• Content-Type: application/json
• 认证方式: 固定密钥，通过 Authorization 请求头传入（不使用 Bearer 前缀）

认证

请求必须在 Authorization 头中携带预分配的访问密钥（由系统管理员提供）。

Authorization: your-access-key

请求参数

参数名	类型	必填	说明
wecom_user_id	string	是	企业微信 OAuth2 返回的 user_id，最长 128 字符
username	string	是	本系统用户名
password	string	是	本系统用户密码
force_update	boolean	否	如果该员工已绑定其他企业微信用户，是否强制覆盖。默认 false

请求示例

curl -X POST "https://your-domain/api/v2/wecom/binduser/" \
  -H "Authorization: your-access-key" \
  -H "Content-Type: application/json" \
  -d '{
    "wecom_user_id": "zhangsan",
    "username": "zhangsan",
    "password": "mypassword123"
  }'

响应说明

绑定成功（200 OK）

{
  "message": "绑定成功",
  "employee_id": 42,
  "employee_name": "张三",
  "wecom_user_id": "zhangsan"
}

用户名或密码错误（401 Unauthorized）

{
  "error": "用户名或密码错误"
}

用户已被禁用（403 Forbidden）

{
  "error": "该用户已被禁用"
}

用户未关联员工（404 Not Found）

{
  "error": "该用户未关联任何员工记录"
}

企业微信用户已绑定到其他员工（409 Conflict）

{
  "error": "该企业微信用户已绑定到其他员工: 李四 (ID: 15)"
}

员工已绑定其他企业微信用户（409 Conflict）

当该员工已有不同的 wecom_user_id 且未传 force_update=true 时：

{
  "error": "该员工已绑定其他企业微信用户",
  "current_wecom_user_id": "old_wecom_id",
  "hint": "如需覆盖，请传入 force_update=true"
}

认证失败（401 Unauthorized）

Authorization 头缺失或密钥错误：

{
  "detail": "AGENT_ACCESS_KEY 无效"
}

参数验证失败（400 Bad Request）

{
  "wecom_user_id": ["该字段是必填项。"],
  "username": ["该字段是必填项。"],
  "password": ["该字段是必填项。"]
}

业务规则

1. 一对一约束：一个企业微信 user_id 只能绑定一个员工，一个员工只能绑定一个企业微信 user_id。
2. 幂等性：重复绑定相同的 wecom_user_id 到同一个员工不会报错，返回 200。
3. 冲突处理：
   • 如果 wecom_user_id 已被其他员工绑定 → 拒绝（409）
   • 如果该员工已绑定不同的 wecom_user_id 且 force_update=false → 拒绝（409）
   • 如果该员工已绑定不同的 wecom_user_id 且 force_update=true → 覆盖绑定
4. 身份验证：通过 Django 内置认证机制验证用户名和密码，验证通过后通过 User → Employee 关系找到对应员工。

接入流程

企业微信用户 → OAuth2 授权 → 获取 wecom user_id
                                    ↓
                        调用本接口（传入 wecom_user_id + 本系统 username/password）
                                    ↓
                              验证凭据 → 查找 Employee → 写入 wecom_user_id
                                    ↓
                              绑定完成，后续可通过 wecom_user_id 识别用户身份

注意事项

1. 密码通过 HTTPS 传输，请确保生产环境使用 TLS。
2. 该接口不限制调用频率，但建议调用方做适当限流。
3. 绑定成功后，后续业务可通过 Employee.wecom_user_id 字段查找对应员工。

---

企业微信快捷登录 API

接口说明

供企业微信服务端程序调用，通过已绑定的 wecom_user_id 快捷获取本系统的 JWT token，无需再次输入用户名密码。

前提条件：该 wecom_user_id 必须已通过绑定接口（/api/v2/wecom/binduser/）完成绑定。

接口信息

• URL: /api/v2/wecom/login/
• 方法: POST
• Content-Type: application/json
• 认证方式: 固定密钥，通过 Authorization 请求头传入（与绑定接口相同）

认证

Authorization: your-access-key

请求参数

参数名	类型	必填	说明
wecom_user_id	string	是	企业微信 OAuth2 返回的 user_id

请求示例

curl -X POST "https://your-domain/api/v2/wecom/login/" \
  -H "Authorization: your-access-key" \
  -H "Content-Type: application/json" \
  -d '{
    "wecom_user_id": "zhangsan"
  }'

响应说明

登录成功（200 OK）

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "employee_id": 42,
  "employee_name": "张三",
  "username": "zhangsan"
}

返回的 access token 可直接用于后续业务 API 的 Authorization: Bearer <token> 认证。

企业微信用户未绑定（404 Not Found）

{
  "error": "该企业微信用户未绑定本系统员工"
}

员工未关联系统用户（404 Not Found）

{
  "error": "该员工未关联系统用户"
}

用户已被禁用（403 Forbidden）

{
  "error": "该用户已被禁用"
}

认证失败（401 Unauthorized）

Authorization 头缺失或密钥错误：

{
  "detail": "AGENT_ACCESS_KEY 无效"
}

参数验证失败（400 Bad Request）

{
  "wecom_user_id": ["该字段是必填项。"]
}

业务规则

1. 该接口仅对已完成绑定的 wecom_user_id 有效。
2. 每次调用都会生成新的 JWT token 对（access + refresh）。
3. access token 有效期为 7 天（与系统 JWT 配置一致）。
4. 安全边界依赖 AGENT_ACCESS_KEY，请妥善保管该密钥。

典型使用流程

用户首次使用：
  企业微信 OAuth2 → 获取 wecom_user_id
  → 调用 /api/v2/wecom/binduser/（传 wecom_user_id + username + password）
  → 绑定完成

用户后续登录：
  企业微信 OAuth2 → 获取 wecom_user_id
  → 调用 /api/v2/wecom/login/（仅传 wecom_user_id）
  → 获取 JWT token
  → 使用 token 访问业务 API