API 请求参数示例

本文档提供客户端联调时常用的请求示例。

1. 登录获取 auth

POST /api/member/login
Content-Type: application/json

{
  "account": "user@example.com",
  "password": "password"
}

成功后从返回 data.auth 中取登录态。

后续请求推荐统一带：

Authorization: Bearer {auth}
Content-Type: application/json

2. 查询当前账号权限

POST /api/sysUsers/permissions
Authorization: Bearer {auth}
Content-Type: application/json

{}

返回中重点看：

{
  "data": {
    "isMainAccount": false,
    "permissionCodes": [
      "browser:list",
      "browser:create:single",
      "browser:update:single",
      "browser:update:batch",
      "group:list",
      "group:add"
    ]
  },
  "code": 0,
  "msg": "success"
}

3. 创建分组

POST /group/add
Authorization: Bearer {auth}
Content-Type: application/json

{
  "groupName": "Amazon 店铺",
  "sortNum": 0
}

4. 查询分组列表

POST /group/list
Authorization: Bearer {auth}
Content-Type: application/json

{
  "page": 0,
  "pageSize": 100
}

5. 创建标签

POST /browserTag/create
Authorization: Bearer {auth}
Content-Type: application/json

{
  "tagName": "重点账号",
  "tagColor": "#ECC2F3"
}

6. 查询标签列表

POST /browserTag/list
Authorization: Bearer {auth}
Content-Type: application/json

{
  "keyword": ""
}

7. 创建浏览器窗口

POST /browser/update
Authorization: Bearer {auth}
Content-Type: application/json

{
  "name": "Amazon-001",
  "groupId": 12,
  "tagIds": [3, 5],
  "remark": "客户端创建",
  "browserFingerPrint": {
    "coreVersion": "118",
    "ostype": "PC",
    "os": "Win32"
  },
  "proxyMethod": 2,
  "proxyType": "direct"
}

说明：上方为云端接口简化创建示例。通过 Local API 转发 /browser/update 创建窗口时，实测需要传完整的非空 config 对象。

8. 创建带 HTTP 代理的窗口

POST /browser/update
Authorization: Bearer {auth}
Content-Type: application/json

{
  "name": "HTTP代理窗口",
  "groupId": 12,
  "proxyMethod": 2,
  "proxyType": "http",
  "host": "127.0.0.1",
  "port": 7890,
  "proxyUserName": "",
  "proxyPassword": "",
  "browserFingerPrint": {}
}

9. 查询窗口列表

POST /browser/list
Authorization: Bearer {auth}
Content-Type: application/json

{
  "page": 0,
  "pageSize": 20,
  "groupId": 12
}

10. 查询窗口详情

POST /browser/detail
Authorization: Bearer {auth}
Content-Type: application/json

{
  "id": 101
}

也可以传：

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

说明：通过 Local API 查询窗口详情时，推荐传 uuid；使用数字 id 可能返回 UUID 无效。

11. 批量修改窗口名称、分组、备注、标签

POST /browser/update/partial
Authorization: Bearer {auth}
Content-Type: application/json

{
  "ids": [101, 102],
  "name": "批量修改名称",
  "groupId": 15,
  "remark": "新的备注",
  "tagIds": [3, 8]
}

12. 批量修改窗口分组

POST /browser/group/update
Authorization: Bearer {auth}
Content-Type: application/json

{
  "ids": [101, 102],
  "groupId": 15
}

13. 批量修改窗口备注

POST /browser/remark/update
Authorization: Bearer {auth}
Content-Type: application/json

{
  "ids": [101, 102],
  "remark": "这是一段新备注"
}

14. 批量修改窗口代理

POST /browser/proxy/update
Authorization: Bearer {auth}
Content-Type: application/json

{
  "ids": [101, 102],
  "ipCheckService": "ip-api",
  "proxyMethod": 2,
  "proxyType": "socks5",
  "host": "127.0.0.1",
  "port": 1080,
  "proxyUserName": "user",
  "proxyPassword": "pass",
  "refreshProxyUrl": ""
}

15. 给窗口添加或移除标签

POST /browserTag/updateRelation
Authorization: Bearer {auth}
Content-Type: application/json

{
  "browserId": 101,
  "addTagIds": [3],
  "removeTagIds": [5]
}

Local API 推荐传 uuid：

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "addTagIds": [3],
  "removeTagIds": [5]
}

说明：通过 Local API 更新标签绑定关系时，推荐传 uuid；使用数字 browserId 可能返回 UUID 无效。

16. 删除窗口

POST /browser/delete
Authorization: Bearer {auth}
Content-Type: application/json

{
  "id": 101
}

批量删除：

POST /browser/delete/ids
Authorization: Bearer {auth}
Content-Type: application/json

{
  "ids": [101, 102]
}

说明：第一阶段删除默认移入回收站。

17. 打开和关闭窗口（Local API）

POST http://127.0.0.1:54345/browser/open
X-Cos-Local-Token: <本机访问令牌>
Content-Type: application/json

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

POST http://127.0.0.1:54345/browser/close
X-Cos-Local-Token: <本机访问令牌>
Content-Type: application/json

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

说明：Local API 只监听 127.0.0.1，实际端口和访问令牌以客户端「系统设置 / Local API」页面展示为准。

18. 常见失败返回

未登录：

{
  "code": 401,
  "msg": "auth required",
  "data": {}
}

登录过期：

{
  "code": 401,
  "msg": "auth expired",
  "data": {}
}

无权限：

{
  "code": 403,
  "msg": "permission denied",
  "data": {}
}

参数错误：

{
  "code": 211,
  "msg": "browser id required",
  "data": {}
}