API :: Item. Получение/изменение данных о номенклатуре

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

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

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

параметры, которые не отмечены как get only, могут быть переданы как get- или как post-параметры.

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

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

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

• external_id (get only) - код товара во внешней системе учета (например, в 1С)

• enabled_only (get only) - опционально, 1 если нужно получить только активные товары, 0 если все.

• pricelist - (опционально). В параметре можно передать Id прайслиста. Если ID прайслиста переден, то к каждому товару будут добавлены колонки с ценами из этого прайлиста. Чтобы вернуть цены из прайслиста для интернет-витрины, то вместо ID можно указать ключевое слово «internet»: &pricelist=internet.

• images - опционально. Если указано значение «1», то к каждому товару будет добавлен список файлов с изображениями. Имена файлов будут перечислены через запятую

• from_id - опционально. Вернуть товары начиная с этого ID

• limit - опционально. Максимальное количество товаров в ответе

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

Ниже приведен пример ответа сервера в формате 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>

Пример запроса на добавление/изменение данных о товаре:

http://mycompany.virtpos.ru/api/item/update?apikey=MySecret&create_if_not_exist=0&external_id=666

параметры, которые не отмечены как get only, могут быть переданы как get- или как post-параметры.

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

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

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

• external_id (get only) - код товара во внешней системе учета (например, в 1С), данные которого надо обновить

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

• manufacturer_name - Название производителя. Если значение указано, то происходит проверка, есть ли производитель с таким именем в справочнике. Если нет, то он будет добавлен. Параметр игнорируется, если указан manufacturer_id

• name - название товара

• 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 - значения гибких полей

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

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

• Флаг isnew равен «1», если запись была создана, и «0» если обновлена.
• Если в запросе указаны штрихкоды товара (поле barcodes), то в поле ответа barcode_errors возвращаются штрихкоды, не прошедшие проверку по контрольной сумме. А в поле barcode_conflicts возвращаются штрихкоды, которые уже назначены другим товарам.

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

Данные для добавления передаются как POST-параметр data в формате JSON. Пример 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"}]

параметры, которые не отмечены как get only, могут быть переданы как get- или как post-параметры.

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

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

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

• 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 неудачно обработанных товаров

<?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>