Это старая версия документа.


API :: Receipt. Получение данных о продажах

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

Пример запроса

Пример запроса на получение данных о продажах (чеков продаж):

http://mycompany.virtpos.ru/api/receipt?apikey=MySecret&marker=394804029:000000010&format=xml

Параметры запроса

  • apikey - Секретный ключ для доступа к данным. Обязательный параметр.
  • marker - уникальный идентификатор чека, который был обработан при последнем обмене данными. Параметр нужен для того, чтобы получать только новые чеки, которые еще не были получены ранее. Необязательный параметр. Если параметр указан, то будут отданы все чеки, которые были сформированы после него. Если параметр пустой, то будут отданы все чеки за последние 25 дней
  • bankTransaction - флаг, который включает добавление в чек информации о банковской транзакции. Принимает значения 0 и 1. По умолчанию 0.
  • datefrom - Необязательный параметр. Если указан, то будут отданы данные, поступившие в облако после указанной даты. Формат даты: ГГГГММДД. Необходимо обратить внимание, что дата продажи и дата поступления в облако могут различаться.
  • format - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.
  • fields - список дополнительных полей, которые будут добавлены в ответ сервера. Имена полей разделены символом «:». Необязательный параметр. Поддерживаются следующие поля:
    • itemname - название товара
    • itemid2 - уникальный идентификатор товара во внешней системе (например, в 1С). Значение заполняется при выгрузке товара в ВиртуалПос из внешней системы.
    • warehouseid2 - уникальный идентификатор магазина во внешней системе (например, в 1С). Значение заполняется при выгрузке товара в ВиртуалПос из внешней системы.
    • article - артикул товара
    • lot_number - характеристика(серия/партия) проданного товара
    • user_login - логин продавца
    • user_fio - ФИО продавца
    • discount_name - название скидки, примененной к строке чека
    • customer_id - ID покупателя
    • customer_id2 - ID покупателя во внешней системе (например, в 1С)
    • customer_fname - Имя покупателя
    • customer_lname - Фамилия покупателя
    • customer_mname - Отчество покупателя
    • card_id - ID дисконтной карты, которая применена при покупке
    • card_id2 - ID дисконтной карты во внешней системе (например, в 1С)
    • manufacturer_id - id производителя товара
    • manufacturer_name - название производителя товара
    • session_open_datetime - дата и время начала смены

Ответ сервера

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

Пример ответа сервера

Ниже приведен пример ответа сервера в формате XML

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <success>1</success>
   <type>receipt</type>
   <count>2</count>
   <receipts>
      <receipt>
         <receipt_id>1E1208CD-84D2-47ED-B58B-16706FD400B0</receipt_id>
         <marker>1415193742:0000036451</marker>
         <terminalid>00000001</terminalid>
         <warehouseid>1</warehouseid>
         <user_id>19</user_id>
         <fr_session>1</fr_session>
         <doc_type>sale</doc_type>
         <doc_num>10</doc_num>
         <doc_num_session>6</doc_num_session>
         <date>03.11.2014 18:31:49</date>
         <discount>0.00</discount>
         <discount_misc>0.00</discount_misc>
         <amount>1749.00</amount>
         <pay_cash>0.00</pay_cash>
         <pay_card>1749.00</pay_card>
         <pay_tare>0.00</pay_tare>
         <pay_credit>0.00</pay_credit>
         <is_electronic>1</is_electronic>
         <pinpad_name>sbrf</pinpad_name>
         <terminal_number>3</terminal_number>
         <device_model_name>ШТРИХ-ФР-01Ф</device_model_name>
         <device_model_version>S C.1 34378 13.01.2017 0 0 01.01.1980 1.14 4</device_model_version>
         <short_fiscal_serial_number>234234</short_fiscal_serial_number>
         <items_count>1</items_count>
         <items>
            <item>
               <line_id>88E41E39-3D0E-5696-78A9-F79A12854B69</line_id>
               <itemid>3580</itemid>
               <quantity>1</quantity>
               <pricebase>1749.00</pricebase>
               <pricesale>1749.00</pricesale>
               <discount>0.00</discount>
               <amount>1749.00</amount>
               <cogs>102.00</cogs>               
               <barcode />
               <user_id />
               <vat_applied/>
               <vat_amount/>
            </item>
         </items>
         <adjustment>
             <id>5</id>
             <title>Корректировка поступления к товарной накладной №1</title>
             <created_date>2017-07-03 16:18:55</created_date>
             <items>
                <line_id>11</line_id>
                <item_id>5</item_id>
                <item_ext_id>eacf7608-892c-11e4-ab28-005056a7771f</item_ext_id>
                <item_name>Аджика по-абхазски SUNFEEL 250 г.</item_name>
                <quantity>5.000</quantity>
                <quantity_expected>1.000</quantity_expected>
                <line_id>12</line_id>
                <item_id>9</item_id>
                <item_ext_id>7c3cbdc3-8d0f-11e4-ab28-005056a7771f</item_ext_id>
                <item_name>Адреналин Раш, 0.5 л. ж/б</item_name>
                <quantity>2.000</quantity>
                <quantity_expected>1.000</quantity_expected>
             </items>
         </adjustment>
         <bankTransaction>
            <rrn>0123456789</rrn>
            <trx_date>18.11.2015</trx_date>
            <term_num>10000000</term_num>
            <auth_code>500000</auth_code>
            <card_type>3</card_type>
            <client_card>676201******1234</client_card>
            <amount_clear>21900</amount_clear>
            <payment_type>coupon</payment_type>
            <payment_denomination>500</payment_denomination>
         </bankTransaction>
         <coupons>
             <barcode>CC-00000040</barcode>
             <sum>500.00</sum>
             <external_id>0</external_id>
         </coupons>
         <session_open_datetime>2016-03-01 16:26:39</session_open_datetime>
      </receipt>
      <receipt>
         <receipt_id>2348F9DA-0B8C-45B7-80AE-7B136E6B9F94</receipt_id>
         <marker>1415193742:0000036452</marker>
         <terminalid>00000001</terminalid>
         <warehouseid>1</warehouseid>
         <user_id>19</user_id>
         <fr_session>1</fr_session>
         <doc_type>return</doc_type>
         <doc_num>11</doc_num>
         <doc_num_session>7</doc_num_session>
         <date>04.11.2014 17:02:53</date>
         <discount>0.00</discount>
         <discount_misc>0.00</discount_misc>
         <amount>199.00</amount>
         <pay_cash>199.00</pay_cash>
         <pay_card>0.00</pay_card>
         <pay_tare>0.00</pay_tare>
         <pay_credit>0.00</pay_credit>
         <pinpad_name>sbrf</pinpad_name>
         <terminal_number>3</terminal_number>
         <items_count>1</items_count>
         <items>
            <item>
               <line_id>D361F6C1-048D-45FA-CB9C-4633FC25DECA</line_id>
               <itemid>3380</itemid>
               <quantity>1</quantity>
               <pricebase>199.00</pricebase>
               <pricesale>199.00</pricesale>
               <discount>0.00</discount>
               <amount>199.00</amount>
               <cogs>102.00</cogs>               
               <barcode />
               <user_id />
               <vat_applied/>
               <vat_amount/>               
            </item>
         </items>
         <bankTransaction>
            <rrn>0123456789</rrn>
            <trx_date>18.11.2015</trx_date>
            <term_num>10000000</term_num>
            <auth_code>500000</auth_code>
            <card_type>3</card_type>
            <client_card>676201******1234</client_card>
            <amount_clear>21900</amount_clear>
         </bankTransaction>
         <sale_receipt_id>D36B3C45-9939-AB11-D9FB-3BA4CB44607E</sale_receipt_id>
         <sale_receipt_date>09.12.2015 17:35:11</sale_receipt_date>
         <session_open_datetime>2016-03-01 16:26:39</session_open_datetime>
      </receipt>
   </receipts>
</root>

Описание данных в ответе

Данные о чеке (раздел receipt)

  • <receipt_id>1E1208CD-84D2-47ED-B58B-16706FD400B0</receipt_id> - уникальный GUID чека
  • <marker>1415193742:0000036451</marker> - уникальный маркер чека. используется для получения новых данных о продажах
  • <terminalid>00000001</terminalid> - регистрационный номер фискального регистратора. Если ФР не используется, то передается некий уникальный идентификатор рабочего места кассира
  • <warehouseid>1</warehouseid> - ID склада/магазина в системе VirtualPos
  • <user_id>19</user_id> - ID продавца
  • <fr_session>1</fr_session> - номер смены
  • <doc_type>sale</doc_type> - тип чека: sale или return
  • <doc_num>10</doc_num> - номер документа по данным ФР
  • <doc_num_session>6</doc_num_session> - номер чека в смене по данным ФР
  • <date>03.11.2014 18:31:49</date> - дата продажи в формате dd.mm.yyy hh:mi:ss
  • <discount>0.00</discount> - размер скидки на чек
  • <discount_misc>0.00</discount_misc> - размер дополнительной скидки на чек (оплачено купоном, сертификатом)
  • <amount>1749.00</amount> - сумма чека с учетом скидки
  • <pay_cash>0.00</pay_cash> - оплачено наличными
  • <pay_card>1749.00</pay_card> - оплачено банковской картой
  • <pay_tare>0.00</pay_tare> - оплачено тарой (не используется)
  • <pay_credit>0.00</pay_credit> - оплачено кредитом (не используется)
  • <is_electronic>1</is_electronic> - отправлен электронный чек покупателю
  • <pinpad_name>sbrf</pinpad_name> - признак платёжного терминала
  • <terminal_number>3</terminal_number> - номер кассы в зале
  • <device_model_name>ШТРИХ-ФР-01Ф</device_model_name> - наименование модели ККМ
  • <device_model_version>S C.1 34378 13.01.2017 0 0 01.01.1980 1.14 4</device_model_version> - версия модели ККТ
  • <short_fiscal_serial_number>234234</short_fiscal_serial_number> - краткий серийный номер ККТ
  • <items_count>1</items_count> - количество товаров в чеке
  • <payment_type>coupon</payment_type> - признак того, что часть чека/чек полностью оплачен подарочным сертификатом
  • <payment_denomination>500</payment_denomination> - номинал подарочного сертификата
  • <sale_receipt_id>D36B3C45-9939-AB11-D9FB-3BA4CB44607E</sale_receipt_id> - поле заполняется только для чеков с типом «Возврат» (return), содержит ссылку на первоначальные чек продажи
  • <sale_receipt_date>09.12.2015 17:35:11</sale_receipt_date> - поле заполняется только для чеков с типом «Возврат»(return), содержит дату первоначального чека продажи
  • <rrn>0123456789</rrn> - номер операции (RRN транзакции)
  • <trx_date>18.11.2015</trx_date> - дата операции
  • <term_num>10000000</term_num> - номер платёжного терминала
  • <auth_code>500000</auth_code> - код авторизации
  • <card_type>3</card_type> - тип платёжной карты
  • <client_card>676201**1234</client_card> - номер платёжной карты
  • <amount_clear>21900</amount_clear> - сумма оплаты
  • <session_open_datetime>2016-03-01 16:26:39</session_open_datetime> - дата и время начала смены

Данные о товарах в чеке (items):

  • <line_id>88E41E39-3D0E-5696-78A9-F79A12854B69</line_id> - уникальный GUID строки чека
  • <itemid>3580</itemid> - ID товара в ВиртуалПос
  • <quantity>1</quantity> - количество товара в чеке
  • <pricebase>1749.00</pricebase> - цена по прайслисту за единицу товара (без учета скидки)
  • <pricesale>1749.00</pricesale> - цена продажи за единицу товара (с учетом скидки)
  • <discount>0.00</discount> - сумма скидки
  • <amount>1749.00</amount> - сумма по строке чека (с учетом скидки)
  • <cogs>109.00</cogs> - себестоимость товара
  • <barcode /> - штрихкоды упаковок через запятую
  • <user_id /> - ID продавца (не используется)
  • <vat_applied/> - ставка НДС
  • <vat_amount/> - сумма НДС

Данные о корректировке поступления (adjustment):

  • <id> - ID корректировки поступления
  • <title> - наименование корректировки поступления
  • <created_date> - дата создания корректировки поступления
  • <items> - товары корректировки поступления
  • <line_id>11</line_id> - id товара в корректировке поступления
  • <item_id>5</item_id> - id товара в VirtualPos
  • <item_ext_id>eacf7608-892c-11e4-ab28-005056a7771f</item_ext_id> - уникальный id товара
  • <item_name>Аджика по-абхазски SUNFEEL 250 г.</item_name> - название товара
  • <quantity>5.000</quantity> - фактическое количество товара в корректировке
  • <quantity_expected>1.000</quantity_expected> - ожидаемое количество товара в корректировке

Данные о подарочных сертификатах (coupons):

  • <barcode>CC-00000040</barcode> - номер ПС
  • <sum>500.00</sum> - сумма сертификата (номинал)
  • <external_id>0</external_id> - идентификатор ПС как товара