# FlexField. Гибкие поля

> Источник: https://wiki.virtualpos.ru/hc/api/flexfield  
> Обновлено: 2026-09-26  
> Где в программе: Настройки → Гибкие поля

Гибкие поля добавляют дополнительные колонки к справочникам и документам системы: клиентам, товарам, точкам продаж, поступлениям и другим. Методы раздела позволяют получить список настроенных гибких полей, создать новое поле, изменить или удалить его.

> **Примечание:**
> Как получить ключ, как формируются запросы и какие бывают ответы и ошибки — в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Здесь описаны только особенности методов раздела `flexField`.

## Что такое гибкие поля

Допустим, вы продаёте одежду и настроили для справочника «Клиенты» поле «Размер». Тогда у каждого клиента можно указать размер одежды: в карточке клиента в панели управления или через API. Настроенные гибкие поля видны в панели управления в разделе **Настройки → Гибкие поля**.

Как записать значение поля через API, описано ниже, в разделе «Как задать значение гибкого поля в записи».

## Методы

| Метод | Адрес | Что делает |
| --- | --- | --- |
| Список справочников | `/api/flexField/listTables` | Возвращает справочники, для которых можно настраивать гибкие поля |
| Получить поля | `/api/flexField` | Возвращает настроенные гибкие поля |
| Создать или изменить поле | `/api/flexField/update` | Обновляет гибкое поле или создаёт новое |
| Удалить поле | `/api/flexField/delete` | Удаляет гибкое поле |

> **Важно:**
> **Где передавать параметры.** Ключ `apikey` и формат `format` принимаются и в адресной строке, и в теле POST-запроса. Параметры, по которым ищется поле — `id`, `table_name`, `name` и `create_if_not_exist` — читаются **только из адресной строки (GET)**. Остальные параметры поля (`attr_type`, `enabled`, `default_value`, `list_values`, `attr_num`) можно передавать и в адресной строке, и в теле POST.
>
> Значения с пробелами и кириллицей кодируйте: например, поле «Размер» в адресе записывается как `name=%D0%A0%D0%B0%D0%B7%D0%BC%D0%B5%D1%80`.

## Справочники

Метод `listTables` возвращает справочники, поддерживающие гибкие поля. Код справочника указывается в параметре `table_name` других методов.

```
GET https://[компания].myvirtualpos.ru/api/flexField/listTables?apikey=MySecret
```

- **success** — `1` — данные получены
- **type** — Тип данных, в ответе всегда `frexfield.tables` (написание сохранено для совместимости)
- **count** — Количество справочников
- **tables** — Список справочников. Каждый обёрнут в объект `table` с полями `name` (код справочника) и `description` (название)

```json
{
  "success": 1,
  "type": "frexfield.tables",
  "count": 25,
  "tables": [
    { "table": { "name": "warehouse", "description": "Точка продаж" } },
    { "table": { "name": "location", "description": "Территория" } }
  ]
}
```

Тот же ответ при `format=xml` (сокращённо):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <success>1</success>
  <type>frexfield.tables</type>
  <count>25</count>
  <tables>
    <table><name>warehouse</name><description>Точка продаж</description></table>
    <table><name>location</name><description>Территория</description></table>
  </tables>
</root>
```

Полный список кодов:

| Код | Справочник | Код | Справочник |
| --- | --- | --- | --- |
| `warehouse` | Точка продаж | `customer` | Клиент |
| `location` | Территория | `customer_group` | Клиентская группа |
| `organisation` | Юридическое лицо | `customer_list` | Клиентский список |
| `item` | Товар | `customer_list_item` | Клиентский список :: элемент |
| `onhand` | Товарный остаток | `requisition` | Заявка на пополнение |
| `manufacturer` | Производитель | `orders` | Заказ покупателя |
| `groups_name` | Группа товаров | `order_state` | Заказ покупателя :: статусы заказа |
| `supplier` | Поставщик | `html_templates` | Шаблоны документов |
| `supplier_item` | Справочник товаров поставщика | `shipment` | Отгрузка |
| `inflow` | Поступление | `pricelist` | Прайслист |
| `movegood` | Перемещение | `pricelist_lines` | Прайслист :: строка прайслиста |
| `inventory` | Инвентаризация | `receipt` | Чек продажи |
| `user` | Пользователь |  |  |

## Типы гибких полей

Тип задаётся параметром `attr_type`:

| Значение | Тип | Описание |
| --- | --- | --- |
| `text` | Текст | Однострочный текст |
| `textarea` | Многострочный текст | Текст из нескольких строк |
| `list` | Один из списка | Выбор одного значения из `list_values` |
| `multi` | Несколько из списка | Выбор нескольких значений из `list_values` |
| `date` | Дата | Дата |

Для типов `list` и `multi` допустимые значения задаются в `list_values` строкой через запятую: `Да,Нет,Возможно`. Пробелы вокруг значений отбрасываются.

Каждое поле занимает одну колонку `attributeN` справочника, где N — значение `attr_num`. Количество колонок ограничено: у клиента, например, их 15.

## Получение полей

```
GET https://[компания].myvirtualpos.ru/api/flexField?apikey=MySecret&table_name=customer
```

### Параметры запроса

- **id** — Число. Ид гибкого поля. Если указан, возвращается только это поле
- **table_name** — Строка. Код справочника: возвращаются только его поля
- **name** — Строка. Название поля: возвращаются только поля с таким названием
- **format** — `json` (по умолчанию) или `xml`

Параметры можно сочетать, условия объединяются по «и». Если параметров нет, возвращаются все настроенные поля.

### Структура ответа

- **success** — `1` — данные получены
- **type** — Тип данных, всегда `flexfield`
- **count** — Количество полей в ответе
- **flexfields** — Список полей. Каждое обёрнуто в объект `flexfield`

### Поля гибкого поля

- **id** — Число. Ид гибкого поля
- **table_name** — Строка. Код справочника, к которому относится поле
- **name** — Строка. Название поля
- **attr_num** — Число. Номер колонки `attributeN` в справочнике. Системное имя поля — `attribute` + `attr_num`
- **attr_type** — Строка. Тип поля, см. раздел «Типы гибких полей»
- **enabled** — Строка. `Y` — поле включено, `N` — отключено
- **default_value** — Строка. Значение по умолчанию, пустая строка, если не задано
- **list_values** — Строка. Допустимые значения через запятую для типов `list` и `multi`, иначе пустая строка
- **created_date**, **last_update_date** — Строка. Дата и время создания и последнего изменения, формат `гггг-мм-дд чч:мм:сс`

### Пример ответа

```json
{
  "success": 1,
  "type": "flexfield",
  "count": 1,
  "flexfields": [
    {
      "flexfield": {
        "id": 7,
        "table_name": "customer",
        "name": "Откуда узнали",
        "attr_num": 2,
        "attr_type": "list",
        "enabled": "Y",
        "default_value": "",
        "list_values": "Сайт,Журнал,Листовка",
        "created_date": "2026-02-02 16:12:50",
        "last_update_date": "2026-02-02 16:12:50"
      }
    }
  ]
}
```

Тот же ответ при `format=xml`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <success>1</success>
  <type>flexfield</type>
  <count>1</count>
  <flexfields>
    <flexfield>
      <id>7</id>
      <table_name>customer</table_name>
      <name>Откуда узнали</name>
      <attr_num>2</attr_num>
      <attr_type>list</attr_type>
      <enabled>Y</enabled>
      <default_value/>
      <list_values>Сайт,Журнал,Листовка</list_values>
      <created_date>2026-02-02 16:12:50</created_date>
      <last_update_date>2026-02-02 16:12:50</last_update_date>
    </flexfield>
  </flexfields>
</root>
```

Если ничего не найдено, метод возвращает успешный ответ с `count` равным `0` и пустым списком `flexfields`.

## Создание и изменение поля

```
GET https://[компания].myvirtualpos.ru/api/flexField/update?apikey=MySecret&table_name=customer&name=%D0%A0%D0%B0%D0%B7%D0%BC%D0%B5%D1%80&create_if_not_exist=1&attr_type=list&list_values=S,M,L,XL
```

### Как ищется поле

Поле ищется по `id`, а если он не указан — по паре `table_name` и `name`. Если поле не найдено:
- при `create_if_not_exist=1` создаётся новое;
- иначе возвращается ошибка «Record not found».

### Параметры

- **id** — Число. Ид изменяемого поля. Только GET
- **table_name** — Строка. Код справочника. Вместе с `name` однозначно определяет поле. При создании обязателен. У существующего поля справочник не меняется. Только GET
- **name** — Строка, до 64 символов. Название поля. Вместе с `table_name` определяет поле; при обновлении по `id` переименовывает его. При создании обязательно. Только GET
- **create_if_not_exist** — `1` — создать поле, если оно не найдено. Только GET
- **attr_type** — Тип поля: `text`, `textarea`, `list`, `multi` или `date`. При создании обязателен
- **attr_num** — Число. Номер колонки `attributeN` справочника. Только при создании; если не указан, подбирается первый свободный. Колонка должна существовать у справочника и не быть занятой другим полем. При изменении поля игнорируется
- **enabled** — `Y` — поле включено (по умолчанию при создании), `N` — отключено
- **default_value** — Строка, до 1024 символов. Значение по умолчанию
- **list_values** — Строка, до 4096 символов. Значения через запятую для типов `list` и `multi`

Изменяются только переданные параметры, остальные остаются прежними.

### Ответ

```json
{"success":1,"id":"21","isnew":"1"}
```

- **success** — `1` — поле сохранено
- **id** — Ид поля. При создании приходит строкой, при изменении — числом
- **isnew** — `"1"` — поле создано, `"0"` — изменено существующее

> **Важно:**
> **Отключённое поле не принимается.** Если поле отключено (`enabled=N`), запросы к записям справочника его значение не записывают и не сообщают об этом. Ранее сохранённые значения остаются в записях.

## Удаление поля

```
GET https://[компания].myvirtualpos.ru/api/flexField/delete?apikey=MySecret&id=21
```

- **id** — Число. Ид удаляемого поля. Только GET
- **table_name**, **name** — Строки. Код справочника и название поля, если ид неизвестен. Нужны оба. Только GET
- **format** — `json` (по умолчанию) или `xml`

Ответ: `{"success":1}`. Если поля нет — ошибка «Record not found».

> **Важно:**
> **Значения не удаляются.** Удаление поля убирает его настройку, но значения в записях остаются в колонке `attributeN` справочника. Если создать новое поле с тем же `attr_num`, оно покажет старые значения.

## Как задать значение гибкого поля в записи

Значение гибкого поля задаётся тем же запросом, который создаёт или изменяет запись справочника. К обычным параметрам добавьте параметр `[имя поля]=[значение]`. Имя — либо название поля («Размер»), либо системное имя `attribute1`…`attribute15`. Номер колонки для каждого поля показывает `attr_num` в ответе метода получения или колонка «Номер атрибута» в разделе **Настройки → Гибкие поля**.

```
GET https://[компания].myvirtualpos.ru/api/customer/update?apikey=MySecret&id=40824&%D0%A0%D0%B0%D0%B7%D0%BC%D0%B5%D1%80=XL
GET https://[компания].myvirtualpos.ru/api/customer/update?apikey=MySecret&id=40824&attribute1=XL
```

Пустое значение очищает поле. Поле должно быть включено (`enabled=Y`). Запись значений описана для клиентов в статье [Customer. Клиенты](https://wiki.virtualpos.ru/hc/api/customer); в ответах методов клиентов гибкие поля не возвращаются.

## Примеры запросов

| Задача | Запрос |
| --- | --- |
| Список справочников | `/api/flexField/listTables?apikey=MySecret` |
| Все гибкие поля клиентов | `/api/flexField?apikey=MySecret&table_name=customer` |
| Поле по ид | `/api/flexField?apikey=MySecret&id=7` |
| Создать текстовое поле для клиентов | `/api/flexField/update?apikey=MySecret&create_if_not_exist=1&table_name=customer&name=Hobby&attr_type=text` |
| Создать поле-список для товаров | `/api/flexField/update?apikey=MySecret&create_if_not_exist=1&table_name=item&name=Season&attr_type=list&list_values=Winter,Summer` |
| Отключить поле | `/api/flexField/update?apikey=MySecret&id=21&enabled=N` |
| Переименовать поле | `/api/flexField/update?apikey=MySecret&id=21&name=Hobby2` |
| Удалить поле по названию | `/api/flexField/delete?apikey=MySecret&table_name=customer&name=Hobby` |

## Ошибки

Ошибка авторизации и общие ошибки описаны в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Ошибки методов раздела приходят с кодом HTTP 200 и `success` равным `0`:

| Сообщение | Метод | Причина | Что делать |
| --- | --- | --- | --- |
| You have to specify [id] or [table_name, name] to update record | update | Не указаны ни `id`, ни пара `table_name` и `name`, и нет `create_if_not_exist` | Передайте ид поля или пару `table_name` и `name` |
| [table_name] and [attr_num] parameters does not specified | update | Создание поля без `table_name` | Передайте код справочника |
| Record not found | update, delete | Поле не найдено, а `create_if_not_exist` не указан | Проверьте ид, справочник и название |
| Data validation failed. … | update | Данные не прошли проверку; далее идёт перечень полей и причин: не заполнены `name` или `attr_type`, неизвестные `table_name`, `attr_type`, `enabled`, слишком длинное значение, у справочника нет колонки с таким `attr_num` | Исправьте указанные параметры |
| Исчерпан лимит гибких полей на таблице … | update | У справочника не осталось свободных колонок `attributeN` | Удалите неиспользуемое поле |
| Cannot save data. … | update | Ошибка сохранения; например, `attr_num` уже занят другим полем справочника | Укажите другой `attr_num` или не передавайте его |
| You have to specify [id] or [table_name] + [name] to delete record | delete | Не указан ни `id`, ни пара `table_name` и `name` | Передайте ид поля или пару |
| Cannot delete data. … | delete | Ошибка удаления | Текст после точки поясняет причину |

## Связанные разделы

- [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview) — Ключ доступа, вызов методов, форматы ответов и ошибки
- [Customer. Клиенты](https://wiki.virtualpos.ru/hc/api/customer) — Изменение клиентов и значений их гибких полей