# open: открыть страницу

> POST /v1/browser/open — завести сессию вокруг страницы и получить список элементов

Источник: https://docs.parreq.com/browser-open/

Первый вызов в любой работе с Browser API. Открывает страницу в живой вкладке,
заводит сессию и возвращает её идентификатор вместе с тем, что заказано в
`include`.

Что при этом происходит внутри — на странице [Инициализация](https://docs.parreq.com/browser-init).

**Цена:** 3 кредита. Надстройка `html` считается отдельно, по прайсу Fetch.

## Запрос

```bash cURL
curl -X POST "https://api.parreq.com/v1/browser/open" \
  -H "Authorization: Bearer pr_ВАШКЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "include": "buttons,fields"}'
```

```python Python

res = requests.post(
    "https://api.parreq.com/v1/browser/open",
    headers={"Authorization": "Bearer pr_ВАШКЛЮЧ"},
    json={"url": "https://example.com", "include": "buttons,fields"},
    timeout=180,
).json()

session = res["session_id"]
for el in res["elements"]:
    print(el["ref"], el["kind"], el["text"])
```

```javascript Node
const res = await fetch("https://api.parreq.com/v1/browser/open", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_ВАШКЛЮЧ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com", include: "buttons,fields" }),
}).then((r) => r.json());

const session = res.session_id;
res.elements.forEach((el) => console.log(el.ref, el.kind, el.text));
```

## Параметры

- **`url`** (`string`, обязательно, body):
  Адрес страницы. Должен начинаться с `http://` или `https://` — иначе приходит
  `invalid_request` с кодом 400, ещё до похода в браузер.

- **`include`** (`string`, по умолчанию `buttons,fields`, body):
  Что вернуть, через запятую: `buttons`, `fields`, `text`, `html`. Неизвестные
  значения молча отбрасываются. Подробно — в разделе
  [Элементы и ссылки](https://docs.parreq.com/browser-elements).

- **`wait_ms`** (`integer`, body):
  Потолок ожидания догрузки, в миллисекундах, до 60000. По умолчанию — общий
  потолок службы. Поднимать его стоит там, где содержимое приезжает сторонним
  виджетом и стандартного ожидания ему не хватает. Помните, что сессия живёт 120
  секунд всего: ожидание тратит её же.

- **`wait_for`** (`string`, body):
  CSS-селектор блока, которого ждём, — вместо общей тишины на странице. Удобно,
  когда точно известно, что должно появиться: форма записи, карточка товара,
  таблица. Не появился за отведённое время — об этом прямо сказано в `reason`, а
  собранное всё равно придёт.

- **`device`** (`string`, по умолчанию `desktop`, body):
  `desktop` или `mobile`. Меняет размер экрана и User-Agent: мобильная вёрстка у
  многих сайтов отличается не только видом, но и составом кнопок.

- **`gl`** (`string`, по умолчанию `us`, body):
  Страна выхода. От неё зависит, через какой адрес пойдёт браузер.

- **`hl`** (`string`, по умолчанию `en`, body):
  Язык интерфейса страницы: заголовок `Accept-Language` и язык браузера.

## Ответ

```json
{
  "session_id": "bs_9f2a41c7e8b0",
  "url": "https://example.com/",
  "device": "desktop",
  "steps": 1,
  "idle_left": 60,
  "life_left": 118,
  "settled": {
    "settled": true,
    "reason": "страница догрузилась: 428 узлов, 12 сетевых записей, 61 изменение DOM",
    "ms": 940
  },
  "elements": [
    {"ref": "pq1-k3f9x", "kind": "field", "tag": "input", "type": "email",
     "name": "email", "text": "Почта", "value": "", "required": true},
    {"ref": "pq2-m8p2q", "kind": "button", "tag": "button", "text": "Войти"}
  ],
  "elements_count": 2,
  "credits": 3
}
```

- **`session_id`** (`string`):
  Идентификатор сессии. Нужен во всех последующих вызовах. Сохраните его сразу:
  другого способа вернуться к этой вкладке нет.

- **`url`** (`string`):
  Адрес после всех переадресаций. Сравните с тем, что просили, если важно знать,
  что вас увели.

- **`device`** (`string`):
  Устройство, которое в итоге эмулируется.

- **`steps`** (`integer`):
  Сколько шагов сделано в этой сессии. После `open` — единица.

- **`idle_left`** (`integer`):
  Секунд простоя до закрытия. Обнуляется каждым новым шагом.

- **`life_left`** (`integer`):
  Секунд до общего потолка жизни сессии. Не обнуляется ничем — см.
  [Сроки жизни](https://docs.parreq.com/browser-lifetime).

- **`settled`** (`object`):
  Чем кончилось ожидание догрузки. Разбор — на странице
  [Догрузка страницы](https://docs.parreq.com/browser-settled).

- **`elements`** (`array`):
  Кнопки и поля со ссылками `ref`. Приходит, если в `include` заказаны `buttons`
  или `fields`.

- **`elements_count`** (`integer`):
  Сколько элементов в списке. Удобно проверять, не пуст ли он, не разбирая
  массив.

- **`credits`** (`integer`):
  Сколько списано за этот вызов.

> **Внимание.**
>   Если `open` ответил ошибкой, сессии не осталось: она закрывается на месте, и
>   закрывать её вам нечем — идентификатора в отказе нет. Просто повторите
>   вызов.

## Дальше

**[Элементы и ссылки](https://docs.parreq.com/browser-elements)**
    Что пришло в `elements` и как этим пользоваться.

**[click](https://docs.parreq.com/browser-click)**
    Первое действие в открытой сессии.