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

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

===== Что такое "Гибкие Поля" =====

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

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

===== Пример использования Гибких Полей =====

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

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

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

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

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

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



===== Функции API для работы с Гибкими Полями =====

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


----

===== listTables :: Получение списка справочников =====

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

==== Пример вызова =====

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

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

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

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

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

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

<file xml>
<?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>
</file>


----

===== index :: Запрос на получение данных =====

==== Пример вызова ====

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

 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

<file 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>
</file>


----

===== update :: добавление/изменение Гибкого Поля =====

Для обновления конкретного гибкого поля надо передать: 
  * либо его идентификатор (параметр **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" если обновлена.


==== Пример ответа сервера ====
<file xml>
<?xml version="1.0" encoding="UTF-8"?>
<root>
	<success>1</success>
	<id>11</id>
	<isnew>1</isnew>
</root>
</file>

----

===== delete :: Удаление Гибкого Поля =====

Функция настроенное ранее удаляет Гибкое Поле. Для удаления конкретного гибкого поля надо передать:
  * либо его идентификатор (параметр **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**

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

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