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가 refresh 토큰으로 갱신합니다.

• 세션은 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을 설치하고 싶지 않다면 두 가지 방법이 있습니다: 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}로 접근 가능합니다 (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"}'

VATS 엔드포인트 맵(auth, domain/, callcenter/, user/*, meetings, ivr …)은 개인 계정 소스 lk_new/assets/index-*.js에 있습니다(callApi("/... 검색).

테스트

.venv/bin/python -m pytest -q

respx를 통한 목(mock)이며 VATS에 대한 실제 요청은 없습니다.

신경망용 스킬

MCP 서버 (mcp_server/)

rtk-vats MCP 서버(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(모든 VATS 엔드포인트).

SKILL.md (skills/rtk-vats/)

CLI 에이전트(Claude Code / Kimi Code 및 호환 제품)용 준비된 스킬: 로그인 플로우 (아이디/비밀번호 → SMS), 엔드포인트, 보안 규칙 및 PBX 설정 가이드 references/pbx-setup.md (가입자, 그룹, IVR, 일정). 설치 — 에이전트 스킬 디렉토리(프로젝트 .kimi/skills/, .claude/skills/ 또는 사용자 디렉토리)에 skills/rtk-vats/를 복사하거나 symlink 생성.

배포 (Docker)

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

기본 이미지에는 패스포트 로그인용 Chromium이 포함되어 있습니다. 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 코드는 세션당 한 번 사람이 입력합니다.

• 완료되지 않은 로그인 시도는 타임아웃으로 종료됩니다 — 브라우저가 계속 떠 있지 않습니다.

RTK가 API를 변경하는 경우

수정 지점은 하나입니다: app/pbx_client.py(인증/refresh) + app/routers/의 해당 라우터. /proxy/* 프록시는 경로 체계 자체가 변경되지 않는 한 계속 작동합니다.