Customer Open API · v2.1

一套 Session，安全配对本地 Runner

账号密码和 Customer API Key 都先换取短期 Open Session；账户资源和 Runner 管理使用同一权限模型，本地动作只有在 Runner v14 签名确认后才成为成功状态。

创建 API Key 查看 OpenAPI v2 JSON 下载 v2.1 接入指南兼容期 v1 文档

快速开始

Base URL

https://shop.robocloud.store/api/open/v2

先用账号密码或具名 API Key 换取 8 小时 Open Session。Session、新 API Key、配对秘密和 Runner Token 的完整值都只显示一次，请保存在操作系统凭据存储中。

curl -X POST https://shop.robocloud.store/api/open/v2/auth/sessions \
  -H 'Authorization: Bearer rbl_live_example_xxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"auth_method":"api_key","device_summary":"home-computer","required_scopes":["runner.read","runner.pair","runner.control"]}'

后续业务请求只接受返回的 rbl_sess_…。浏览器 Cookie 和原始 Customer API Key 不能直接调用 v2 业务接口。

权限

account.read / wallet.read: 读取统一账户身份与整数最小货币单位余额。
plans.read / services.read: 读取套餐目录、服务列表与异步操作。
connection.read: 读取脱敏连接状态，不包含配置秘密。
configuration.read / nodes.read: 读取经过认证的配置 payload 与脱敏节点元数据。新 Key 必须显式拥有 configuration.read。
usage.read: 读取流量、计费和钱包快照。
active_dynamic.read: 读取主动动态线路、地区与轮转任务。
active_dynamic.control: 切换出口地区、设置轮转策略和执行手动轮转。
payg.open: 独立开通按量服务；与新增付费线路一起使用时仍要求幂等键和报价快照。
runner.read: 读取账户所属 Runner、真实 operation 状态和已确认的本地出口。
runner.pair: 创建一次性配对、查询配对和解绑 Runner。
runner.control: 向同账户、在线且版本受支持的 Runner 提交固定类型命令。

完整控制模板会显式保存全部 14 项权限。受限自定义模板只提交明确勾选项。旧 client:read / payg:open Key 会如实显示 integrationStatus=limited 和 missingRequiredScopes；迁移期仅保留原有连接/配置读取兼容，不会获得新增的显式 configuration.read、主动动态控制或 Runner 权限。

升级时先创建并验证新 Key，在 Session 请求中声明 required_scopes，确认 requestedScopesSatisfied=true 后切换消费端，最后撤销旧 Key。

接口

POST /auth/sessions统一登录

账号密码或 API Key 换取同一种短期 Session。登录不接受 Idempotency-Key，只读 Key 会返回 integrationStatus=limited 和缺失权限。

GET /me · GET /wallet账户与余额

两种认证来源在同一账户下返回完全相同的数据；金额始终使用整数分。

GET /plans套餐目录与节点

展示全部有效套餐。套餐节点是该 SKU 当前可提供的公开节点，包含地区、协议、公开倍率和可用状态；只有开放的按量套餐会返回 apiPurchasable=true。

GET /services已有服务

支持游标分页。不同套餐及同一套餐的多个服务彼此独立。

GET /services/{id}/connection安全连接状态

只返回 revision、ready、stale 和节点数量，不返回稳定订阅 URL 或节点凭据。

GET /services/{id}/configuration认证配置 payload

在 Session 和服务归属检查后返回 Clash 配置本体，响应禁止缓存。

GET /services/{id}/nodes脱敏节点元数据

返回名称、地区、协议、倍率和可用性，不返回代理认证字段。

GET /services/{id}/usage流量与扣费

返回原始流量、倍率计费流量、累计扣费金额和当前钱包余额。

POST /payg/services开通按量服务

需要 payg.open、完整费率快照、自动扣费确认和唯一的 Idempotency-Key。

GET /operations/{id}任务进度

开通异步执行。响应保留首次提交的 requestId，终态失败提供脱敏 lastErrorCode / lastError；幂等重放不覆盖关联 ID。建议从 2 秒开始退避轮询，最大间隔 15 秒。

/services/{id}/active-dynamic/*云端主动动态控制

地区切换、轮转策略、手动轮转和线路调整复用现有异步任务与账户级幂等约束；任务查询同样返回首次 requestId 与脱敏终态错误。

POST /runner-pairings · POST /runners/pair一次性设备配对

Open Session 创建五分钟有效的一次性秘密；Runner 用 Ed25519 私钥持有证明消费它。最低版本为 v14.0.0，v13.2.0 返回 runner_pairing_unsupported。

GET /runners · GET/DELETE /runners/{id}Runner 管理

读取和解绑严格限定当前账户。Runner Token 是设备凭据，不能充当 Open Session。

/runners/{id}/*固定 Runner 命令

选择服务、测速、启动、停止和刷新均要求 Idempotency-Key，返回真实异步 operation；Runner 确认前不显示成功。

GET /runners/{id}/exports已确认本地出口

只返回 networkScope=runner_local 的回环地址；该地址只能由 Runner 所在设备使用，并非云端可访问代理。

Runner v14 协议

Runner 使用立即返回的短请求，不使用阻塞长轮询：POST /runner/heartbeat、POST /runner/commands/claim、POST /runner/operations/{operation_id}/results。

每次请求同时携带 Authorization: Runner rbl_run_…、X-RoboCloud-Runner-Timestamp、唯一 X-RoboCloud-Runner-Nonce 和 X-RoboCloud-Runner-Signature。Ed25519 签名 canonical 文本如下：

METHOD
/api/open/v2/NORMALIZED_ABSOLUTE_PATH
X-ROBOCLOUD-RUNNER-TIMESTAMP
X-ROBOCLOUD-RUNNER-NONCE
SHA256_HEX_OF_EXACT_BODY_BYTES

仅允许 service.select、service.status、nodes.read、nodes.test、node.start、node.stop、exports.read、runner.refresh；没有 shell、脚本、自由 URL 或任意命令。

claim 返回有限租约、deadline、服务与 Runner revision。heartbeat 固定上报稳定 deviceId、配对 accountId，服务端与 Runner Token 的权威绑定做恒等校验；选择服务后还必须上报本机实际应用的 selectedServiceRevision，云端不能拿最新 revision 冒充。过期命令不得在重连后执行；同一 operation 重领时复用本地保存结果，不能重复副作用。敏感配置只在 claim 时即时生成，经签名 HTTPS 通道交付，不写入普通命令记录或日志。

按量开通

curl -X POST https://shop.robocloud.store/api/open/v2/payg/services \
  -H 'Authorization: Bearer rbl_sess_example_xxxxxxxxxxxx' \
  -H 'Idempotency-Key: 018f-example-unique-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "sku": "home-payg",
    "expectedPlanVersion": 7,
    "expectedBasePriceMinorPerGb": 200,
    "expectedCurrency": "CNY",
    "confirmAutomaticDebit": true
  }'

余额达到套餐返回的最低开通要求即可创建，开通时不预扣套餐费。
每个新幂等键创建一个独立服务；重复同一个幂等键不会重复创建。
多个服务共享账户余额并分别记账；余额耗尽时停止，充值后自动恢复。

数据约定

金额: 整数分为权威值，例如 200 表示 ¥2.00。
流量: 1 GB = 1,000,000,000 bytes，上传和下载均计入。
倍率: 千分制整数：800=0.8x、1000=1x。
时间: UTC ISO 8601，例如 2026-08-21T08:30:00Z。

Open Session、API Key、Runner Token、pairing secret、密码、配置 payload、订阅 URL 和节点凭据都属于敏感值，不得写入 URL 查询参数、普通日志、截图、遥测或错误报告。

本地出口 host 只允许 127.0.0.1 或 ::1，并始终带 networkScope=runner_local。云端调用者不得直接连接该回环地址，也不得把云端节点元数据当作本地出口。

错误与重试

错误响应统一为 {"error":{"code","message","requestId","details"}}。程序只判断 code；message 用于展示，requestId 用于脱敏排障。

认证: robocloud_auth_required、robocloud_auth_invalid、robocloud_session_expired、robocloud_session_revoked、robocloud_account_disabled、robocloud_api_key_revoked。
权限与归属: robocloud_scope_required、service_not_found、robocloud_service_inactive、package_inactive。不存在和不属于当前账户的服务均返回同一个 404，避免泄露其他账户资源。
幂等与报价: idempotency_key_required、idempotency_key_reused、quote_required、quote_changed、line_quote_changed。同一键同一请求可安全重放；同一键不同请求必须换新键。
余额与容量: insufficient_balance、payg_minimum_balance_required、payg_service_exists、line_limit_reached、line_operation_running。
请求与临时故障: request_too_large、robocloud_rate_limited、database_busy、robocloud_upstream_unavailable。仅对后三种临时错误采用带抖动的指数退避，并复用原幂等键。
Runner 配对与认证: runner_pairing_invalid、runner_pairing_expired、runner_pairing_consumed、runner_pairing_unsupported、runner_auth_invalid、runner_token_revoked、runner_signature_invalid、runner_request_replayed、runner_version_unsupported。
Runner 控制: runner_not_found、runner_offline、runner_capability_required、runner_revision_conflict、runner_operation_expired、runner_lease_invalid、runner_result_invalid。Runner 离线或尚未确认不等于成功。

完整的常用错误码目录同时写入 OpenAPI 根级 x-error-code-catalog，领域接口还可能返回其在 OpenAPI 响应中说明的更具体错误码。