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

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

Получение остатков в разрезе товаров

Альтернативный вариант запроса на получение остатков. В отличие от предыдущего варианта данные группируются не по точкам продаж, а по товарам. Это позволяет запросить остатки одного товара сразу во всех точках продаж:

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

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

Механизм обнуления необновленных остатков

Логика обновления:

  1. Получить текущую версию данных об остатках (getOnhandVersion)
  2. Обновить товары с ненулевыми остатками (updateOnhand)
  3. Для всех необновленных товаров (версия данных младше полученной) массово установить нулевой остаток (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 склада, для которого надо обнулить остатки