rtk-vats-api

API REST sobre la API interna del área personal de la Centralita Virtual de Rostelecom (cloudpbx.rt.ru/webapi). Permite a scripts y agentes de IA gestionar la telefonía: contactos, abonados, grupos de llamadas, historial de llamadas, grabaciones de conversaciones, números y enrutamiento, saldo — además de un proxy transparente a cualquiera de los ~240 endpoints de la centralita.

El acceso se realiza con el usuario y la contraseña del «Pasaporte Rostelecom» con confirmación mediante código SMS; a partir de ahí la sesión se mantiene automáticamente. Incluye un servidor MCP y una skill lista para que pueda usarla un agente de IA (Claude Code y compatibles).

Proyecto no oficial: utiliza la API interna del área personal, que Rostelecom puede modificar sin previo aviso. No está afiliado a PJSC «Rostelecom».

Cómo funciona

• Acceso — con el usuario y la contraseña del «Pasaporte Rostelecom» más un código de un solo uso por SMS (POST /auth/login → POST /auth/code). A partir de ahí el servicio funciona solo: JWT ~24 minutos, un keepalive en segundo plano lo renueva mediante el token de refresco.

• La sesión se guarda en data/session.json (permisos 600) y sobrevive al reinicio del servicio.

• El acceso a esta API se realiza mediante la cabecera X-API-Key (valor en .env).

Por qué se necesita un motor de navegador para el acceso

En los dominios conectados al «Pasaporte Rostelecom», el clásico POST /webapi/auth (usuario + contraseña + dominio) no funciona: esa cuenta no tiene contraseña propia en la centralita, el servidor responde «Las credenciales introducidas son incorrectas». El acceso se realiza mediante la cadena /webapi/sso → Keycloak passport.rt.ru → código SMS → retorno al área personal con los tokens.

Las páginas del Pasaporte están protegidas por el antibot F5: un cliente HTTP normal recibe un desafío JS en lugar del formulario, y grant_type=password (ROPC) — el mismo desafío. Por eso el paso de inicio de sesión lo realiza un motor real (Playwright, Chromium) — solo en el momento del acceso, durante unos treinta segundos. Todo el trabajo posterior se realiza con httpx normal, sin navegador.

Si no quieres instalar Chromium en el servidor, hay dos opciones: scripts/login_helper.py (el navegador se ejecuta en tu máquina, los tokens se envían al servicio) o el POST /auth/import manual.

Related MCP server: Radius MCP Server

Ejecución (desarrollo)

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

Documentación OpenAPI: http://<host>:8010/docs

Autorización

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"

El usuario y la contraseña pueden omitirse en la petición — entonces se toman PBX_USERNAME / PBX_PASSWORD de .env. Acceso con código de un solo uso sin contraseña: {"by_code": true}.

Para introducir el código se dispone de BROWSER_CODE_TTL segundos (por defecto 300): durante todo ese tiempo la página abierta del Pasaporte espera el código. Si no llegas a tiempo — empieza por /auth/login.

Acceso sin navegador en el servidor

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

Importación manual de tokens (caso extremo)

DevTools (F12) → Application → Local Storage → token, refreshToken. El valor fingerprint no está en el almacenamiento — se toma de la barra de direcciones del redireccionamiento SSO (...&fingerprint=...) o se ejecuta getBrowserFingerprint() en la consola del área personal. Sin fingerprint la renovación de la sesión no funcionará.

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

Dominios sin SSO

Si la cuenta tiene contraseña propia en la propia centralita, funciona el acceso clásico: POST /auth/start (usuario/contraseña/dominio de .env) → POST /auth/complete con el código del SMS.

Endpoints

Cómodos (tipados)

Proxy transparente

Cualquier endpoint de la centralita está disponible mediante ANY /proxy/{path} → /webapi/{path} (query, cuerpo y método se reenvían; las respuestas binarias se devuelven tal cual):

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

El mapa de endpoints de la centralita (auth, domain/, callcenter/, user/*, meetings, ivr …) — en el código fuente del área personal lk_new/assets/index-*.js (buscar callApi("/...).

Pruebas

.venv/bin/python -m pytest -q

Mocks mediante respx, no hay peticiones reales a la centralita.

Skill para redes neuronales

Servidor MCP (mcp_server/)

Servidor MCP rtk-vats (stdio) con herramientas tipadas vats_* — se conecta a cualquier agente con soporte MCP (Kimi Code, Claude Code/Desktop, Cursor). Accede a esta API REST por HTTP, por lo que se ejecuta en la máquina del agente:

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

Herramientas: 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 (descarga en VATS_DOWNLOAD_DIR, por defecto ./downloads), vats_balance, vats_numbers, vats_settings, vats_proxy (cualquier endpoint de la centralita).

SKILL.md (skills/rtk-vats/)

Skill lista para agentes CLI (Claude Code / Kimi Code y compatibles): flujo de acceso (usuario/contraseña → SMS), endpoints, reglas de seguridad y manual de referencia references/pbx-setup.md para la configuración de la centralita (abonados, grupos, IVR, horarios). Instalación — copiar o crear un symlink skills/rtk-vats/ en el directorio de skills del agente (.kimi/skills/ del proyecto, .claude/skills/ o el del usuario).

Despliegue (Docker)

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

La imagen por defecto incluye Chromium para el acceso mediante el Pasaporte. Variante ligera sin él — docker build --build-arg WITH_BROWSER=0 -t rtk-vats-api:slim .; entonces el acceso se realiza desde fuera (scripts/login_helper.py) o mediante /auth/import.

⚠️ Mantener el puerto 8010 en la red local o detrás de una VPN y no publicarlo en internet: detrás hay una sesión viva de tu centralita. La clave API_KEY — es la única protección del propio servicio.

Seguridad

• La contraseña, los códigos SMS y los tokens no se registran en logs; .env y data/ están en .gitignore.

• PBX_VERIFY_SSL=false — solo para máquinas detrás de un proxy MITM corporativo (de lo contrario la cadena de certificados no cuadra). En el servidor dejar true.

• El segundo factor no se elude: el código SMS lo introduce una persona, una vez por sesión.

• Un intento de acceso sin completar se cierra por tiempo de espera — el navegador no se queda colgado.

Si RTK cambia la API

El punto de modificación es uno solo: app/pbx_client.py (autorización/refresh) + el router correspondiente en app/routers/. El proxy /proxy/* seguirá funcionando mientras no cambie el propio esquema de rutas.