Различия

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

--- doc:dev:api:store [25.04.2015 13:15]
rlysov
+++ doc:dev:api:store [23.10.2020 16:09] (текущий)
sshevchuk [Получение остатков в разрезе товаров]
@@ Строка 1: / Строка 1: @@
 ====== API :: Store. Получение данных об остатках товара ======
-В системе реализован программный интерфейс для получения данных об остатках товаров в магазинах. Данные выгружаются по http протоколу. Формат на выбор - xml или json.
+В системе реализован программный интерфейс для получения и обновления данных об остатках товаров в магазинах. Данные выгружаются по http протоколу. Формат на выбор - xml или json.
-===== Пример запроса =====
+===== Пример запроса на получение данных =====
 Пример запроса на получение данных об остатках товаров:
- http://mycompany.virtpos.ru/api/store?apikey=MySecret&format=xml
+ http://mycompany.virtpos.ru/api/store?apikey=MySecret&format=xml&warehouseid=1&fields=itemname:article
+==== Параметры запроса на получение данных ====
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
+  * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **stockonly** (get only) - если "1", то возвращает только те товары, которые есть в наличии (остаток больше нуля)
+  * **warehouseid** (get only) - код магазина, для которого надо вернуть данные об остатках. Если не указан, то возвращаются данные обо всех магазинах.
+  * **itemid** (get only) - код товара, данные о котором надо вернуть. Если не задан, то будут отданы данные обо всех товарах.
+  * **article** (get only) - артикул товара, данные о котором надо вернуть. Если не задан, то будут отданы данные обо всех товарах.
+  * **itemname** (get only) - название товара, данные о котором надо вернуть. Если не задан, то будут отданы данные обо всех товарах.
+  * **fields** - список дополнительных полей, которые будут добавлены в ответ сервера. Имена полей разделены символом ":". Необязательный параметр. Поддерживаются следующие поля:
+    * itemname - название товара
+    * article - артикул товара
+    * cogs - себестоимость товара
+    * price - цена продажи по основному прайслисту
+    * optionalprices - цены товара по дополнительным прайслистам
+    * turnovercalc - оборачиваемость товара, рассчитанная системой
+==== Ответ сервера ====
+В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
+  * quantity - текущее количество товара
+  * available_quantity - количество товара с учетом резервов
+==== Пример ответа сервера ====
+Ниже приведен пример ответа сервера в формате XML
+<file xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<root>
+    <success>1</success>
+    <type>store</type>
+    <stockonly>1</stockonly>
+    <count>1</count>
+    <warehouses>
+        <warehouse>
+            <id>3</id>
+            <name>Магазин 1</name>
+            <count>1</count>
+            <items>
+                <item>
+                    <id>17007</id>
+                    <quantity>2.000</quantity>
+                    <available_quantity>1.000</available_quantity>
+                    <lot_number>12345</lot_number>
+                    <name>63838 Корм для собак 2кг</name>
+                    <article>63838</article>
+                    <cogs>0.00</cogs>
+                    <price>1126.00</price>
+                    <prices>
+                        <price>
+                            <pricelistid>4</pricelistid>
+                            <price>1126.00</price>
+                        </price>
+                        <price>
+                            <pricelistid>3</pricelistid>
+                            <price>866.00</price>
+                        </price>
+                    </prices>
+                </item>
+            </items>
+        </warehouse>
+    </warehouses>
+</root>
+</file>
+===== Получение остатков в разрезе товаров =====
+Альтернативный вариант запроса на получение остатков. В отличие от предыдущего варианта данные группируются не по точкам продаж, а по товарам. Это позволяет запросить остатки одного товара сразу во всех точках продаж:
+ http://mycompany.myvirtualpos.ru/api/store/byItem?apikey=MySecret&format=xml&id=1&from_id=0&total=1&limit=10
+==== Параметры запроса на получение данных ====
+  * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **id** - идентификатор товара. Если не указан, то возвращаются данные по всем товарам. Если указан, будут отданы остатки по всем точкам продаж для этого товара
+  * **from_id** - идентификатор товара, начиная с которого надо вернуть данные. Если указан, то возвращаются только те товары, идентификатор которых больше указанного. Используется совместно с параметром limit и total для получения данных пачками
+  * **total** - (bool). Если указано "yes", "true" или "1", то в ответ будет добавлено поле "total" с общим количеством строк данных, соответствующих запросу. Используется совместно с limit для получения общего количества строк
+  * **limit** - максимальное число записей, которые можно вернуть.
+====== Изменение данных ======
+===== Пример запроса на изменение данных =====
+Пример запроса на изменение данных об остатках товаров:
+ http://mycompany.virtpos.ru/api/store/updateOnhand?apikey=MySecret&format=xml&warehouseid=1&itemid=1&quantity=20
+==== Параметры запроса на изменение данных ====
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
+  * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **warehouseid** (get only) - код магазина, в котором надо изменить данные об остатках.
+  * **itemid** (get only) - код товара, данные о котором надо изменить.
+  * **ext_warehouseid** (get only) - код магазина внешней системе (например, 1С), в котором надо изменить данные об остатках. Используется только если не указан warehouseid
+  * **ext_itemid** (get only) - код товара внешней системе (например, 1С), данные о котором надо изменить. . Используется только если не указан itemid
+  * Поля, которые можно изменить:
+    * quantity - количество товара
+    * manuf_date - дата изготовления товарного остатка
+    * cogs - себестоимость товарного остатка
+    * expir_date - срок годности товарного остатка
+    * lot_number - серия или партия товарного остатка
+==== Ответ сервера ====
+В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info. Также в ответе присутствуют:
+  * itemid - внутренний идентификатор товара, данные о котором были обновлены
+  * warehouseid - внутренний идентификатор магазина(склада), на котором был обновлен остаток товара
+  * isnew - "1" если остаток был впервые добавлен в систему. 0 - если остаток был обновлен
+  * quantity_before - количество товара до обновления
+==== Пример ответа сервера ====
+Ниже приведен пример ответа сервера в формате XML
+<file xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<root>
+    <success>1</success>
+    <id>3</id>
+    <itemid>8</itemid>
+    <warehouseid>1</warehouseid>
+    <isnew>0</isnew>
+    <quantity_before>1.700</quantity_before>
+</root>
+</file>
+===== Механизм обнуления необновленных остатков =====
+Логика обновления:
+    - Получить текущую версию данных об остатках (getOnhandVersion)
+    - Обновить товары с ненулевыми остатками (updateOnhand)
+    - Для всех необновленных товаров (версия данных младше полученной) массово установить нулевой остаток (setZeroOnhand)
+==== Получение текущей версии: ====
+ http://mycompany.virtpos.ru/api/store/getOnhandVersion?apikey=MySecret&format=xml&ext_warehouseid=1
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
+Параметры:
+  * int **warehouseid** (get only) - ID склада в ВиП, для которого надо получить версию остатков
+  * string **ext_warehouseid** (get only) - Внешний ID склада,  для которого надо получить версию остатков
+==== Обнуление необновленных остатков ====
+ http://mycompany.virtpos.ru/api/store/setZeroOnhand?apikey=MySecret&format=xml&ext_warehouseid=1
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
+Параметры:
+  * int **version** (get only) - версия, полученная с помощью функции getOnhandVersion
+  * int **warehouseid** (get only) - ID склада в ВиП, для которого надо обнулить остатки
+  * string **ext_warehouseid** (get only) - Внешний ID склада,  для которого надо обнулить остатки