Локальный API, ключи и вызовы

Локальный API это небольшой веб-сервер внутри программы. Ваши программы на той же машине зовут его по петле и получают ответ.

Всё, с чем он работает, лежит у вас на диске: профили, куки, движок и мост прокси. Пропала сеть, а ваши сценарии зовут по-прежнему, и сама программа держится без сети сутки.

• Вести профили из своей программы

  Перечислить, создать, запустить, остановить и удалить, не трогая окно.

• Подключить Puppeteer, Playwright или Selenium

  В ответ вы получаете адрес отладки именно этого профиля.

• Запускать сохранённые сценарии снаружи

  Ваше расписание или сборочный сервер запускает сценарий по названным профилям.

• Дать работать помощнику ИИ

  Через встроенный сервер MCP помощник ИИ берёт те же ходы, и интерфейс должен быть включён.

Интерфейс выключен, пока вы его не включите, потому что включение открывает порт. При первом запуске программа выписывает себе случайный токен, 24 байта в виде 48 знаков, в файл, доступный только вашей учётной записи.

Токен вы передаёте тремя путями: параметром в адресе, своим заголовком или общим заголовком доступа. Обновив токен, вы остановите каждый сценарий со старым, поэтому программа сперва спрашивает подтверждение.

1. 1

   Откройте экран «Для программистов»

   На нём переключатель, адрес, токен и список ходов.

2. 2

   Нажмите «Включить локальный API»

   Вы должны увидеть «Запущен», а если обычный порт занят, панель назовёт тот, который взяла.

3. 3

   Скопируйте адрес и токен

   Панель даёт готовую строку вызова с вашим собственным токеном внутри.

4. 4

   Наведите на него свой сценарий

   Каждый ваш вызов, кроме хода состояния, несёт токен, а на неверный вы получите 401.

Привязка к петле похожа на границу. Границей она не является: страницы, которые вы открываете, работают на этом же компьютере и до того же адреса дотянутся.

Поэтому со страницы в браузере до него не дозвониться: программа узнаёт такой вызов и отвечает отказом. Доменное имя, наведённое на петлю, тоже не поможет: оно приходит под своим именем и получает отказ.

В ответе вы найдёте три поля: код, содержимое и сообщение. При удаче код равен нулю, а при отказе вы получаете причину. Особняком стоит вопрос о состоянии интерфейса: он отвечает своей короткой формой и полей содержимого с сообщением не несёт.

Ветвитесь по коду в конверте, а не по состоянию HTTP: состоянием отвечают отказы на входе, а отказ по существу приходит двухсотым с ненулевым кодом. Тело больше мегабайта интерфейс не обрезает: ответ 413 с payload_too_large, а загрузка куки, одноразовый профиль и ввоз принимают до 16 МБ.

Номер профиля можно передать и в теле, и в строке запроса: оба примера ниже передают его строкой запроса, и переделывать их не придётся. Можно попросить прогон без окна, а если не просить ничего, решает настройка самого профиля.

Что вернётся, зависит от движка. На ARMANOS Browser у каждого профиля свой адрес отладки, отделённый от всех остальных.

• Движок ARMANOS Browser

  Порт и адрес сокета только для этого профиля. Подключайте свою библиотеку прямо к нему.

• Встроенный движок

  Один общий порт на всю программу, названный в ответе вместе с предупреждением, что он общий.

• Ни того, ни другого

  Вы получаете ответ о том, что адреса отладки нет и почему, а не пустое поле.

Интерфейс это не чёрный ход. Профиль, созданный вызовом, проходит ту же проверку лицензии и нормы, что и созданный кнопкой в окне, и запустить его без лицензии не выйдет ни там, ни там.

Запуская сценарий, вы получите обратно номера профилей, которых программа не знает, а если в работу не взят ни один, это отказ, а не удача.

Токен выше ведёт одну установку на одном компьютере. Ключ сервера это другое: он говорит с нашим сервером откуда угодно и окна браузера не открывает никогда.

Ключ вы видите один раз, при создании, а у себя мы держим ровно столько, чтобы отличать ваши ключи друг от друга. Ключи входят в платные тарифы, живых можно держать 20, а смена тарифа доходит до ключа за минуту.

Вызов это наш сервер, который зовёт ваш, когда в вашем пространстве что-то произошло. Подписки заводит человек, вошедший паролем, а не ключ, и новая заводится только после повторного ввода пароля и числа второго шага, если он включён. Держать их можно до десяти.

Каждый вызов подписан, и поля с именами, похожими на доступы, до вашего приёмника не доезжают. Код приглашения или ссылка на смену пароля не уезжают на чужой сервер.

• Профили

  profile.create, profile.update, profile.delete, profile.start, profile.stop, profile.transfer.accept

• Прокси

  proxy.create, proxy.update, proxy.delete

• Ключи

  apikey.create, apikey.revoke

• Команда

  team.invite, team.remove

• Деньги

  plan.change

К неудачам доставка честна: три попытки, повтор при ошибке сервера, при отказе «слишком часто» и когда ответа не было вовсе, и последнее состояние вы видите на самой подписке. После пятнадцати неудач подряд подписка выключает сама себя.