API

Kalkan Local API позволяет вашим собственным скриптам управлять профилями, прокси и папками, запускать и останавливать браузеры и управлять ими через Playwright, Puppeteer или Selenium. Это REST API, который предоставляет запущенное настольное приложение Kalkan на вашем компьютере:

http://127.0.0.1:50360/api/v1

Все запросы и ответы передаются в формате JSON. API входит в тарифы Starter, Pro и Unlimited (кроме пробного периода).

Включение и получение ключа

1. Откройте Kalkan → Настройки → API и включите API.
2. Измените порт, если 50360 на вашем компьютере занят.
3. Скопируйте ключ API (он начинается с kk_). Кнопка Перевыпустить создаёт новый ключ, а старый сразу перестаёт работать.

API доступен, пока открыто приложение Kalkan. Для серверов и скриптов без окна есть также команда для разработчиков adb api, которая предоставляет тот же API.

Аутентификация и безопасность

• Передавайте ключ в каждом запросе в заголовке X-Token: <key>. Также принимается Authorization: Bearer <key>.
• При отсутствии ключа или неверном ключе возвращается 401 unauthorized. После 10 неверных ключей в течение минуты API отвечает 429 locked в течение 60 секунд.
• API слушает только 127.0.0.1 и отвечает только на запросы, адресованные 127.0.0.1 или localhost (иначе 403 forbidden_host). С других компьютеров он недоступен.
• API предназначен для скриптов, а не для веб-страниц: запросы с заголовком Origin (его отправляют браузеры) отклоняются с 403 forbidden_origin, CORS не поддерживается.
• Ключ — единственный секрет. Не добавляйте его в репозитории кода; если он утёк, перевыпустите его.
• Если API не входит в ваш тариф, любой вызов возвращает 403 plan. GET /status работает всегда и в поле api_allowed сообщает, входит ли API в ваш тариф.

Ответы и ошибки

Успешный вызов возвращает {"ok": true, "data": …}; неудачный — {"ok": false, "error": {"code": "…", "message": "…"}}.

{"ok": true, "data": {"id": "…", "running": true, "ws": "ws://127.0.0.1:49731/devtools/browser/…", "debug_port": 49731, "pid": 12345}}

{"ok": false, "error": {"code": "unauthorized", "message": "missing or wrong API key (send it as the X-Token header)"}}

Движки

В Kalkan четыре движка: Kalkan Native (рекомендуется; наш собственный Chromium с более чем 150 патчами на C++, которые формируют отпечаток прямо в его коде; приложение устанавливает и обновляет его в фоне), Kalkan (патч Chrome: ваш настоящий Google Chrome с модифицированным драйвером), Kalkan Edge (тот же слой на установленном Microsoft Edge; при создании "engine": "edge") и Firefox (профили Windows, macOS и Linux). Профили Kalkan, Kalkan Edge и Kalkan Native запускаются с эндпоинтом DevTools (CDP) для автоматизации; профили Firefox запускаются без него (ws равен null).

Эндпоинты

Все пути указаны относительно http://127.0.0.1:50360/api/v1.

Примеры: curl

В PowerShell вводите curl.exe, так как curl там является псевдонимом Invoke-WebRequest. JSON-тела проще всего отправлять из Git Bash, cmd или скрипта.

curl -H "X-Token: kk_..." http://127.0.0.1:50360/api/v1/status

curl -H "X-Token: kk_..." "http://127.0.0.1:50360/api/v1/profiles?status=running&sort=last_used&desc=1"

curl -X POST -H "X-Token: kk_..." -H "Content-Type: application/json" \
     -d '{"name": "shop-01", "os": "windows", "mode": "balanced", "proxy": "socks5://1.2.3.4:1080", "proxy_user": "user", "proxy_pass": "pass"}' \
     http://127.0.0.1:50360/api/v1/profiles

curl -X POST -H "X-Token: kk_..." -H "Content-Type: application/json" \
     -d '{"url": "https://example.com"}' \
     http://127.0.0.1:50360/api/v1/profiles/PROFILE_ID/start

Примеры: Python + Playwright

Создаёт профиль с прокси, открывает его и подключается через connect_over_cdp (pip install requests playwright).

import requests
from playwright.sync_api import sync_playwright

API = "http://127.0.0.1:50360/api/v1"
H = {"X-Token": "kk_..."}

def call(method, path, **kw):
    r = requests.request(method, API + path, headers=H, timeout=200, **kw).json()
    if not r["ok"]:
        raise RuntimeError(r["error"]["code"] + ": " + r["error"]["message"])
    return r["data"]

prof = call("POST", "/profiles", json={
    "name": "shop-01", "os": "windows", "mode": "balanced",
    "proxy": {"type": "socks5", "host": "1.2.3.4", "port": 1080,
              "username": "user", "password": "pass"},
})
run = call("POST", f"/profiles/{prof['id']}/start")

with sync_playwright() as pw:
    browser = pw.chromium.connect_over_cdp(run["ws"])
    ctx = browser.contexts[0]                  # the profile's own context
    page = ctx.pages[0] if ctx.pages else ctx.new_page()
    page.goto("https://example.com")
    print(page.title())

call("POST", f"/profiles/{prof['id']}/stop")

Примеры: Node.js + Puppeteer

Используйте puppeteer-core: браузер запускает Kalkan, а Puppeteer только подключается к нему.

const puppeteer = require("puppeteer-core");

const API = "http://127.0.0.1:50360/api/v1";
const H = { "X-Token": "kk_...", "Content-Type": "application/json" };

(async () => {
  const res = await fetch(`${API}/profiles/PROFILE_ID/start`, { method: "POST", headers: H, body: "{}" });
  const { ok, data, error } = await res.json();
  if (!ok) throw new Error(`${error.code}: ${error.message}`);

  const browser = await puppeteer.connect({ browserWSEndpoint: data.ws, defaultViewport: null });
  const [page] = await browser.pages();
  await page.goto("https://example.com");
  console.log(await page.title());
  await browser.disconnect();
})();

Примеры: Selenium

Selenium подключается через debug_port. Основная версия chromedriver должна совпадать с версией браузера (Kalkan использует установленный у вас Chrome).

import requests
from selenium import webdriver

API = "http://127.0.0.1:50360/api/v1"
H = {"X-Token": "kk_..."}

run = requests.post(f"{API}/profiles/PROFILE_ID/start", headers=H, json={}).json()["data"]

opts = webdriver.ChromeOptions()
opts.debugger_address = f"127.0.0.1:{run['debug_port']}"
driver = webdriver.Chrome(options=opts)
driver.get("https://example.com")
print(driver.title)

Советы

• Не задавайте viewport из скрипта. Размер экрана профиля — часть его отпечатка. Используйте defaultViewport: null в Puppeteer и не передавайте viewport в Playwright.
• Используйте существующий контекст профиля. В Playwright берите browser.contexts[0] вместо new_context(): в новом контексте нет ни cookies, ни настроек профиля.
• По завершении скрипта отключайтесь, а не закрывайте браузер, и останавливайте профиль через POST /profiles/{id}/stop, чтобы Kalkan корректно сохранил сессию.
• Запуск уже открытого профиля возвращает тот же эндпоинт с already_running: true, поэтому скрипты могут безопасно вызывать start повторно.
• Обрабатывайте 409 осознанно: allow_direct и force существуют для того, чтобы скрипт никогда случайно не открыл профиль без прокси или на повторно используемом IP.