====== API :: Store. Получение данных об остатках товара ======
В системе реализован программный интерфейс для получения и обновления данных об остатках товаров в магазинах. Данные выгружаются по http протоколу. Формат на выбор - xml или json.
===== Пример запроса на получение данных =====
Пример запроса на получение данных об остатках товаров:
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
1
store
1
1
3
Магазин 1
1
-
17007
2.000
1.000
12345
63838 Корм для собак 2кг
63838
0.00
1126.00
4
1126.00
3
866.00
===== Получение остатков в разрезе товаров =====
Альтернативный вариант запроса на получение остатков. В отличие от предыдущего варианта данные группируются не по точкам продаж, а по товарам. Это позволяет запросить остатки одного товара сразу во всех точках продаж:
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
1
3
8
1
0
1.700
===== Механизм обнуления необновленных остатков =====
Логика обновления:
- Получить текущую версию данных об остатках (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 склада, для которого надо обнулить остатки