Типы форм

Каждый эндпоинт сообщает витрине, какие данные он принимает. Такое описание называется формой. Оно приходит в ответе загрузки приложения (POST /api/appload) рядом с адресом и HTTP-методом эндпоинта. По нему видно, какие поля показать покупателю и как передать их значения в теле запроса.

Тип формы определяет вид тела запроса. Кратко:

В загрузке приложения	Что отправлять
`form_type: "filters"`	Условия поиска или отбора внутри объекта `filters`.
`form_type: "form"`	Сами поля в корне JSON-тела.
`form_type: "step"`	Имя текущего шага `step` и поля этого шага. Каждый ответ сообщает, какой шаг следующий.
`forms: []`	То, что описано на странице самого эндпоинта; часто пустой JSON-объект.

Формы в ответе загрузки приложения

Загрузка приложения перечисляет все эндпоинты, доступные текущему посетителю. В page_data.unauth.paths — эндпоинты, работающие без входа, в page_data.auth.paths — эндпоинты для вошедшего покупателя. Внутри они сгруппированы по разделам (например, address_hints), а затем по маршрутам. У каждой записи эндпоинта есть такие ключи:

url_name: Постоянное имя эндпоинта. По нему ищется запись.
target: Адрес, на который отправляется запрос.
methods: HTTP-метод запроса.
forms: Описание данных, которые принимает эндпоинт. Пустой массив означает, что формы нет.

Тип формы говорит только о том, как собрать тело запроса. Адрес, метод и необходимость входа он не определяет: их берут из target, methods и из списка, в котором находится эндпоинт.

Поиск эндпоинта по url_name и отправка запроса

Пример: форма подсказок городов

Эндпоинт address_hints_suggest_city подсказывает города, пока покупатель вводит адрес. Он требует входа, поэтому его запись находится в page_data.auth.paths. Его форма лежит по этому пути в ответе загрузки приложения:

page_data.auth.paths.address_hints["/suggest_city"].forms[0]

page_data.auth.paths: эндпоинты, доступные вошедшему покупателю
address_hints: раздел, к которому относится эндпоинт
["/suggest_city"]: маршрут эндпоинта внутри раздела
forms[0]: первая форма эндпоинта (у этого эндпоинта она одна)

Каждая строка ниже — одно свойство этой формы с реальным значением. Раскройте form_data или sub_filters_dict, чтобы увидеть и скопировать объект целиком.

Свойство	Назначение	Значение
`forms[]` Формы эндпоинта. Обычно одна; пустой массив означает, что формы нет.
`forms[].name`	Внутреннее имя формы. Оно нужно для загрузки вариантов полей (см. «Связанные поля» ниже); с основным запросом не отправляется.	`"fCitySuggestion"`
`forms[].form_type`	Как собрать тело запроса: `filters`, `form` или `step`. Каждому типу посвящён раздел ниже.	`"form"`
`forms[].form_data`	Поля ввода; ключ — имя, под которым поле отправляется. У поля есть `label`, `required`, `input_type` (text, select и т. д.), а у списков выбора — `options`. В пошаговой форме поля сначала сгруппированы по шагам: `form_data.step_phone.phone`.
`forms[].sub_filters_dict`	Дополнительные фильтры для полей, варианты которых загружаются отдельно; ключ — имя поля. Здесь варианты `region` можно сузить по стране, названию региона и порядку сортировки. Они фильтруют список вариантов и не отправляются с основным запросом.

Как читать поле и фильтр

Поле из form_data. search_string — обязательное текстовое поле с подписью «City Search String». В запросе отправляется только введённый покупателем текст под ключом search_string.

Путь внутри записи эндпоинта: forms[0].form_data.search_string

{
  "form_class": "CharField",
  "label": "City Search String",
  "required": true,
  "input_type": "text",
  "attrs": {}
}

Фильтр из sub_filters_dict. ordering сортирует варианты региона. У каждого варианта есть key — подпись для показа («Id»), и value — то, что отправляется ("id"). path: "region" означает, что фильтр относится к полю region.

Путь внутри записи эндпоинта: forms[0].sub_filters_dict.region.ordering

{
  "form_class": "ChoiceExactField",
  "label": "Порядок",
  "required": false,
  "input_type": "select",
  "attrs": {},
  "options": [
    {
      "key": "Id",
      "value": "id"
    },
    {
      "key": "Id (по убыванию)",
      "value": "-id"
    }
  ],
  "path": "region"
}

Не каждая форма описывает все поля в form_data, а некоторым эндпоинтам нужны ещё параметры в адресе или вложенные объекты. В спорных случаях ориентируйтесь на страницу самого эндпоинта. В разделах ниже каждый тип формы показан на сокращённой записи из загрузки приложения (без описаний полей) рядом с подходящим телом запроса.

Фильтры — filters

Используется эндпоинтами поиска и списков. Условия отбора передаются внутри объекта filters. Если эндпоинт поддерживает страницы, их параметры передаются в отдельном объекте paginate рядом с filters.

Пример эндпоинта: Поиск регионов address_hints_region_search
В загрузке приложения: page_data.auth.paths.address_hints["/region/search"]

{
  "url_name": "address_hints_region_search",
  "target": "api/address/hints/region/search",
  "methods": [
    "POST"
  ],
  "forms": [
    {
      "name": "ffCountryRegions",
      "form_type": "filters"
    }
  ]
}

{
  "filters": {
    "region_name": "Moscow",
    "ordering": "id"
  }
}

Этот запрос ищет регионы, в названии которых есть «Moscow», и сортирует их по ID. Пустой объект filters возвращает все регионы. Этот эндпоинт возвращает один список без страниц, поэтому paginate нет: тип filters сам по себе пагинацию не включает.

Обычная форма — form

Используется эндпоинтами, выполняющими одно действие. Поля передаются прямо в корне JSON-тела под именами из form_data.

Пример эндпоинта: Адрес по координатам address_hints_suggest_location
В загрузке приложения: page_data.auth.paths.address_hints["/suggest_location"]

{
  "url_name": "address_hints_suggest_location",
  "target": "api/address/hints/suggest_location",
  "methods": [
    "POST"
  ],
  "forms": [
    {
      "name": "fGeoSuggestions",
      "form_type": "form"
    }
  ]
}

{
  "longitude": 37.6173,
  "latitude": 55.7558
}

address_hints_suggest_location требует числовые longitude и latitude и возвращает адресные подсказки для этой точки. Если одного из них нет, ответ содержит ошибку этого поля.

Пошаговая форма — step

Используется процессами из нескольких экранов, например входом. Каждый запрос передаёт имя текущего шага step и поля этого шага — всё в корне. В form_data поля сгруппированы по шагам (forms[].form_data.step_phone.phone), а тело плоское: step: "step_phone" и phone.

Пример эндпоинта: Вход и регистрация auth_signin_signup
В загрузке приложения: page_data.unauth.paths.auth["/signin_signup"]

{
  "url_name": "auth_signin_signup",
  "target": "api/accounts/auth/signin_signup",
  "methods": [
    "POST"
  ],
  "forms": [
    {
      "name": "fSignInUpSet",
      "form_type": "step"
    }
  ]
}

{
  "step": "step_phone",
  "phone": "+12025550123"
}

Начните auth_signin_signup с step_phone. Каждый ответ возвращает page_data.next_step: покажите поля этого шага и отправьте их в той же браузерной сессии, пока процесс не завершится. Все шаги описаны на странице входа.

Без формы

forms: [] означает, что у эндпоинта нет формы. Что отправлять, описано на странице самого эндпоинта.

Пример эндпоинта: Дерево публичных категорий catalog_load
В загрузке приложения: page_data.unauth.paths.catalog["/get"]

{
  "url_name": "catalog_load",
  "target": "api/catalog/get",
  "methods": [
    "POST"
  ],
  "forms": []
}

{}

catalog_load не требует входных данных: отправьте пустой JSON-объект {} и получите общедоступный каталог.

Отсутствие формы не всегда означает отсутствие входных данных. У products_view_feedbacks_stats_get тоже forms: [], но ему нужен feedback_id в адресе. Подставьте его в target, а не в тело запроса.

Статистика отзыва: параметр feedback_id

Связанные поля и загрузка вариантов

Некоторые поля — списки выбора, которые заполняет бэкенд, например страна и регион в форме адреса. У каждого варианта есть key — подпись для показа, и value — то, что отправляется. Если options поля в form_data заполнены, используйте их. Если они пустые, как у region в форме подсказок городов, загрузите их этим запросом, передав имя формы-владельца, field_name и фильтры, описанные в sub_filters_dict. Вспомогательный эндпоинт может использовать варианты другой формы.

PATCH /api/reload_customer_app

При смене родительского выбора (другая страна) очистите зависимый выбор (регион) и загрузите его список заново с новым фильтром. Показывайте загрузку, пустой список и ошибки. Если старый ответ пришёл после нового выбора, игнорируйте его. Загрузка вариантов — отдельный запрос, он не отправляет основную форму.

Загрузка вариантов тоже проверяет права. Запросы адресных подсказок требуют входа, а списки стран и регионов формы адреса — активного аккаунта покупателя. Принимаются только зарегистрированные пары формы и поля; наличие формы в загрузке приложения само по себе доступа не даёт.

Поля запроса подсказок адреса

Проверка данных и ошибки

Каждый тип формы сообщает об ошибках по-своему. В любом случае у эндпоинта могут быть собственные проверки — смотрите его страницу.

Тип формы	Как приходят ошибки
`form_type: "filters"`	На эндпоинтах витрины (клиентских) значение фильтра, которое нельзя применить, например неверного типа, с неизвестным ID или с неподдерживаемой сортировкой, возвращает ошибку поля под именем этого фильтра вместо списка без фильтрации. Эндпоинты панелей пропускают такое значение и применяют остальные фильтры. У методов также могут быть собственные проверки и общие ошибки; filters не означает, что ошибок не бывает.
`form_type: "form"`	Обычная форма проверяет обязательные поля, типы и ограничения до выполнения действия. В примере поиска по координатам пустое тело вызывает ошибки latitude и longitude. Бэкенд возвращает их в `form_errors`, а не выполняет запрос с пропущенными обязательными полями. Пропущенное или пустое обязательное поле также добавляет общую ошибку «Заполните все обязательные поля.» в `__all__`. Обязательное поле только с некорректным значением, например с неизвестным вариантом или слишком длинным значением, возвращает лишь собственную ошибку поля.
`form_type: "step"`	Обработчик проверяет поля переданного шага и сохранённое состояние процесса. Корректное значение поля не позволяет пропустить обязательный предыдущий шаг. Вместе с ошибками может прийти `page_data.next_step` для возврата к другому экрану; обрабатывайте оба поля, а не оставляйте форму на текущем шаге при любой ошибке.
`forms: []`	Отсутствие формы не отключает проверки метода: параметры пути, права доступа и состояние данных по-прежнему могут привести к ошибке.

HTTP 200 сам по себе не подтверждает успех: учитывайте success_message и form_errors. Формат ошибок полей, общие ошибки __all__, HTTP-ошибки, ответы не в формате JSON и сетевые сбои описаны в общей справке.

Успех и ошибки