rtk-vats-api

ロステレコム仮想PBX（cloudpbx.rt.ru/webapi）の個人アカウント内部APIの上に構築されたREST API。スクリプトやAIエージェントが電話機能（連絡先、加入者、コールグループ、通話履歴、通話録音、番号とルーティング、残高）を操作できるようにするほか、VATSの約240のエンドポイントすべてへの透過的なプロキシも提供します。

ログインは「ロステレコムパスポート」のログイン名とパスワードに加え、SMSで届くコードによる確認が必要です。以降はセッションが自動的に維持されます。MCPサーバーと既製スキルが同梱されており、AIエージェント（Claude Codeおよび互換製品）がこれを利用できます。

非公式プロジェクトです。ロステレコムが予告なく変更する可能性のある個人アカウントの内部APIを使用しています。PJSCロステレコムとは提携関係にありません。

仕組み

• ログイン — 「ロステレコムパスポート」のログイン名とパスワードに加え、SMSで届くワンタイムコードを使用（POST /auth/login → POST /auth/code）。以降はサービスが自動で維持します。JWTは約24分、バックグラウンドのkeepaliveがリフレッシュトークンで更新します。

• セッションはdata/session.json（権限600）に保存され、サービス再起動後も維持されます。

• このAPIへのアクセスはX-API-Keyヘッダー（値は.env内）で行います。

ログインにブラウザエンジンが必要な理由

「ロステレコムパスポート」に接続されているドメインでは、従来のPOST /webapi/auth（ログイン名＋パスワード＋ドメイン）は機能しません。そのようなアカウントにはVATS独自のパスワードがなく、サーバーは「入力された認証情報が正しくありません」と応答します。ログインは/webapi/sso → Keycloak passport.rt.ru → SMSコード → トークン付きで個人アカウントに戻る、というチェーンで行われます。

パスポートのページはF5アンチボットで保護されています。通常のHTTPクライアントはフォームの代わりにJSチャレンジを受け取り、grant_type=password（ROPC）でも同じチャレンジが返ります。そのため、ログインステップは実際のエンジン（Playwright、Chromium）で実行されます — ログイン時のみ、約30秒間。以降のすべての処理はブラウザなしの通常のhttpxで行われます。

サーバーにChromiumをインストールしたくない場合は、2つの方法があります。 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なしのドメイン

アカウントがVATS自体に独自のパスワードを持っている場合は、従来のログインが機能します。 POST /auth/start（.envのログイン名/パスワード/ドメイン）→ SMSのコードによるPOST /auth/complete。

エンドポイント

便利なもの（型付き）

透過的プロキシ

VATSの任意のエンドポイントはANY /proxy/{path} → /webapi/{path}で利用できます （クエリ、ボディ、メソッドはそのまま渡され、バイナリ応答もそのまま返されます）:

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"}'

VATSエンドポイントのマップ（auth、domain/、callcenter/、user/*、meetings、ivr …）は 個人アカウントのソースlk_new/assets/index-*.jsにあります（callApi("/...をgrep）。

テスト

.venv/bin/python -m pytest -q

モックはrespxを使用しており、VATSへの実際のリクエストはありません。

ニューラルネットワーク用スキル

MCPサーバー（mcp_server/）

型付きツールvats_*を備えたMCPサーバーrtk-vats（stdio）— MCPをサポートする任意のエージェント（Kimi Code、Claude Code/Desktop、Cursor）に接続できます。 このREST APIにHTTPでアクセスするため、エージェントのマシン上で実行されます:

{
  "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（VATSの任意のエンドポイント）。

SKILL.md（skills/rtk-vats/）

CLIエージェント（Claude Code / Kimi Codeおよび互換製品）向けの既製スキル: ログインフロー （ログイン名/パスワード → SMS）、エンドポイント、セキュリティルール、および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キーがサービスの唯一の保護です。

セキュリティ

• パスワード、SMSコード、トークンはログに記録されません。.envとdata/は.gitignoreに含まれます。

• PBX_VERIFY_SSL=false — 企業のMITMプロキシの背後にあるマシン専用 （それ以外の場合は証明書チェーンが一致しません）。サーバーではtrueのままにしてください。

• 2要素認証は回避されません。SMSコードは人間がセッションごとに1回入力します。

• 未完了のログイン試行はタイムアウトで終了します — ブラウザがぶら下がったままになることはありません。

RTKがAPIを変更した場合

修正箇所は1つです: app/pbx_client.py（認証/リフレッシュ）+ app/routers/内の対応するルーター。 /proxy/*プロキシは、パスのスキーマ自体が変更されない限り機能し続けます。