rtk-vats-api

REST-API über der internen API des persönlichen Kontos der virtuellen Telefonanlage von Rostelecom (cloudpbx.rt.ru/webapi). Ermöglicht Skripten und KI-Agenten die Steuerung der Telefonie: Kontakte, Teilnehmer, Anrufgruppen, Anrufverlauf, Gesprächsaufzeichnungen, Nummern und Routing, Guthaben – plus einen transparenten Proxy zu jedem der ~240 Endpunkte der VTA.

Der Zugang erfolgt über Benutzername und Passwort des „Rostelecom-Passports“ mit Bestätigung per SMS-Code; danach wird die Sitzung automatisch aufrechterhalten. Im Lieferumfang enthalten sind ein MCP-Server und ein fertiger Skill, damit ein KI-Agent (Claude Code und kompatible) dies nutzen kann.

Inoffizielles Projekt: nutzt die interne API des persönlichen Kontos, die Rostelecom ohne Vorwarnung ändern kann. Nicht mit PJSC Rostelecom verbunden.

So funktioniert es

• Anmeldung – mit Benutzername und Passwort des „Rostelecom-Passports“ plus einem Einmalcode aus SMS (POST /auth/login → POST /auth/code). Danach funktioniert der Dienst von selbst: JWT ~24 Minuten, ein Hintergrund-Keepalive erneuert ihn über das Refresh-Token.

• Die Sitzung wird in data/session.json (Rechte 600) gespeichert und übersteht einen Neustart des Dienstes.

• Der Zugriff auf diese API erfolgt über den Header X-API-Key (Wert in .env).

Warum für die Anmeldung eine Browser-Engine nötig ist

Bei Domains, die mit dem „Rostelecom-Passport“ verbunden sind, funktioniert das klassische POST /webapi/auth (Benutzername + Passwort + Domain) nicht: Ein solches Konto hat kein eigenes Passwort in der VTA, der Server antwortet mit „Die eingegebenen Anmeldedaten sind ungültig“. Die Anmeldung erfolgt über die Kette /webapi/sso → Keycloak passport.rt.ru → SMS-Code → Rückkehr zum persönlichen Konto mit Tokens.

Die Passport-Seiten sind durch den Anti-Bot F5 geschützt: Ein normaler HTTP-Client erhält eine JS-Herausforderung statt des Formulars, und grant_type=password (ROPC) – dieselbe Herausforderung. Deshalb führt den Login-Schritt eine echte Engine (Playwright, Chromium) aus – nur im Moment der Anmeldung, für etwa dreißig Sekunden. Die gesamte weitere Arbeit erfolgt mit normalem httpx ohne Browser.

Wenn Sie Chromium nicht auf dem Server installieren möchten, gibt es zwei Wege: scripts/login_helper.py (der Browser läuft auf Ihrem Rechner, die Tokens werden an den Dienst übergeben) oder manuelles POST /auth/import.

Related MCP server: Radius MCP Server

Start (Entwicklung)

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-Dokumentation: http://<host>:8010/docs

Autorisierung

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"

Benutzername und Passwort können auch weggelassen werden – dann werden PBX_USERNAME / PBX_PASSWORD aus .env verwendet. Anmeldung mit Einmalcode ohne Passwort: {"by_code": true}.

Für die Eingabe des Codes stehen BROWSER_CODE_TTL Sekunden zur Verfügung (Standard: 300): Während dieser Zeit wartet die geöffnete Passport-Seite auf den Code. Wenn Sie es nicht rechtzeitig schaffen, beginnen Sie erneut mit /auth/login.

Anmeldung ohne Browser auf dem Server

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

Manueller Import von Tokens (letzter Ausweg)

DevTools (F12) → Application → Local Storage → token, refreshToken. Der Wert fingerprint ist im Speicher nicht vorhanden – aus der Adressleiste des SSO-Redirects entnehmen (...&fingerprint=...) oder getBrowserFingerprint() in der Konsole des persönlichen Kontos ausführen. Ohne fingerprint funktioniert die Sitzungsaktualisierung nicht.

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

Domains ohne SSO

Wenn das Konto ein eigenes Passwort in der VTA selbst hat, funktioniert die klassische Anmeldung: POST /auth/start (Benutzername/Passwort/Domain aus .env) → POST /auth/complete mit dem Code aus SMS.

Endpunkte

Bequeme (typisierte)

Transparenter Proxy

Jeder VTA-Endpunkt ist über ANY /proxy/{path} → /webapi/{path} erreichbar (Query, Body und Methode werden durchgereicht; binäre Antworten werden unverändert ausgegeben):

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

Die Karte der VTA-Endpunkte (auth, domain/, callcenter/, user/*, meetings, ivr …) – im Quellcode des persönlichen Kontos lk_new/assets/index-*.js (nach callApi("/... greppen).

Tests

.venv/bin/python -m pytest -q

Mocks über respx, keine echten Anfragen an die VTA.

Skill für KI-Systeme

MCP-Server (mcp_server/)

MCP-Server rtk-vats (stdio) mit typisierten Tools vats_* – verbindet sich mit jedem Agenten, der MCP unterstützt (Kimi Code, Claude Code/Desktop, Cursor). Er greift über HTTP auf diese REST-API zu und läuft daher auf dem Rechner des Agenten:

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

Tools: 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 (lädt in VATS_DOWNLOAD_DIR, Standard ./downloads), vats_balance, vats_numbers, vats_settings, vats_proxy (beliebiger VTA-Endpunkt).

SKILL.md (skills/rtk-vats/)

Fertiger Skill für CLI-Agenten (Claude Code / Kimi Code und kompatible): Anmeldeablauf (Benutzername/Passwort → SMS), Endpunkte, Sicherheitsregeln und Nachschlagewerk references/pbx-setup.md zur Einrichtung der Telefonanlage (Teilnehmer, Gruppen, IVR, Zeitpläne). Installation – kopieren oder Symlink skills/rtk-vats/ in das Skill-Verzeichnis des Agenten (Projekt-.kimi/skills/, .claude/skills/ oder benutzerdefiniert).

Deployment (Docker)

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

Das Standard-Image enthält Chromium für die Anmeldung über den Passport. Leichte Variante ohne – docker build --build-arg WITH_BROWSER=0 -t rtk-vats-api:slim .; dann erfolgt die Anmeldung extern (scripts/login_helper.py) oder über /auth/import.

⚠️ Port 8010 im lokalen Netzwerk oder hinter VPN halten und nicht im Internet veröffentlichen: dahinter liegt eine aktive Sitzung Ihrer Telefonanlage. Der Schlüssel API_KEY ist der einzige Schutz des Dienstes selbst.

Sicherheit

• Passwort, SMS-Codes und Tokens werden nicht protokolliert; .env und data/ in .gitignore.

• PBX_VERIFY_SSL=false – nur für Maschinen hinter einem Unternehmens-MITM-Proxy (sonst stimmt die Zertifikatskette nicht). Auf dem Server true lassen.

• Der zweite Faktor wird nicht umgangen: Den SMS-Code gibt ein Mensch ein, einmal pro Sitzung.

• Ein nicht abgeschlossener Anmeldeversuch wird per Timeout beendet – der Browser bleibt nicht hängen.

Falls RTK die API ändert

Es gibt nur eine Stelle zum Anpassen: app/pbx_client.py (Autorisierung/Refresh) + der entsprechende Router in app/routers/. Der Proxy /proxy/* funktioniert weiter, solange sich das Pfadschema selbst nicht ändert.