form: заполнить анкету

Заполняет несколько полей за одно обращение и, если попросить, нажимает кнопку отправки тем же шагом. Цена: 1 кредит за шаг — независимо от того, сколько в нём полей. Работа тут одна: страница собирается один раз, в конце.

Зачем отдельная ручка

Анкета заказа в интернет-магазине — это имя, почта, телефон, город, способ доставки, способ оплаты, примечание и две галочки согласия. Отдельными вызовами fill это девять обращений, девять ответов со всей страницей и восемь пауз между ними, каждая из которых приближает сессию к закрытию по простою. Здесь поля идут подряд, по порядку списка. Порядок соблюдается намеренно: витрины пересчитывают одно поле по другому, и «город» перед «улицей» — не прихоть, а условие того, что улица вообще появится.

Запрос

curl -X POST "https://api.parreq.com/v1/browser/form" \
  -H "Authorization: Bearer pr_ВАШКЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
        "session_id": "bs_9f2a41c7e8b0",
        "fields": [
          {"ref": "pq3-a1b2c", "value": "Иван Петров"},
          {"ref": "pq4-d3e4f", "value": "+375290001100"},
          {"ref": "pq7-g5h6i", "value": "Самовывоз"},
          {"ref": "pq9-j7k8l", "value": "да"}
        ],
        "submit": "pq12-m9n0o"
      }'

res = requests.post(
    "https://api.parreq.com/v1/browser/form",
    headers={"Authorization": "Bearer pr_ВАШКЛЮЧ"},
    json={
        "session_id": session,
        "fields": [
            {"ref": fio,   "value": "Иван Петров"},
            {"ref": phone, "value": "+375290001100"},
            {"ref": pickup, "value": "да"},
            {"ref": offer, "value": "да"},
        ],
        "submit": order_button,
    },
    timeout=180,
).json()

for row in res["filled"]:
    print(row["ref"], "→", row.get("got", row.get("error")))

const res = await fetch("https://api.parreq.com/v1/browser/form", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_ВАШКЛЮЧ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session_id: session,
    fields: [
      { ref: fio, value: "Иван Петров" },
      { ref: phone, value: "+375290001100" },
      { ref: pickup, value: "да" },
    ],
    submit: orderButton,
  }),
}).then((r) => r.json());

Параметры

string

required

Идентификатор сессии из open.

array

required

Поля анкеты по порядку. Каждое — объект с ref и value. От одного до шестидесяти.

string

Ссылка на кнопку, которую нажать после заполнения. Пусто — анкета останется заполненной, но не отправленной.

string

default:"buttons,fields"

Что вернуть после заполнения. Те же значения, что и в open.

Что означает `value`

Зависит от того, что за поле — смотрите field в списке элементов.

`field`	Что писать в `value`
`text`, `tel`, `email`, `password`, `number`, `textarea`	текст; вводится посимвольно
`select`	подпись пункта: `"Самовывоз"`. Совпадение сперва точное, потом по вхождению
`radio`, `checkbox`	`да` — выбрать, `нет` — снять

Радиокнопку снять нельзя: её отменяет только выбор соседней в той же группе. На нет она честно останется выбранной, и это будет видно в got — вместо того, чтобы сделать вид, что сняли.Уже выбранный переключатель повторным да не трогается. Иначе анкета, заполненная дважды, оказалась бы пустой.

Ответ

{
  "filled": [
    {"ref": "pq3-a1b2c", "value": "Иван Петров", "typed": 11, "got": "Иван Петров"},
    {"ref": "pq4-d3e4f", "value": "+375290001100", "typed": 13, "got": "+375 (29) 000-11-00"},
    {"ref": "pq7-g5h6i", "value": "да", "typed": 0, "got": "да"},
    {"ref": "pq8-x0y1z", "value": "мимо", "error": "поля pq8-x0y1z нет на странице…"}
  ],
  "submitted": "pq12-m9n0o",
  "settled": {"settled": true, "reason": "страница догрузилась…"},
  "credits": 1
}

string

Что оказалось в поле на самом деле. Сверяйте с value: маска ввода, maxlength и обработчик на странице могли его переписать. В примере выше телефон уехал в поле цифрами, а вернулся в маске — это нормально, и агент должен видеть именно возвращённое.

integer

Сколько знаков набрано. У списка и переключателя — ноль: вводом там дело не решается.

string

Почему поле не заполнилось. Промах по одному полю не отменяет остальных: анкета, заполненная на пять шестых, полезнее пустой, а какое поле не легло — видно здесь.

string

Какая кнопка нажата. Приходит, только если submit был задан и нажатие прошло; иначе на её месте submit_error.

Оформление заказа целиком

Живой пример: один дешёвый товар, самовывоз, оплата при получении.

# 1. Товар в корзину
page = browser_open("https://shop.example/catalog/lenta/")
to_cart = ref_of(page, "В корзину")
browser_click(session, to_cart)

# 2. К оформлению
page = browser_open("https://shop.example/order/")

# 3. Покупатель — одним шагом, и сразу «Продолжить»
page = browser_form(session, [
    {"ref": ref_of(page, "Ф.И.О."),   "value": "Иван Петров"},
    {"ref": ref_of(page, "E-Mail"),   "value": "[email protected]"},
    {"ref": ref_of(page, "Телефон"),  "value": "+375290001100"},
    {"ref": ref_of(page, "Продолжая, вы соглашаетесь с публичной офертой"),
     "value": "да"},
], submit=ref_of(page, "Продолжить"))

# 4. Способы доставки и оплаты появляются только после шага «Покупатель»
page = browser_click(session, ref_of(page, "Изменить"))

# 5. Самовывоз, оплата при получении, примечание — и отправка
page = browser_form(session, [
    {"ref": ref_of(page, "Самовывоз"),          "value": "да"},
    {"ref": ref_of(page, "Наличными, картой"),  "value": "да"},
    {"ref": ref_of(page, "Комментарии к заказу:"), "value": "самовывоз со склада"},
], submit=ref_of(page, "Оформить заказ"))

Разделы анкеты открываются по очереди: способы доставки и оплаты на витринах Битрикса появляются в разметке только после того, как заполнен покупатель. Поэтому шагов два, а не один, и ref для второго берутся из ответа первого — ссылки предыдущего списка после перерисовки уже не действуют.

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

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

Отказ по одному полю приходит в его строке filled[].error и шаг не отменяет. Отказ по сессии — общий, и тогда filled не приходит вовсе.

Дальше

Элементы и ссылки

Что такое field, group, checked и options.

fill

Одно поле, когда оно и вправду одно.

Начало

Search

Fetch

Browser API

Crawler

Агенты и MCP

Библиотеки

Как это работает

form: заполнить анкету

Зачем отдельная ручка

Запрос

Параметры

Что означает `value`

Ответ

Оформление заказа целиком

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

Дальше

Элементы и ссылки

fill

​Зачем отдельная ручка

​Запрос

​Параметры

​Что означает value

​Ответ

​Оформление заказа целиком

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

​Дальше

Элементы и ссылки

fill

Зачем отдельная ручка

Запрос

Параметры

Что означает `value`

Ответ

Оформление заказа целиком

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

Дальше