rtk-vats-api

基于Ростелеком 虚拟 PBX个人账户内部 API（cloudpbx.rt.ru/webapi）的 REST API。允许脚本和 AI 代理管理电话系统：联系人、用户、呼叫组、通话记录、通话录音、号码和路由、余额——以及对 VPBX 约 240 个端点中的任意一个进行透明代理。

登录方式为“Ростелеком 通行证”用户名和密码，并通过短信验证码确认；之后会话自动维持。附带 MCP 服务器和现成的技能，以便 AI 代理（Claude Code 及兼容工具）可以使用它。

非官方项目：使用个人账户的内部 API，Ростелеком 可能在不事先通知的情况下更改该 API。与 ПАО «Ростелеком» 无关联。

工作原理

• 登录 — 使用“Ростелеком 通行证”用户名和密码以及一次性短信验证码（POST /auth/login → POST /auth/code）。之后服务自行运行：JWT 约 24 分钟，后台 keepalive 通过 refresh 令牌更新它。

• 会话存储在 data/session.json（权限 600）中，并在服务重启后仍然有效。

• 对此 API 的访问通过 X-API-Key 标头（值在 .env 中）。

为什么登录需要浏览器引擎

对于连接到“Ростелеком 通行证”的域，经典的 POST /webapi/auth（用户名 + 密码 + 域）不起作用：此类账户在 VPBX 中没有自己的密码，服务器响应“Введенные учетные данные некорректны”。登录通过 /webapi/sso → Keycloak passport.rt.ru → 短信验证码 → 携带令牌返回个人账户的链式流程进行。

通行证页面受 F5 反机器人保护：普通 HTTP 客户端会收到 JS 挑战而不是表单，而 grant_type=password（ROPC）也会收到同样的挑战。因此，登录步骤由真正的引擎（Playwright、Chromium）执行——仅在登录时，大约三十秒。所有后续工作都通过普通的 httpx 进行，无需浏览器。

如果不想在服务器上安装 Chromium，有两种方法：scripts/login_helper.py（浏览器在您的机器上运行，令牌发送给服务）或手动 POST /auth/import。

Related MCP server: Radius MCP Server

启动（开发）

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/playwright install chromium     # нужен только для /auth/login
cp .env.example .env                      # заполнить PBX_USERNAME/PBX_PASSWORD, API_KEY
.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8010

OpenAPI 文档：http://<host>:8010/docs

授权

KEY="X-API-Key: <ваш API_KEY>"

# 1. Логин и пароль -> на телефон владельца учётки уходит SMS
curl -X POST http://localhost:8010/auth/login -H "$KEY" \
     -H 'Content-Type: application/json' \
     -d '{"username":"lk_1234567890","password":"..."}'
# -> {"status":"code_required","hint":"Мы отправили код на номер +7 ...","seconds_to_enter_code":300}

# 2. Код из SMS
curl -X POST http://localhost:8010/auth/code -H "$KEY" \
     -H 'Content-Type: application/json' -d '{"code":"123456"}'
# -> {"status":"ok","seconds_left":1435,"has_refresh_token":true,"has_fingerprint":true}

# Состояние сессии / принудительное обновление / отмена входа
curl http://localhost:8010/auth/status -H "$KEY"
curl -X POST http://localhost:8010/auth/refresh -H "$KEY"
curl -X POST http://localhost:8010/auth/cancel  -H "$KEY"

用户名和密码可以不传入请求——此时从 .env 中读取 PBX_USERNAME / PBX_PASSWORD。使用一次性验证码登录而无需密码：{"by_code": true}。

输入验证码的时间限制为 BROWSER_CODE_TTL 秒（默认 300）：在此期间，打开的通行证页面会等待验证码。如果超时——请从 /auth/login 重新开始。

在服务器上无需浏览器登录

# на своей машине (там, где есть playwright); токены уедут на удалённый сервис
python scripts/login_helper.py --api-url http://10.10.0.187:8010 --api-key <KEY>

手动导入令牌（最后手段）

DevTools（F12）→ Application → Local Storage → token、refreshToken。存储中缺少 fingerprint 值——从 SSO 重定向的地址栏中获取（...&fingerprint=...）或在个人账户控制台中执行 getBrowserFingerprint()。 没有 fingerprint，会话刷新将无法工作。

curl -X POST http://localhost:8010/auth/import -H "$KEY" \
     -H 'Content-Type: application/json' \
     -d '{"token":"<JWT>","refresh_token":"<refreshToken>","fingerprint":"<fp>"}'

无 SSO 的域

如果账户在 VPBX 本身中有自己的密码，则经典登录有效：POST /auth/start（用户名/密码/域来自 .env）→ POST /auth/complete 并输入短信验证码。

端点

便捷端点（类型化）

透明代理

任何 VPBX 端点都可通过 ANY /proxy/{path} → /webapi/{path} 访问（query、请求体和方法均透传；二进制响应原样返回）：

curl http://localhost:8010/proxy/domain/payments/balance -H "$KEY"
curl -X POST http://localhost:8010/proxy/callcenter/reports/by_calls \
     -H "$KEY" -H 'Content-Type: application/json' -d '{"date_from":"2026-08-01"}'

VPBX 端点映射（auth、domain/、callcenter/、user/*、meetings、ivr …）— 在个人账户源码 lk_new/assets/index-*.js 中（搜索 callApi("/...）。

测试

.venv/bin/python -m pytest -q

通过 respx 模拟，不向 VPBX 发送真实请求。

面向神经网络的技能

MCP 服务器（mcp_server/）

MCP 服务器 rtk-vats（stdio），带有类型化工具 vats_* — 可连接到任何支持 MCP 的代理（Kimi Code、Claude Code/Desktop、Cursor）。它通过 HTTP 访问此 REST API，因此在代理机器上运行：

{
  "mcpServers": {
    "rtk-vats": {
      "command": "/path/to/rtk-vats-api/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/rtk-vats-api",
      "env": {
        "VATS_API_URL": "http://10.10.0.187:8010",
        "VATS_API_KEY": "<тот же API_KEY>"
      }
    }
  }
}

工具：vats_auth_login/code/status/refresh/cancel、vats_contacts_*、vats_domain_users、vats_users_list、vats_groups_list、vats_calls_history、vats_call_protocol、vats_call_record（下载到 VATS_DOWNLOAD_DIR，默认 ./downloads）、vats_balance、vats_numbers、vats_settings、vats_proxy（任何 VPBX 端点）。

SKILL.md（skills/rtk-vats/）

适用于 CLI 代理（Claude Code / Kimi Code 及兼容工具）的现成技能：登录流程（用户名/密码 → 短信）、端点、安全规则以及关于 PBX 配置（用户、组、IVR、日程）的参考手册 references/pbx-setup.md。安装 — 将 skills/rtk-vats/ 复制或创建符号链接到代理的技能目录（项目 .kimi/skills/、.claude/skills/ 或用户目录）。

部署（Docker）

cp .env.example .env      # заполнить PBX_USERNAME/PBX_PASSWORD, API_KEY
docker compose up -d --build
docker compose logs -f

默认镜像包含用于通过通行证登录的 Chromium。不带它的轻量版本 — docker build --build-arg WITH_BROWSER=0 -t rtk-vats-api:slim .；此时登录在外部执行（scripts/login_helper.py）或通过 /auth/import。

⚠️ 端口 8010 应保持在本地网络或 VPN 内，不要发布到互联网：其后是您 PBX 的活动会话。API_KEY 是服务本身的唯一保护。

安全性

• 密码、短信验证码和令牌不会记录日志；.env 和 data/ 在 .gitignore 中。

• PBX_VERIFY_SSL=false — 仅适用于位于企业 MITM 代理后面的机器（否则证书链无法验证）。在服务器上保持 true。

• 第二因素不会被绕过：短信验证码由人工输入，每个会话一次。

• 未完成的登录尝试会因超时而关闭 — 浏览器不会一直挂起。

如果 RTK 更改 API

需要修改的点只有一个：app/pbx_client.py（授权/刷新）+ app/routers/ 中相应的路由器。只要路径方案本身不变，/proxy/* 代理将继续工作。