Различия

Здесь показаны различия между двумя версиями данной страницы.

--- doc:dev:api:item [11.07.2015 17:48]
rlysov создано
+++ doc:dev:api:item [28.04.2020 20:05] (текущий)
rlysov [Параметры запроса]
@@ Строка 1: / Строка 1: @@
 ====== API :: Item. Получение/изменение данных о номенклатуре ======
-В системе реализован программный интерфейс для получения, добавления и изменения данных о товарной номенклатуре. Данные выгружаются по http протоколу. Формат на выбор - xml или json.
+В системе реализован программный интерфейс для получения, добавления и изменения данных о товарной номенклатуре. Данные выгружаются по http протоколу. Формат на выбор - XML или JSON.
 ===== Пример запроса на получение данных =====
-Пример запроса на получение данных об остатках товаров:
+Пример запроса на получение данных о номенклатуре:
  http://mycompany.virtpos.ru/api/item?apikey=MySecret&format=xml
 ==== Параметры запроса ====
+параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
   * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
-  * **format** - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **id** (get only) - код товара, для которого надо вернуть данные. Если не указан, то возвращаются данные о всех товарах.
+  * **external_id** (get only) - код товара во внешней системе учета (например, в 1С)
+  * **enabled_only** (get only) - опционально, 1 если нужно получить только активные товары, 0 если все.
-  * **id** - код товара, для которого надо вернуть данные. Если не указан, то возвращаются данные о всех товарах.
+  * **pricelist** - (опционально). В параметре можно передать Id прайслиста. Если ID прайслиста переден, то к каждому товару будут добавлены колонки с ценами из этого прайлиста. Чтобы вернуть цены из прайслиста для интернет-витрины, то вместо ID можно указать ключевое слово "internet": &pricelist=internet.
-  * **external_id** - код товара во внешней системе учета (например, в 1С)
+  * **images** - опционально. Если указано значение "1", то к каждому товару будет добавлен список файлов с изображениями. Имена файлов будут перечислены через запятую
+  * **from_id** - опционально. Вернуть товары начиная с этого ID
+  * **limit** - опционально. Максимальное количество товаров в ответе
 ==== Ответ сервера ====
@@ Строка 33: / Строка 41: @@
 <file xml>
 <?xml version="1.0" encoding="UTF-8"?>
+<root>
+	<success>1</success>
+	<type>item</type>
+	<flexfields>
+		<attribute1>Цвет</attribute1>
+	</flexfields>
+	<count>2</count>
+	<items>
+		<item>
+			<id>1</id>
+			<name>Коробка конфет Рафаэлло</name>
+			<description/>
+			<enabled>1</enabled>
+			<sales_weight>0</sales_weight>
+			<manufacturer_id>1</manufacturer_id>
+			<type>G</type>
+			<weight_good_flag>N</weight_good_flag>
+			<not_show_in_shop>1</not_show_in_shop>
+                        <html_template_id>5</html_template_id>
+			<external_id/>
+			<group_ids>1,2</group_ids>
+			<group_ext_ids>{123-543},{000-999}</group_ext_ids>
+			<barcodes>4607092441788,9785864153055</barcodes>
+			<vat_percent>18</vat_percent>
+			<created_date>2015-07-11 17:16:49</created_date>
+			<last_update_date>2015-07-11 17:29:25</last_update_date>
+		</item>
+		<item>
+			<id>8</id>
+			<name>Чипсы Лэйс</name>
+			<description/>
+			<enabled>1</enabled>
+			<sales_weight>0</sales_weight>
+			<manufacturer_id>1</manufacturer_id>
+			<type>G</type>
+			<weight_good_flag>N</weight_good_flag>
+			<not_show_in_shop>0</not_show_in_shop>
+                        <html_template_id>5</html_template_id>
+			<external_id>22222</external_id>
+			<group_ids>1,2</group_ids>
+			<group_ext_ids>{123-543},{000-999}</group_ext_ids>
+			<barcodes>4607092441788,9785864153055</barcodes>
+			<vat_percent>18</vat_percent>
+			<created_date>2015-07-11 17:34:58</created_date>
+			<last_update_date>2015-07-11 17:36:36</last_update_date>
+			<attribute1>Красный</attribute1>
+		</item>
+	</items>
+</root>
 </file>
@@ Строка 39: / Строка 95: @@
 ===== Пример запроса на добавление/изменение данных =====
-Пример запроса на получение данных о товаре:
+Пример запроса на добавление/изменение данных о товаре:
  http://mycompany.virtpos.ru/api/item/update?apikey=MySecret&create_if_not_exist=0&external_id=666
 ==== Параметры запроса ====
+параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
   * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
-  * **format** - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
-  * **id** - код товара, данные которого надо обновить
+  * **id** (get only) - код товара, данные которого надо обновить
-  * **external_id** - код товара во внешней системе учета (например, в 1С), данные которого надо обновить
+  * **external_id** (get only) - код товара во внешней системе учета (например, в 1С), данные которого надо обновить
-  * **create_if_not_exist** - Если истина, то при неудачном поиске товар будет добавлен в систему.
+  * **create_if_not_exist** (get only) - Если истина, то при неудачном поиске товар будет добавлен в систему.
+  * **manufacturer_name** - Название производителя. Если значение указано, то происходит проверка, есть ли производитель с таким именем в справочнике. Если нет, то он будет добавлен. Параметр игнорируется, если указан manufacturer_id
+  * **name** - название товара
-  * Также в качестве параметров могут быть переданы все поля для товара (name, description, article и т.д.)
+  * **description** - описание товара
+  * **article** - артикул
+  * **enabled** - "0" или "1". признак,что товар активен и незаблокирован
+  * **volume** - объем
+  * **manufacturer_id** - id производителя
+  * **type** - тип товара (G - товар, S - услуга, M - материальная ценность).
+  * **weight_good_flag** - флаг весового товара. Значения "Y" / "N"
+  * **not_show_in_shop** - показывать или нет товар в интернет-витрине и мобильном приложении. Значения: "0" / "1"
+  * **html_template_id** - id шаблона ценника
+  * **category_id** - id товарной категории ("1" - алкоголь / "2" - товары18+ )
+  * **group_ids** - разделенный запятой список из id товарных групп, в которые входит товар
+  * **vat_percent** - ставка НДС
+  * **attribute1**..**attribute15** - значения гибких полей
@@ Строка 62: / Строка 146: @@
 В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
-Также возвращается id записи, которая была обновлена или добавлена. Флаг isnew равен "1", если запись была создана, и "0" если обновлена.
+Также возвращается id записи, которая была обновлена или добавлена.
+  * Флаг **isnew** равен "1", если запись была создана, и "0" если обновлена.
+  * Если в запросе указаны штрихкоды товара (поле barcodes), то в поле ответа **barcode_errors** возвращаются штрихкоды, не прошедшие проверку по контрольной сумме. А в поле **barcode_conflicts** возвращаются штрихкоды, которые уже назначены другим товарам.
@@ Строка 72: / Строка 159: @@
 	<id>11</id>
 	<isnew>1</isnew>
+	<barcode_errors>4607092441787</barcode_errors>
+	<barcode_conflicts/>
 </root>
 </file>
+===== Пример запроса на массовое добавление/изменение данных =====
+Данные для добавления передаются как POST-параметр data в формате JSON.
+Пример http запроса для массового обновления/добавления данных
+<file http>
+POST /api/item/updateAll?apikey=11112222&format=xml HTTP/1.1
+HOST: mycompany.virtpos.ru
+content-type: application/x-www-form-urlencoded
+content-length: 89
+data=[{"id":"1940","description":"Test desc 1"},{"external_id":"1941","description":"Test desc 2"}]
+</file>
+==== Параметры запроса ====
+параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
+  * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **create_if_not_exist** (get only) - Если истина, то при неудачном поиске товар будет добавлен в систему.
+==== Параметры data ====
+  * **id** - код товара, данные которого надо обновить
+  * **external_id** - код товара во внешней системе учета (например, в 1С), данные которого надо обновить
+  * **description** - значение товара, которое нужно обновить. В данном случае это описание. Могут быть (name, article, volume, attr1, attr2, attr3, attr4 и т.д.)
+==== Ответ сервера ====
+В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
+Также возвращаются:
+  * success_count - количество удачно обработанных записей
+  * fails_count - количество неудачно обработанных записей
+  * problem_ids - массив, который содержит id неудачно обработанных товаров
+  * problem_external_ids - массив, который содержит external_id неудачно обработанных товаров
+==== Пример ответа сервера ====
+<file xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<root>
+   <success>1</success>
+   <success_count>0</success_count>
+   <fails_count>3</fails_count>
+   <problem_ids>
+      <problem_item>
+         <id>1940</id>
+      </problem_item>
+      <problem_item>
+         <id>1941</id>
+      </problem_item>
+   </problem_ids>
+   <problem_external_ids>
+      <problem_item>
+         <id>1942</id>
+      </problem_item>
+   </problem_external_ids>
+</root>
+</file>