API :: FlexField. Работа с Гибкими Полями

В системе реализован программный интерфейс для получения, добавления и изменения данных о гибких полях. Данные выгружаются по http протоколу. Формат на выбор - xml или json.

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

Настроенные Гибкие Поля можно посмотреть в административной консоли в меню «Настройки» → «Гибкие поля»

Например, Вы продаете одежду и настроили для справочника «Клиенты» гибкое поле «Размер». Теперь для каждого клиента возможно указать размер его одежды. Указать значение можно двумя способами.

1. Первый способ - через административный интерфейс в карточке Клиента (меню Клиенты). В карточке появится новая графа «Размер», в котором можно задать нужное значение

2. Второй способ - программно через API. Чтобы задать значение гибкого поля через API, необходимо к стандартному запросу на изменение/добавление Клиента добавить еще один параметр в формате: [ИмяПоля]=[Значение]

В качестве ИмяПоля можно указать как пользовательское название поля (пример: «Размер»), так и его системное имя: attribute1, .., attribute15. Конкретный номер атрибута для каждого гибкого поля можно посмотреть в административном интерфейсе настройках гибких полей (Настройки → Гибкие поля → Номер атрибута)

Пример запроса на изменение гибкого поля «Размер» для Клиента с ID=1 через API:

http://mycompany.virtpos.ru/api/customer/update?apikey=MySecret&id=1&Размер=XL

Для работы с Гибкими Полями в API предусмотрены следующие методы:

• listTables - получение списка справочников системы, которые поддерживают добавление Гибких Полей
• index - получение данных о настроенных Гибких Полях
• update - добавление или изменение Гибкого Поля
• delete - удаление настроенного ранее Гибкого Поля

Запрос возвращает список справочников системы, которые поддерживают работу с Гибкими Полями. Эти системные названия используются в других запросах в качестве параметра table_name.

Пример запроса на получение списка справочников:

http://mycompany.virtpos.ru/api/flexField/listTables?apikey=MySecret&format=xml

• apikey - Секретный ключ для доступа к данным. Обязательный параметр.

• format - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<success>1</success>
	<type>frexfield.tables</type>
	<count>5</count>
	<tables>
		<table>
			<name>warehouse</name>
			<description>Точка продаж</description>
		</table>
		<table>
			<name>location</name>
			<description>Территория</description>
		</table>
		<table>
			<name>organisation</name>
			<description>Юридическое лицо</description>
		</table>
		<table>
			<name>item</name>
			<description>Товар</description>
		</table>
		<table>
			<name>onhand</name>
			<description>Товарный остаток</description>
		</table>
	</tables>
</root>

Пример запроса на получение данных о настроенных Гибких Полях:

http://mycompany.virtpos.ru/api/flexField?apikey=MySecret&format=xml

• apikey (get или post) - Секретный ключ для доступа к данным. Обязательный параметр.

• format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.

• id (get only) - код Гибкого Поля, для которого надо вернуть данные. Если не указан, то возвращаются данные обо всех настроенных полях.

• table_name (get only) - системное название справочника. Если указано, то возвращаются поля только для этого справочника

• name (get only) - название Гибкого Поля. Если указано, то возвращаются поля только с таким названием

В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info

Ниже приведен пример ответа сервера в формате XML

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<success>1</success>
	<type>flexfield</type>
	<count>1</count>
	<flexfields>
		<flexfield>
			<id>32</id>
			<table_name>warehouse</table_name>
			<name>Площадь помещения</name>
			<attr_num>2</attr_num>
			<attr_type>text</attr_type>
			<enabled>Y</enabled>
			<default_value/>
			<list_values/>
			<created_date>2016-08-12 18:21:38</created_date>
			<last_update_date>2016-08-12 18:21:38</last_update_date>
		</flexfield>
	</flexfields>
</root>

Для обновления конкретного гибкого поля надо передать:

• либо его идентификатор (параметр id)
• либо пару справочник + название_поля (параметры table_name и name)

Пример запроса на изменение данных о гибком поле:

http://mycompany.virtpos.ru/api/flexField/update?apikey=MySecret&create_if_not_exist=0&enabled=N

• apikey (get или post) - Секретный ключ для доступа к данным. Обязательный параметр.

• format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.

• id (get only) - код товарной группы, данные которой надо обновить

• table_name (get only) - системное название таблицы, в которой надо изменить (добавить) поле. Используется для однозначной идентификации записи вместе с параметром name

• name (get only) - название гибкого поля, которое надо изменить (добавить). Используется для однозначной идентификации записи вместе с параметром table_name

• create_if_not_exist (get only) - если «1», то при неудачном поиске гибкое поле будет добавлено в систему.

• attr_type (get или post) - тип гибкого поля. Принимает значения: list (выбор из списка) или text(текстовые данные)

• enabled (get или post) - признак активно поле или нет. Принимает значения: Y (активно) или N (неактивно)

• default_value (get или post) - значение по умолчанию

• list_values (get или post) - список возможных значений гибкого поля. Используется с типом поля list. Список возможных значений передается в виде строки, разделенной запятыми. Лишних пробелов быть не должно. Пример: «Да,Нет,Возможно»

В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.

Также возвращается id записи, которая была обновлена или добавлена.

• Флаг isnew равен «1», если запись была создана, и «0» если обновлена.

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<success>1</success>
	<id>11</id>
	<isnew>1</isnew>
</root>

Функция настроенное ранее удаляет Гибкое Поле. Для удаления конкретного гибкого поля надо передать:

• либо его идентификатор (параметр id)
• либо пару: справочник + название_поля (параметры table_name и name)

Пример запроса на удаление гибкого поля:

http://mycompany.virtpos.ru/api/flexField/delete?apikey=MySecret&format=xml&id=2

• apikey (get или post) - Секретный ключ для доступа к данным. Обязательный параметр.

• format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.

• id (get only) - идентификатор гибкого поля, которое надо удалить

• table_name (get only) - системное название таблицы, в которой надо удалить поле. Используется для однозначной идентификации записи вместе с параметром name

• name (get only) - название гибкого поля, которое надо удалить. Используется для однозначной идентификации записи вместе с параметром table_name

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<success>1</success>
</root>