# fill: заполнить поле

> POST /v1/browser/fill — ввести значение посимвольно и увидеть, что вправду оказалось в поле

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

Заполняет **одно** поле по его `ref`. Полей больше одного — берите
[form](https://docs.parreq.com/browser-form): он делает то же самое за один шаг и один кредит.

Что именно делать, решает вид поля (`field` в [списке
элементов](https://docs.parreq.com/browser-elements)): в строку и `textarea` вводится текст —
**посимвольно**, как с клавиатуры, а не вставкой целиком; в `select`
выбирается пункт по подписи; переключатель нажимается.

**Цена:** 1 кредит за действие.

## Запрос

```bash cURL
curl -X POST "https://api.parreq.com/v1/browser/fill" \
  -H "Authorization: Bearer pr_ВАШКЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "bs_9f2a41c7e8b0", "ref": "pq1-k3f9x", "value": "me@example.com"}'
```

```python Python
res = requests.post(
    "https://api.parreq.com/v1/browser/fill",
    headers={"Authorization": "Bearer pr_ВАШКЛЮЧ"},
    json={"session_id": session, "ref": "pq1-k3f9x", "value": "me@example.com"},
    timeout=180,
).json()

print("в поле оказалось:", res["filled"]["value"])
```

```javascript Node
const res = await fetch("https://api.parreq.com/v1/browser/fill", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_ВАШКЛЮЧ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session_id: session, ref: "pq1-k3f9x", value: "me@example.com",
  }),
}).then((r) => r.json());

console.log("в поле оказалось:", res.filled.value);
```

## Параметры

- **`session_id`** (`string`, обязательно, body):
  Идентификатор сессии из `open`.

- **`ref`** (`string`, обязательно, body):
  Ссылка на поле из последнего списка `elements`. У поля `kind` равен `field`.

- **`value`** (`string`, обязательно, body):
  Что ввести, что выбрать или чем переключить — по виду поля:

  | `field` | `value` |
  |---|---|
  | `text`, `tel`, `email`, `number`, `textarea` | текст |
  | `select` | подпись пункта: `"Самовывоз"` |
  | `radio`, `checkbox` | `да` — выбрать, `нет` — снять |

  Не длиннее 2000 знаков — иначе запрос отклоняется проверкой, ещё до похода в
  браузер.

- **`include`** (`string`, по умолчанию `buttons,fields`, body):
  Что вернуть после ввода. Те же значения, что и в `open`.

## Ответ

```json
{
  "filled": {"ref": "pq1-k3f9x", "typed": 14, "value": "me@example.com"},
  "settled": {"settled": true, "reason": "страница догрузилась…"},
  "credits": 1
}
```

- **`filled.typed`** (`integer`):
  Сколько знаков отправлено в поле.

- **`filled.value`** (`string`):
  Что в поле оказалось **на самом деле**. Может отличаться от отправленного:
  маска ввода, `maxlength` или обработчик на странице могли его изменить.
  Сверяйте — по этому полю видно, приняла форма ввод или переписала его
  по-своему.

- **`settled`** (`object`):
  Догрузилась ли страница после ввода. Многие формы проверяют поле на лету и
  дорисовывают подсказку — это тоже изменение страницы.

## Почему посимвольно

> **Внимание.**
>   Вставка отличается от живого ввода тем, что поле получает одно событие вместо
>   потока нажатий. Защита это видит и отличает автоматизацию от человека именно
>   по такому следу.
>
>   Отсюда следствие: **длинное значение занимает время**. Символы идут с
>   разбросом задержки 10–30 мс, то есть сотня символов — около двух секунд.

Вставки целиком в API нет намеренно. Если бы она была, ей пользовались бы по
умолчанию — и упирались бы в проверку на тех самых сайтах, ради которых Browser
API и нужен.

## Заполнение формы целиком

Отдельными вызовами `fill` анкета из шести полей — это шесть обращений, шесть
ответов со всей страницей и пять пауз между ними. Для этого есть
[form](https://docs.parreq.com/browser-form): поля идут подряд, по порядку, страница собирается один
раз, и кнопка отправки нажимается тем же шагом.

```python
res = form(session, [
    {"ref": fio_ref,   "value": "Иван Петров"},
    {"ref": phone_ref, "value": "+375290001100"},
    {"ref": pickup_ref, "value": "да"},          # переключатель
    {"ref": city_ref,  "value": "Минск"},        # список
], submit=submit_ref)
```

Берите `ref` кнопки отправки из **последнего** ответа: пока вы заполняли поля,
форма могла перерисоваться и разблокировать её.

## Частые отказы

| Код | Что делать |
|---|---|
| `element_not_found` | Поле исчезло после перерисовки — возьмите свежий `elements` |
| `element_disabled` | Поле отключено: скорее всего, ждёт заполнения другого |
| `option_not_found` | В списке нет такого пункта; доступные перечислены в сообщении |
| `session_not_found` | Сессия закрылась — откройте новую |

Полный список — на странице [Ошибки](https://docs.parreq.com/browser-errors).