自动化 API

美客浏览器自动化 API 用于管理店铺、网络节点、团队成员和已保存凭据，并启动店铺浏览器。

网页读取、点击、输入、截图等操作不属于这些 HTTP 接口，需要在启动浏览器后通过 CDP 或支持 CDP 的自动化工具完成。

1. 接入准备

1. 启动美客浏览器桌面客户端并登录账号。
2. 确认账号拥有付费套餐。
3. 在客户端设置中启用自动化 API，复制 API Key，确认监听端口。
4. 启动店铺前，确保浏览器内核已就绪，店铺已绑定可用节点。
5. 使用期间保持美客浏览器桌面客户端运行，并保持网络可用。接口复用客户端的登录状态，不提供独立的登录接口。

默认连接信息：

远程访问时，将 127.0.0.1 替换为运行美客浏览器的电脑地址。浏览器进程、调试端口及接口返回的本地文件路径始终属于运行美客浏览器的电脑，而不是调用方电脑。

2. 通用约定

2.1 鉴权

除 GET /health 外，所有 API 请求均需携带：

Authorization: Bearer <API_KEY>

有请求体的 HTTP 请求使用：

Content-Type: application/json

API Key 用于访问本地自动化服务，不会替代美客浏览器账号登录或提升账号权限。

2.2 请求和响应

• 请求体为 JSON 对象，不能使用数组、字符串或 null 作为顶层值。
• 请求体上限为 256 KiB；超限时连接可能直接关闭。
• 本文接口成功时均返回 200，包括创建和删除操作。
• 响应为 JSON，并带有 Cache-Control: no-store。
• 店铺、节点、成员及凭据的路径 ID 为 UUID。格式不合法的路径 ID 返回 404。
• 本文路径中的 :id、:passwordId、:otpId、:passkeyId 均需替换为真实值。
• 列表接口未提供通用分页参数；活动列表最多返回最近 200 条。
• 店铺、节点和成员的 PATCH 保留未传字段；具体清空规则见各章节。不要使用 null 代替省略字段。

错误响应：

{
  "error": "错误说明",
  "code": "not_found"
}

程序应根据 HTTP 状态码及 code 处理错误，不依赖 error 文案或语言。

2.3 权限

• 创建或删除店铺、访问节点接口以及团队管理均需要所有者或管理员 admin 权限；普通成员 member 需要店铺授权。
• 店铺 read 权限允许启动店铺及读取已保存凭据。
• 店铺 full 权限还允许修改店铺及已保存凭据，但不授予团队管理权限。
• 创建普通成员不会自动授予店铺访问权限，应另外设置店铺成员授权。

3. 快速开始

以下命令使用 Bash/zsh 语法。将 API Key 和店铺 ID 替换为实际值。

export MERCA_API_BASE='http://127.0.0.1:43210'
export MERCA_API_KEY='替换为客户端中的 API Key'

curl -sS "$MERCA_API_BASE/health"

curl -sS "$MERCA_API_BASE/v1/engine" \
  -H "Authorization: Bearer $MERCA_API_KEY"

curl -sS "$MERCA_API_BASE/v1/stores" \
  -H "Authorization: Bearer $MERCA_API_KEY"

export STORE_ID='替换为店铺 UUID'

curl -sS -X POST "$MERCA_API_BASE/v1/stores/$STORE_ID/launch" \
  -H "Authorization: Bearer $MERCA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"startupUrl":"https://example.com","extraArgs":["--remote-debugging-port=9222"]}'

启动成功返回：

{"ok": true}

此时只表示浏览器进程启动成功，不表示网页、登录或 CDP 已就绪。等待调试端口可用后，可查询：

curl -sS http://127.0.0.1:9222/json/version

使用返回的 webSocketDebuggerUrl，或使用自动化工具支持的 CDP HTTP 地址，连接该浏览器进行页面操作。43210 是美客浏览器 API 端口，9222 是示例浏览器调试端口，两者不可混用。并行运行多个店铺时，应为每个浏览器分配不同的调试端口。

使用成员账号进行 CDP 页面自动化前，请关闭该成员的「禁用开发者工具」选项，并重新启动店铺。

关闭本次由 API 启动的店铺：

curl -sS -X POST "$MERCA_API_BASE/v1/stores/$STORE_ID/close" \
  -H "Authorization: Bearer $MERCA_API_KEY"

4. 服务、账号与平台

4.1 内核与会话状态

GET /v1/engine 的 version 是浏览器内核版本，不是美客浏览器客户端版本；无法取得版本时为空字符串。ready 不代表任何店铺已经启动，也不代表调试端口可用。

GET /v1/session 的 session 可为：

/health 返回正常不代表账号已登录、拥有权限或内核已就绪。

4.2 账号权益

entitlements 包含：

4.3 平台目录

可通过 platformId 查询参数筛选单个平台：

GET /v1/platforms?platformId=<PLATFORM_ID>

响应结构：

{
  "platforms": [
    {
      "id": "平台 ID",
      "name": "平台名称",
      "sites": [
        {"id": "站点 ID", "name": "站点名称"}
      ]
    }
  ]
}

名称跟随客户端当前语言。创建店铺时使用返回的 id，不要使用显示名称。筛选不存在的平台返回 404。

4.4 活动记录

GET /v1/activity 和 GET /v1/members/:id/activity 返回相同结构，按时间倒序，最多 200 条：

{
  "entries": [
    {
      "id": "活动 UUID",
      "action": "活动类型",
      "details": {},
      "createdAt": "2026-09-17T08:00:00.000Z"
    }
  ]
}

details 为活动相关字段，值为字符串或布尔值；具体字段依活动类型而定。

5. 店铺管理

5.1 创建与更新字段

可以先创建未绑定节点的店铺，但启动和生成启动命令前必须绑定节点。

fingerprint 字段：

每次创建都会随机选择 CPU 线程数 8/12/16/20/24/32 和内存 16/32 GB；随机组合中，8 线程的性能档位为 3，其余为 4。显式字段覆盖对应预设，更新时省略则保留原值，启动时不会重新随机。

cpuPerformance 档位：0 = Unknown、1 = Low、2 = Mid、3 = High、4 = Ultra。

webrtcIpPolicy 支持：

• disable_non_proxied_udp
• default_public_interface_only
• default_public_and_private_interfaces
• default

允许 UDP 的模式可能暴露直连 IP，而非节点 IP。修改后需关闭并重新启动浏览器。

创建店铺时，未提供的指纹字段使用上述默认值。更新 fingerprint 时，只覆盖传入的子字段。

创建请求示例，平台、站点和节点 ID 请替换为接口查询到的实际值：

{
  "name": "运营店铺 A",
  "platformId": "<PLATFORM_ID>",
  "siteIds": ["<SITE_ID>"],
  "username": "seller@example.com",
  "password": "<STORE_PASSWORD>",
  "nodeId": "<NODE_UUID>",
  "fingerprint": {
    "hardwareConcurrency": 8,
    "deviceMemory": 8,
    "webrtcIpPolicy": "disable_non_proxied_udp"
  }
}

局部更新示例：

PATCH /v1/stores/:id

{
  "name": "运营店铺 B",
  "fingerprint": {"hardwareConcurrency": 4}
}

5.2 店铺响应对象

店铺列表中的每项包含：

• id、name、platformId、siteIds、username
• nodeId、nodeBound
• fingerprint
• appearanceLabel、appearanceBackgroundColor、appearanceForegroundColor
• createdAt、updatedAt、可选的 lastLaunchedAt

nodeBound 表示是否已设置 nodeId，不代表节点在线或浏览器正在运行。

店铺详情、创建和更新响应在上述字段基础上增加：

node 摘要包含 name、ip、country、timezone、acceptLanguages，不包含代理密码。代理连接详情通过节点接口获取。

店铺登录字段与第 9 节的已保存网站密码集合是不同数据。

6. 浏览器启动与关闭

6.1 启动参数

launch 和 command 接受相同请求体；不需要自定义参数时发送 {}：

{
  "startupUrl": "https://example.com",
  "extraArgs": ["--remote-debugging-port=9222"]
}

启动会继承客户端全局启动参数，再追加本次 extraArgs；传入空数组不会清除全局参数。extraArgs 不能覆盖美客浏览器管理的店铺数据目录和浏览器生命周期参数。

launch 和 command 均受登录保护限制。店铺登录账号与节点账号记录冲突时，返回 400 node_account_conflict，请先在客户端查看和处理账号记录。

launch 成功仅代表浏览器已启动。重复调用可能关闭并重新启动该店铺，请勿用它轮询运行状态。

6.2 获取启动命令

POST /v1/stores/:id/command

响应字段：

请将 executable 和 args 原样交给进程启动 API，不要拼接成 shell 命令，也不要自行覆盖店铺数据目录。

command 不会启动浏览器，但会更新店铺的最后启动时间和活动记录。店铺登录账号非空时，还可能新增节点账号记录，影响其他账号能否在该 IP 上使用同一平台；即使不执行返回的命令，也会产生这些影响。

如使用 --remote-debugging-pipe，应选择 command，由调用方创建进程并正确连接调试管道；launch 不会把管道返回给调用方。

6.3 生命周期

• 使用浏览器期间，请保持美客浏览器桌面客户端运行。
• close 仅管理通过 launch 启动的浏览器，不管理客户端界面或调用方依据 command 自行启动的进程。
• 没有可关闭的 API 启动记录时，close 返回 404，错误码为 not_running。浏览器已自行退出时，首次 close 仍可能成功，因此不能用此接口判断运行状态。
• close 成功表示已发出关闭请求，不保证浏览器进程已退出。
• 店铺使用独立本地数据目录。不要对同一店铺并发启动多个实例。

7. 网络节点管理

删除节点前，必须先解除所有店铺与该节点的绑定，否则返回 400 node_in_use。

7.1 创建与更新字段

{
  "name": "美国节点 A",
  "protocol": "socks5",
  "host": "proxy.example.com",
  "port": 1080,
  "username": "<PROXY_USERNAME>",
  "password": "<PROXY_PASSWORD>",
  "acceptProxyChain": true
}

使用限制：

• 同一出口 IP 不能重复添加，即使使用不同账号添加也会返回 node_already_added。
• ip 和 country 必须同时提供或同时省略；仅提供其中一个会返回 node_probe_required。
• 手动提供时区等附加地理字段时，必须同时提供 ip 和 country，无需修改连接信息。非空时区必须是有效的 IANA 时区；留空时跟随当前电脑。
• 更新连接信息或检测结果时，出口 IP 必须与原节点保持一致，否则返回 node_ip_changed。需要更换出口 IP 时应创建新节点。

7.2 节点响应

节点详情包含：

id、name、protocol、host、port、username、password、acceptProxyChain、ip、country、timezone、acceptLanguages。

列表省略 password；创建、更新和详情响应包含该字段。请求支持的附加地理字段不代表响应也返回这些字段。

8. 团队成员与店铺授权

8.1 成员接口

成员接口不包含团队所有者。成员路径参数使用成员对象的 id，不是 userId。

创建和更新字段：

{
  "nickname": "运营一组",
  "username": "operator_01",
  "password": "<MEMBER_PASSWORD>",
  "role": "member",
  "disableDevtools": true,
  "passwordRevealBlock": true
}

成员对象包含 id、userId、username、nickname、role、disableDevtools、passwordRevealBlock、disabled、createdAt，不返回登录密码。

禁用成员的请求体：

{"disabled": true}

恢复时传 false。禁用成员会使其已有登录会话失效。不能修改自己的角色、删除自己，或对自己调用禁用状态接口。

8.2 店铺成员授权

需要所有者或管理员权限及付费套餐。列表只包含可授权的 member 账号；所有者及管理员已有管理权限，不在此列表中。

响应中的每项包含 userId、username、nickname、access。access 可为 read、full 或表示未授权的 null。

替换请求：

{
  "grants": [
    {"userId": "<MEMBER_USER_UUID>", "access": "read"},
    {"userId": "<ANOTHER_MEMBER_USER_UUID>", "access": "full"}
  ]
}

这里使用 userId，不是成员接口路径使用的 id。同一个 userId 不可重复，且必须来自可授权成员列表。

这是整体替换，不是追加：未包含的原有成员授权将被移除。传入 { "grants": [] } 清空普通成员的店铺授权。

9. 已保存的网站凭据

本节读取操作需要店铺 read 权限，写入和删除需要 full 权限。

9.1 网站密码

保存请求：

{
  "origin": "https://example.com",
  "username": "seller@example.com",
  "password": "<WEBSITE_PASSWORD>"
}

PATCH 只接受上述三个字段中的一个或多个，至少提供一个；不允许空字符串。signon_realm 自动生成，不接受作为请求字段。

密码摘要字段：id、origin、signon_realm、username、locked。单条详情另含 password。

同一网站登录域与用户名的未锁定条目会在保存时更新，锁定条目拒绝覆盖。保存接口不返回条目 ID，需要再次查询列表。

锁定请求：

{"locked": true}

传 false 解锁。锁定阻止修改、删除及浏览器同步覆盖，不阻止读取或使用密码。

修改会在后续启动时提供给浏览器；删除不会修改网站账号，也不会移除运行中浏览器已加载的凭据。后续浏览器同步可能覆盖未锁定条目或重新创建已删除条目。

9.2 TOTP 动态验证码

保存请求字段：

列表和保存响应中的元数据包含 id、label、issuer、accountName、algorithm、digits、period，不返回密钥。

同一店铺下相同的标准化密钥会更新或恢复已有条目；不同密钥创建新条目。再次保存时，省略的元数据与设置采用默认值，不保留旧值。

验证码响应示例：

{
  "id": "<OTP_UUID>",
  "code": "012345",
  "expiresAt": "2026-09-17T08:00:30.000Z"
}

code 为字符串，应保留前导零。验证码按运行美客浏览器的电脑时钟生成；expiresAt 为 UTC ISO 时间。此接口不会自动提交验证码。保存或删除条目不会开启或关闭网站上的两步验证。

9.3 Passkey

每项包含 id、rpId、userName、userDisplayName，不返回私钥。

自动化 API 不提供创建或导入 Passkey 的端点。删除只影响美客浏览器中保存的条目及后续启动，不会在网站注销凭据，也不会移除运行中浏览器已加载的副本。

10. 常见错误

相关文档

• 添加网络节点
• 如何绑定店铺
• 如何添加成员
• 店铺指纹如何工作