Импорт cookies - новая функциональность в Browser API

30.09.2026

Рубен Эрера

Строю backend, IT-инфраструктуру и automation-сервисы для масштабируемых SaaS-продуктов.

Импорт cookies - новая функциональность в Browser API

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

Импорт cookies в профили Browser API позволяет повторно использовать уже авторизованные сессии, сохранять состояние браузера между запусками и продолжать автоматизацию без повторного входа и ручной настройки окружения.

Browser API теперь поддерживает импорт cookies. С помощью cookie import API можно заранее загрузить существующие cookies в нужный браузерный профиль, а уже после этого подключиться к нему. Полное описание параметров, поддерживаемых форматов и примеры запросов доступны в документации Browser API.

Новый cookie import API позволяет загрузить cookies непосредственно в профиль Browser API и использовать уже подготовленную сессию. После импорта cookies сохраняются для выбранного профиля и автоматически применяются при следующем подключении к нему через CDP.

Это позволяет переносить существующие сессии в Browser API, сохранять состояние между отдельными запусками автоматизации и заранее подготавливать профиль перед подключением Playwright, Puppeteer или другого CDP-клиента.

Запускайте автоматизацию без повторной подготовки сессии

Во многих сценариях браузер тратит ощутимую часть времени не на саму задачу, а на воссоздание уже существовавшего состояния.

Обычный запуск часто включает цепочку предварительных действий:

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

Если действующие cookies уже есть, повторять все эти шаги необязательно. С импортом cookies состояние браузера подготавливается отдельно, а новая сессия Browser API сразу стартует в готовом контексте.

flowchart TB subgraph Before["Без импорта cookies"] direction TB A1[Запуск браузера] A2[Авторизация] A3[Восстановление состояния сессии] A4[Переход на нужную страницу] A5[Запуск автоматизации] A1 --> A2 A2 --> A3 A3 --> A4 A4 --> A5 end subgraph After["С импортом cookies"] direction TB B1[Готовые cookies] B2[Импорт в профиль Browser API] B3[Подключение через CDP] B4[Автоматическое применение cookies] B5[Запуск автоматизации] B1 --> B2 B2 --> B3 B3 --> B4 B4 --> B5 end A5 ~~~ B1

В результате подготовку сессии не нужно выполнять внутри каждого запуска браузера. Нужное состояние создается один раз и повторно используется при последующих подключениях.

Где пригодится импорт cookies

Импорт cookies полезен в любых сценариях, где автоматизация должна начинаться не с чистого профиля, а с уже существующего состояния браузера.

Повторное использование авторизованных сессий

Импортируйте cookies активной сессии, чтобы сразу продолжить работу со страницами, доступными только после авторизации, не воспроизводя процесс входа заново.

Регулярная автоматизация

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

Перенос сессий между окружениями

Cookies, экспортированные из локального браузера, расширения или инструментов управления профилями, можно импортировать в Browser API и продолжить работу уже в облачном окружении.

Подготовка профиля до подключения

Поскольку импорт выполняется отдельным запросом, профиль Browser API можно наполнить нужными cookies еще до того, как Playwright, Puppeteer или другой CDP-клиент откроет соединение. Браузер сразу получит подготовленное состояние.

Раздельные состояния для разных профилей

Каждый профиль Browser API полностью изолирован и использует собственный набор cookies. Это позволяет параллельно вести автоматизацию для нескольких независимых окружений.

Как импортировать cookies в профиль Browser API

Для импорта отправьте POST-запрос на:

text Copy

https://cb-api.rucaptcha.com/cookies/import-cookies

В запросе нужно указать профиль Browser API и cookies, которые требуется загрузить.

Пример:

bash Copy

curl -X POST "https://cb-api.rucaptcha.com/cookies/import-cookies" \
  -H "Content-Type: application/json" \
  -d '{
    "login": "LOGIN",
    "password": "PASSWORD",
    "profileId": "PROFILE_ID",
    "cookies": [
      {
        "name": "session",
        "value": "abc",
        "domain": ".example.com",
        "path": "/",
        "secure": true,
        "httpOnly": true,
        "sameSite": "Lax",
        "expires": 1893456000
      }
    ]
  }'

Профиль можно указать двумя способами:

через login, password и profileId;
одной строкой connectionUri.

Эти способы нельзя смешивать. Если используются отдельные поля, необходимо передать все три значения: login, password и profileId.

Сами cookies можно передать:

как структурированные данные через cookies;
как текст экспорта через cookiesText.

При успешном импорте API возвращает информацию о профиле и количестве принятых cookies:

json Copy

{
  "cookiesStaged": 1,
  "customerId": "10001",
  "profileId": "PROFILE_ID"
}

Поле cookiesStaged показывает, сколько cookies было принято и подготовлено для профиля. Успешный ответ означает, что cookies поставлены в очередь, но в активную сессию браузера они попадут при подключении.

Когда импортированные cookies начинают работать

Cookie import API не изменяет уже открытую браузерную сессию.

После успешного запроса cookies подготавливаются для выбранного профиля и применяются автоматически только при следующем подключении к этому же профилю через CDP.

flowchart TB A[Существующие cookies] B[POST /import-cookies] C[Cookies подготовлены для профиля Browser API] D[Новое CDP-подключение к тому же профилю] E[Cookies применяются автоматически] F[Playwright / Puppeteer / CDP-клиент] G[Продолжение работы с импортированной сессией] A --> B B --> C C --> D D --> E E --> F F --> G

Если профиль уже используется другой активной сессией, API может вернуть ошибку profile_locked. В таком случае нужно завершить текущую сессию и повторить импорт после освобождения профиля.

Как переносить сессию между запусками

Один из практичных сценариев — сохранить состояние после первого запуска и использовать его в следующих.

flowchart TB A0["Первый запуск"] A1["Браузерная сессия"] A2["Сессия подготовлена"] A3["Cookies сохранены или экспортированы"] B0["Следующий запуск"] B1["Сохраненные cookies"] B2["Cookie import API"] B3["Профиль Browser API"] B4["Новое CDP-подключение"] B5["Предыдущее состояние сессии снова доступно"] A0 --> A1 A1 --> A2 A2 --> A3 A3 --> B0 B0 --> B1 B1 --> B2 B2 --> B3 B3 --> B4 B4 --> B5

Вместо того чтобы при каждом запуске заново авторизовываться и настраивать окружение, сессию можно подготовить заранее.

Такой подход также позволяет разделить получение сессии и основную автоматизацию. Например, один процесс получает и сохраняет cookies, а другие воркеры позже подключаются через Browser API и сразу приступают к выполнению задач.

Импорт cookies из других инструментов

Cookie import API поддерживает несколько распространенных форматов, поэтому существующие экспорты во многих случаях можно использовать без дополнительного преобразования:

Формат	Типичный источник
JSON-массив	CDP, собственный экспорт, подготовленный вручную JSON
`{"cookies": [...]}`	GoLogin, AdsPower, Dolphin, Octo
`{"data": [...]}`	AdsPower и похожие инструменты
Cookie-Editor / EditThisCookie	Расширения браузера
Netscape `cookies.txt`	Multilogin, Octo, GoLogin и другие инструменты экспорта

Формат автоматически определяется по переданным данным.

Даже если используется Netscape cookies.txt, сам HTTP-запрос остается JSON. Содержимое файла передается строкой в поле cookiesText:

json Copy

{
  "login": "LOGIN",
  "password": "PASSWORD",
  "profileId": "PROFILE_ID",
  "cookiesText": "# Netscape HTTP Cookie File\n.example.com\tTRUE\t/\tTRUE\t1893456000\tsession\tabc\n"
}

Это позволяет переносить cookies из существующих браузерных окружений и profile-management инструментов в Browser API без ручного создания каждого cookie-объекта.

Использование connectionUri вместо отдельных параметров

Если строка подключения к профилю Browser API уже есть в приложении, можно передать ее целиком через connectionUri. В этом случае отдельно передавать login, password и profileId не требуется:

json Copy

{
  "connectionUri": "ws://LOGIN-zone-scraping_browser-country-us-pid-PROFILE_ID:[email protected]:9222",
  "cookies": [
    {
      "name": "session",
      "value": "abc",
      "domain": ".example.com"
    }
  ]
}

Также поддерживается сокращенный вариант строки подключения без схемы и хоста. Такой способ удобен, если connectionUri уже используется в коде для подключения к Browser API и нет необходимости отдельно хранить параметры профиля.

Поля cookies и проверка данных

Каждый cookie должен содержать:

name;
value;
domain или url.

Дополнительно можно передать:

path;
secure;
httpOnly;
sameSite;
expires;
expirationDate;
session;
hostOnly;
sourcePort.

Для sameSite поддерживаются значения:

None;
Lax;
Strict.

Также можно использовать no_restriction — оно будет преобразовано в None.

Важно соблюдать типы данных. Например, boolean-поля должны передаваться как настоящие JSON-значения:

json Copy

{
  "secure": true,
  "httpOnly": false
}

а не как строки:

json Copy

{
  "secure": "true"
}

То же самое касается времени истечения cookies: timestamps должны передаваться числами.

Что важно учитывать

При работе с cookie import API есть несколько ключевых ограничений:

cookies применяются только при следующем CDP-подключении;
уже открытую браузерную сессию импорт не изменяет;
максимальный размер запроса — 8 MB;
два способа идентификации профиля нельзя использовать одновременно;
cookies должны соответствовать поддерживаемому формату и типам данных.

Если запрос не удалось обработать, API возвращает машиночитаемый код в поле error и при необходимости дополнительное описание в detail.

Среди возможных ошибок:

invalid_request;
invalid_json;
invalid_cookie;
auth_failed;
profile_locked;
ошибки работы с хранилищем.

Полный список ошибок и описание их причин доступны в документации cookie import API.

Cookie import API позволяет запускать автоматизацию Browser API уже с подготовленным состоянием браузера вместо того, чтобы заново создавать одну и ту же сессию при каждом запуске.

Рабочий процесс выглядит просто:

сохранить или экспортировать существующие cookies;
импортировать их в нужный профиль Browser API;
подключиться к этому профилю через CDP;
продолжить автоматизацию с подготовленным состоянием.

Так можно повторно использовать авторизованные сессии, переносить состояние между разными окружениями и упростить регулярные сценарии на Playwright, Puppeteer и других CDP-клиентах.

Импортируйте cookies, подключайтесь к нужному профилю и продолжайте автоматизацию с уже подготовленной сессией.

Browser API

Браузерные отпечатки

Unlocker APIСкоро

Scraper API

Web MCP

Browser MCP

Scraper MCP

Web Search MCP

Каталог программ

Блог

How-to

Демо капч

Selenium

Puppeteer

Playwright

Импорт cookies - новая функциональность в Browser API