# 工作手机 SDK 公网 API 对接文档

> 更新：2026-07-14
> 生产地址：`https://wpsdk.quwanzhi.com`
> OpenAPI：`https://wpsdk.quwanzhi.com/openapi.json`
> Swagger：`https://wpsdk.quwanzhi.com/docs`

## 1. 对接条件

- 所有业务接口使用 HTTPS；手机主动连接使用 WSS。
- 外部应用从服务器安全环境读取 API Key，请勿写入前端源码、APK、日志或仓库。
- 请求头：`X-API-Key: <由运维安全提供>`；也兼容 `Authorization: Bearer <API_KEY>`。
- 当前生产真机 ID：`xgfe65eimrrofyws`；MD5：`ed25814d9c92b3430696dc96c2142b5f`。
- 健康探针 `/health`、`/ready` 无需 Key；控制接口无 Key或错误 Key均返回 401。

## 2. 最小调用样例

### curl

```bash
export WORKPHONE_URL='https://wpsdk.quwanzhi.com'
export WORKPHONE_API_KEY='<从服务器密钥管理获取>'

curl -fsS "$WORKPHONE_URL/api/v3/devices" \
  -H "X-API-Key: $WORKPHONE_API_KEY"

curl -fsS -X POST "$WORKPHONE_URL/api/v3/hook/execute" \
  -H "X-API-Key: $WORKPHONE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"device_id":"xgfe65eimrrofyws","platform":"wechat","action":"ping","params":{}}'
```

### JavaScript / Node.js

```js
const response = await fetch(`${process.env.WORKPHONE_URL}/api/v3/hook/execute`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.WORKPHONE_API_KEY,
  },
  body: JSON.stringify({
    device_id: 'xgfe65eimrrofyws',
    platform: 'wechat',
    action: 'get_profile',
    params: {},
  }),
});
if (!response.ok) throw new Error(`WorkPhone HTTP ${response.status}`);
const result = await response.json();
```

### Python

```python
import os
import requests

result = requests.post(
    f"{os.environ['WORKPHONE_URL']}/api/v3/hook/execute",
    headers={"X-API-Key": os.environ["WORKPHONE_API_KEY"]},
    json={
        "device_id": "xgfe65eimrrofyws",
        "platform": "wechat",
        "action": "get_contacts",
        "params": {"limit": 20},
    },
    timeout=35,
)
result.raise_for_status()
print(result.json())
```

## 3. 核心接口

| 用途 | 方法与路径 | 说明 |
|---|---|---|
| 健康 | `GET /health` | 服务状态与在线设备数，无需 Key |
| 就绪 | `GET /ready` | 数据库与服务启动门禁，无需 Key |
| 设备列表 | `GET /api/v3/devices` | WS/ADB 统一设备列表 |
| 设备详情 | `GET /api/v3/devices/{device_id}` | 项目、能力、连接信息 |
| 当前应用 | `GET /api/v3/adb/devices/{device_id}/app/current` | WS 设备也支持 |
| 启动应用 | `POST /api/v3/adb/devices/{device_id}/app/start` | Body：`{"package":"com.tencent.mm"}` |
| 真机截图 | `POST /api/v3/adb/devices/{device_id}/screenshot` | 返回 PNG Base64 |
| UI 树 | `GET /api/v3/adb/devices/{device_id}/ui-tree` | MIUI 状态变化时可能受系统限制 |
| 微信统一执行 | `POST /api/v3/hook/execute` | 推荐的单设备微信 RPC 入口 |
| 批量执行 | `POST /api/v3/fleet/execute` | 多设备、项目或全部在线设备 |
| 能力清单 | `GET /api/v3/wechat/actions` | 读取服务器当前动作清单 |

### 截图响应与解码

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "image_base64": "<PNG_BASE64>",
    "mime_type": "image/png",
    "size": 245296,
    "path": "<手机应用缓存路径>"
  },
  "channel_used": "websocket/agent"
}
```

```js
const png = Buffer.from(result.data.image_base64, 'base64');
```

## 4. 已验收的微信读类动作

以下动作于 2026-07-14 通过公网域名真实调用，通道均为 `server/frida`：

`ping`、`get_hook_status`、`get_wechat_version`、`get_process_info`、`get_profile`、`check_account_status`、`get_device_info`、`get_network_info`、`get_storage_info`、`get_contacts`、`get_groups`、`get_labels`、`get_recent_messages`、`get_safety_center`、`check_restrictions`。

调用格式统一：

```json
{
  "device_id": "xgfe65eimrrofyws",
  "platform": "wechat",
  "action": "get_wechat_version",
  "params": {}
}
```

## 5. 批量调用

```json
POST /api/v3/fleet/execute
{
  "device_ids": ["xgfe65eimrrofyws"],
  "platform": "wechat",
  "action": "get_profile",
  "params": {},
  "hook_only": true,
  "timeout": 60,
  "max_concurrency": 3
}
```

涉及发消息、发朋友圈、好友、群、支付、账号资料修改等写类操作时，调用方必须增加业务审批、目标白名单、幂等键、审计日志和人工确认，不允许仅凭 HTTP 200 判断业务成功。

## 6. 浏览器跨域

生产服务已放行标准 OPTIONS 预检；真实 GET/POST 仍要求 API Key。验证结果：

- `OPTIONS /api/v3/devices`：200；
- `Access-Control-Allow-Origin`：回显请求 Origin；
- `Access-Control-Allow-Headers`：包含 `X-API-Key`。

不建议把长期 API Key 放在浏览器；正式业务应由存客宝 BFF 代调。

## 7. 错误处理

| HTTP | 含义 | 调用方处理 |
|---:|---|---|
| 400/422 | 动作或参数错误 | 不重试，修正请求 |
| 401 | API Key 缺失或错误 | 停止调用并告警 |
| 404 | 设备或路径不存在 | 刷新设备列表 |
| 429 | 风控暂停或限流 | 按业务策略延迟 |
| 503 | 设备 WS、Frida 隧道或 Hook 不在线 | 指数退避，先查 `/health` 与设备状态 |
| 500 | 服务端或 RPC 执行异常 | 记录 request ID，有限重试 |

成功判定必须同时检查 HTTP 状态、`code`、`success`、`channel_used` 及动作业务字段；截图还要检查 `data.image_base64` 非空。

## 8. 安全与生产边界

- API Key 与手机 pairing token 必须分离，禁止相互替代。
- pairing token 只用于手机 WSS 绑定，不提供给业务调用方。
- 当前 Frida 经手机→443/WSS→宝塔反向隧道，公网不开放 Frida 端口。
- 微信 8.0.69、Android 13、Agent 5.0.1 已验收。
- 朋友圈图文发布在本轮两次返回“内容未发表”，不能标记成功；其他写类需要白名单逐项确认。
