Различия
Здесь показаны различия между двумя версиями данной страницы.
doc:dev:api:flexfield [01.09.2017 13:09] mzubkov [Параметры запроса] |
doc:dev:api:flexfield [02.06.2018 10:42] |
||
---|---|---|---|
Строка 1: | Строка 1: | ||
- | ====== 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** - Секретный ключ для доступа к данным. Обязательный параметр. | ||
- | |||
- | * **format** - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр. | ||
- | |||
- | * **id** - идентификатор гибкого поля, которое надо удалить | ||
- | |||
- | * **table_name** - системное название таблицы, в которой надо удалить поле. Используется для однозначной идентификации записи вместе с параметром **name** | ||
- | |||
- | * **name** - название гибкого поля, которое надо удалить. Используется для однозначной идентификации записи вместе с параметром **table_name** | ||
- | |||
- | ==== Пример ответа ==== | ||
- | |||
- | <file xml> | ||
- | <?xml version="1.0" encoding="UTF-8"?> | ||
- | <root> | ||
- | <success>1</success> | ||
- | </root> | ||
- | </file> | ||
- | |||
- | |||