Form types

Every endpoint tells your storefront what data it accepts. This description is called a form. It comes in the Application Load response (POST /api/appload) next to the endpoint’s URL and HTTP method. Read it to know which inputs to show the customer and how to put their values into the request body.

The form type decides the shape of the request body. In short:

In Application Load	What you send
`form_type: "filters"`	Search or list criteria, wrapped in a `filters` object.
`form_type: "form"`	The fields themselves, at the top level of the JSON body.
`form_type: "step"`	The name of the current `step` and that step’s fields. Each response tells you which step comes next.
`forms: []`	Whatever the endpoint’s own page describes; often an empty JSON object.

Forms in Application Load

Application Load lists every endpoint the current visitor can call. page_data.unauth.paths holds the endpoints that work without signing in, page_data.auth.paths the ones for a signed-in customer. Inside, endpoints are grouped by area (for example address_hints) and then by route. Every endpoint record has these keys:

url_name: The endpoint’s stable name. Use it to find the record.
target: The URL to send the request to.
methods: The HTTP method to use.
forms: The description of the data the endpoint accepts. An empty array means the endpoint has no form.

The form type only tells you how to shape the body. It does not decide the URL, the method or whether sign-in is needed: take those from target, methods and the list the endpoint is in.

Finding an endpoint by url_name and sending a request

Example: the city suggestion form

The address_hints_suggest_city endpoint suggests cities while a customer types an address. It needs a signed-in customer, so its record is in page_data.auth.paths. Its form sits at this path of the Application Load response:

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

page_data.auth.paths: endpoints available to a signed-in customer
address_hints: the area the endpoint belongs to
["/suggest_city"]: the endpoint’s route inside that area
forms[0]: the endpoint’s first form (this endpoint has only one)

Each row below is one property of that form, with its real value. Expand form_data or sub_filters_dict to see the whole object and copy it.

Property	Purpose	Value
`forms[]` The endpoint’s forms. Usually there is one; an empty array means the endpoint has no form.
`forms[].name`	The form’s internal name. You need it to load field choices (see “Connected fields” below); it is not sent with the main request.	`"fCitySuggestion"`
`forms[].form_type`	How to build the request body: `filters`, `form` or `step`. Each type has its own section below.	`"form"`
`forms[].form_data`	The input fields, keyed by the name you send. Each field has a `label`, `required`, an `input_type` (text, select and so on) and, for choice lists, `options`. In a step form the fields are grouped by step first: `form_data.step_phone.phone`.
`forms[].sub_filters_dict`	Extra filters for fields whose choices are loaded separately, keyed by field name. Here the `region` choices can be narrowed by country, region name and sort order. They filter the choice list; they are not sent with the main request.

Reading one field and one filter

A field from form_data. search_string is a required text input labelled “City Search String”. In the request you send just the text the customer typed, under the key search_string.

Path inside the endpoint record: forms[0].form_data.search_string

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

A filter from sub_filters_dict. ordering sorts the region choices. Each option has a key, the label to show (“Id”), and a value, the thing to send ("id"). path: "region" means this filter belongs to the region field.

Path inside the endpoint record: 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"
}

Not every form describes all its fields in form_data, and some endpoints also need URL parameters or nested objects. When in doubt, the endpoint’s own page is the reference. The sections below show each form type with a shortened Application Load record (field descriptions left out) next to a matching request body.

Filters — filters

Used by endpoints that search or list things. Put the criteria inside a filters object. If the endpoint supports pages, the page settings go in a separate paginate object next to filters.

Example endpoint: Search regions address_hints_region_search
In Application Load: 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"
  }
}

This request finds regions whose name contains “Moscow” and sorts them by ID. Send an empty filters object to get all regions. This endpoint returns one list without pages, so there is no paginate: the filters type does not turn on pagination by itself.

Regular form — form

Used by endpoints that perform one action. Send the fields directly at the top level of the JSON body, under the names used in form_data.

Example endpoint: Find an address by coordinates address_hints_suggest_location
In Application Load: 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 needs both longitude and latitude as numbers and returns address suggestions for that point. If one of them is missing, the response contains an error for that field.

Step form — step

Used by flows that take several screens, such as signing in. Each request sends the name of the current step plus that step’s fields, all at the top level. In form_data the fields are grouped by step (forms[].form_data.step_phone.phone), but the body is flat: step: "step_phone" and phone.

Example endpoint: Sign in or register auth_signin_signup
In Application Load: 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"
}

Start auth_signin_signup with step_phone. Each response returns page_data.next_step: show that step’s fields and send them in the same browser session, until the flow ends. The sign-in page describes every step.

No form

forms: [] means the endpoint has no form. What to send is described on the endpoint’s own page.

Example endpoint: Public category tree catalog_load
In Application Load: page_data.unauth.paths.catalog["/get"]

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

{}

catalog_load needs no input: send an empty JSON object {} and you get the public catalog.

No form does not always mean no input. products_view_feedbacks_stats_get also has forms: [], but needs feedback_id inside the URL. Put it into target, not into the body.

Feedback statistics: the feedback_id parameter

Connected fields and option reloading

Some fields are choice lists filled by the backend, such as country and region in an address form. Each choice has a key, the label to show, and a value, the thing to send. If the field’s options in form_data are filled, use them. If they are empty, as for region in the city suggestion form, load them with this request, passing the owning form’s name, the field_name and the filters described in sub_filters_dict. A helper endpoint may use the choices of another form.

PATCH /api/reload_customer_app

When the parent choice changes (another country), clear the child choice (region) and load its list again with the new filter. Show the loading state, an empty list and errors. If an older response arrives after a newer selection, ignore it. Loading choices is a separate request; it does not submit the main form.

Choice loading checks permissions too. Address hint requests need a signed-in session, and the country and region lists of the address form need an active customer account. Only registered form and field pairs are accepted; finding a form in Application Load does not by itself give access.

Address suggestion request fields

Validation and errors

Each form type reports problems in its own way. In every case the endpoint may have its own checks as well, so read its page.

Form type	How problems come back
`form_type: "filters"`	On storefront (customer) endpoints a filter value that cannot be used, such as a wrong type, an unknown ID or an unsupported ordering, returns a field error under that filter’s name instead of an unfiltered list. Panel endpoints skip such a value and apply the other filters. Methods can also have their own checks and general errors; filters does not mean errors are impossible.
`form_type: "form"`	A regular form validates required fields, types and constraints before running the action. In the coordinate lookup example, an empty body produces latitude and longitude errors. The backend returns them in `form_errors` instead of processing a request with missing required fields. A missing or empty required field also adds the general error «Please enter all required fields.» in `__all__`. A required field that only has an invalid value, such as an unknown choice or a value that is too long, returns just its own field error.
`form_type: "step"`	The handler validates the submitted step’s fields and the saved flow state. A valid field value cannot skip a required earlier step. Errors can include `page_data.next_step` to return to another screen; handle both instead of treating every error as a request to stay on the same step.
`forms: []`	No form does not disable the method’s checks: path parameters, permissions and data state can still cause errors.

HTTP 200 alone does not confirm success: also check success_message and form_errors. The common reference covers field-error arrays, general __all__ errors, HTTP errors, non-JSON responses and network failures.

Success and errors