4.8. API интерфейс

REGOS: VCR предоставляет API интерфейс для взаимодействия с пользовательскими функциями.


Содержание:

Порядок взаимодействия

Взаимодействие с REGOS: VCR осуществляется с помощью HTTP-запросов методом POST.

Каждый запрос должен содержать обязательный заголовок (Headers):

Content-Type : application/json

Тело запроса (Body) имеет следующую структуру:

{
    "id":1,
    "jsonrpc":"2.0",
    "method":"ZReport.GetInfo",
    "params":null,
    "auth":"cmVF5dd6cGds33M5"
}

где:

  • "id" - Id запроса к API;
  • "method" - поле содержит в себе название метода, вызываемого при обращении к API интерфейсу;
  • "params" - Объект, при необходимости, должен содержать в себе дополнительные данные, необходимые для выполнения API метода;
  • "auth" - Поле содержит в себе Base64(Login:Password) - логин:пароль, зашифрованные в формате base64. Доступ к использованию API интерфейса имеет только пользователь Кассир.

При корректном выполнении метода сервер вернет ответ с кодом 200. Другие коды ответа, могут возникать при ошибке на стороне сервера.

Тело ответа (Body) имеет следующую структуру:

{
    "id":1,
    "ok":true,
    "result": object,
    "jsonrpc":"2.0"
}

где:

  • id - id запроса;
  • ok - статус выполнения запроса (true - успех, false - ошибка);
  • result - объект ответа. Если ok=true, то ответ метода, если ok=false - объект с описанием ошибки.

Все методы, кроме sys.getinfo осуществляют печать на принтере на который настроена виртуальная касса. Без настроенного принтера методы работать не будут.

Для тестирования API виртуальной кассы REGOS: VCR можно использовать следующий Endpoint: http://vcr-test.regos.uz:22298
Для проверки работы методов в тестовой среде и просмотра напечатанного результата на POS принтере запущена онлайн Web-камера


Пользовательские методы

sys.getinfo

Получение информации о фискальном модуле

Входные параметры

Метод не имеет входных параметров.

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

{
    "id":1,
    "auth":"a2Fzc2E6MTIzNDU2Nzhh",
    "method":"Sys.GetInfo",
    "params":null,
    "jsonrpc":"2.0"
}

Выходные параметры

Название Тип данных Описание параметра
TerminalID string Уникальный номер фискального модуля
CurrentReceiptSeq string Номер последнего чека, отправленного на фискальный модуль
CurrentTime string Дата и время в формате YYYY-MM-DD hh:mm:ss последнего отправленного чека на фискальный модуль
ReceiptCount int64 Количество чеков за текущий ZReport
ReceiptMaxCount int64 Максимальное количество чеков
ZReportCount int64 Количество открытых ZReport
ZReportMaxCount int64 Максимальное количество ZReport
AvailablePersistentMemory int64 Доступная постоянная память
AvailableResetMemory int64 Доступная сбрасываемая память
AvailableDeselectMemory int64 Память javacard

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

{
    "id":1,
    "ok":true,
    "result":
    {
        "TerminalID":"UZ75686797076878",
        "CurrentReceiptSeq":"355",
        "CurrentTime":"2020-11-26 17:42:12",
        "ReceiptCount":0,
        "ReceiptMaxCount":858,
        "ZReportCount":69,
        "ZReportMaxCount":832,
        "AvailablePersistentMemory":6100,
        "AvailableResetMemory":1440,
        "AvailableDeselectMemory":1440
    },
    "jsonrpc":"2.0"
}


receipt.sale

Занесение чека продажи.

Входные параметры

Название Тип данных Обязательность Описание параметра
code string Обязательный Номер чека в системе клиента
pos_id string Необязательный Id кассы в системе клиента, если не задан ставится VCR
session_code string Необязательный Номер кассовой смены в системе клиента
cashier_name string Необязательный ФИО кассира в системе клиента. Если не задан, ставится имя пользователя под котором выполняется запрос
seller_name string Необязательный Имя продавца в системе клиента (может быть передана пустая строка)
positions Array of positions Обязательный Позиции номенклатуры - массив объектов positions
payments Array of payments Обязательный Позиции оплаты - массив объектов payments
custom_variables Array of custom_variables Необязательный Клиентские переменные для печати чека - массив объектов custom_variables


positions

Модель, описывающая позиции номенклатуры в чеке.

Название Тип данных Обязательность Описание параметра
name string Обязательный Наименование номенклатуры
barcode string Обязательный Штрих-код в формате EAN-13
code string Необязательный Код номенклатуры
articul string Необязательный Артикул
unit_name string Необязательный Наименование единицы измерения
size_name string Необязательный Наименование размера
brand_name string Необязательный Наименование бренда
producer_name string Необязательный Наименование производителя
color_name string Необязательный Наименование цвета
country_name string Необязательный Страна производителя
department_name string Необязательный Наименование отдела
group_name string Необязательный Наименование группы номенклатуры
type_name string Необязательный Наименование типа номенклатуры
label string Необязательный Код обязательной маркировки (можно передать пустую строку)
quantity int64 Обязательный Количество в граммах. Всегда больше 0. Если label задан – то всегда 1000. Если товар штучный, то 1000 * кол-во
amount int64 Обязательный Сумма стоимости позиции без учёта скидки. Значение суммы * 100. Не может быть меньше 0
discount int64 Обязательный Сумма скидки позиции. Значение суммы * 100. Не может быть меньше 0
vat_value int64 Обязательный Значение ставки НДС * 100. При ставке "Без НДС" отправляется значение "-1". Ставка НДС должна быть занесена на VCR


payments

Модель, описывающая позиции оплаты в чеке.

Название Тип данных Обязательность Описание параметра
type Int64 Обязательный Форма оплаты в VCR: 1 (наличные), 2 (терминал)
value int64 Обязательный Сумма оплаты. Значение суммы * 100. Не может быть меньше 0


custom_variables

Модель, описывающая клиентские переменные в чеке.

Название Тип данных Обязательность Описание параметра
name string Обязательный Наименование переменной
value string Обязательный Значение переменной

Добавляемые переменные в чеки согласуются с сотрудниками ЦТО, кроме того содержимое чека не должно нарушать требования ПКМ Республики Узбекистан №943 от 23.11.2020.

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

{
    "id":1,
    "auth":"a2Fzc2E6MTIzNDU2Nzhh",
    "method":"Receipt.Sale",
    "params":
    {
        "code":"1-0000782",
        "pos_id":"00027",
        "session_code":"1-0000086",
        "cashier_name":"Administrator",
        "seller_name":null,
        "positions":
        [
            {
                "name":"Coca-cola",
                "barcode":"000001",
                "code":"000001",
                "articul":"",
                "unit_name":"шт",
                "size_name":null,
                "brand_name":null,
                "producer_name":"Coca Cola",
                "color_name":null,
                "country_name":null,
                "department_name":null,
                "group_name":"Напитки",
                "type_name":"Товар",
                "label":"",
                "quantity":1000,
                "amount":900000,
                "discount":0,
                "vat_value":1500
            }
        ],
        "payments":
        [
            {
                "type":1,
                "value":900000
            }
        ],
        "custom_variables":null
    },
    "jsonrpc":"2.0"
}

Выходные параметры

Название Тип данных Описание параметра
id string id созданного чека в REGOS: VCR

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

{
    "id":1,
    "ok":true,
    "result":
    {
        "id":"3ca29f3a-c19a-4a43-ba28-8425bf9bf383"
    },
    "jsonrpc":"2.0"
}


receipt.refund

Занесение чека возврата.

Входные параметры

Название Тип данных Обязательность Описание параметра
code string Обязательный Номер чека в системе клиента
pos_id string Необязательный Id кассы в системе клиента, если не задан ставится VCR
session_code string Необязательный Номер кассовой смены в системе клиента
cashier_name string Необязательный ФИО кассира в системе клиента. Если не задан, ставится имя пользователя под котором выполняется запрос
seller_name string Необязательный Имя продавца в системе клиента (может быть передана пустая строка)
positions Array of positions Обязательный Позиции номенклатуры - массив объектов positions
payments Array of payments Обязательный Позиции оплаты - массив объектов payments
custom_variables Array of custom_variables Необязательный Клиентские переменные для печати чека - массив объектов custom_variables


positions

Модель, описывающая позиции номенклатуры в чеке.

Название Тип данных Обязательность Описание параметра
name string Обязательный Наименование номенклатуры
barcode string Обязательный Штрих-код в формате EAN-13
code string Необязательный Код номенклатуры
articul string Необязательный Артикул
unit_name string Необязательный Наименование единицы измерения
size_name string Необязательный Наименование размера
brand_name string Необязательный Наименование бренда
producer_name string Необязательный Наименование производителя
color_name string Необязательный Наименование цвета
country_name string Необязательный Страна производителя
department_name string Необязательный Наименование отдела
group_name string Необязательный Наименование группы номенклатуры
type_name string Необязательный Наименование типа номенклатуры
label string Необязательный Код обязательной маркировки (можно передать пустую строку)
quantity int64 Обязательный Количество в граммах. Всегда больше 0. Если label задан – то всегда 1000. Если товар штучный, то 1000 * кол-во
amount int64 Обязательный Сумма стоимости позиции без учёта скидки. Значение суммы * 100. Не может быть меньше 0
discount int64 Обязательный Сумма скидки позиции в. Значение суммы * 100. Не может быть меньше 0
vat_value int64 Обязательный Значение ставки НДС * 100. При ставке "Без НДС" отправляется значение "-1". Ставка НДС должна быть занесена на VCR


payments

Модель, описывающая позиции оплаты в чеке.

Название Тип данных Обязательность Описание параметра
type Int64 Обязательный Форма оплаты в VCR: 1 (наличные), 2 (терминал)
value int64 Обязательный Сумма оплаты. Значение суммы * 100. Не может быть меньше 0


custom_variables

Модель, описывающая клиентские переменные в чеке.

Название Тип данных Обязательность Описание параметра
name string Обязательный Наименование переменной
value string Обязательный Значение переменной

Добавляемые переменные в чеки согласуются с сотрудниками ЦТО, кроме того содержимое чека не должно нарушать требования ПКМ Республики Узбекистан №943 от 23.11.2020.

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

{
    "id":1,
    "auth":"a2Fzc2E6MTIzNDU2Nzhh",
    "method":"Receipt.Refund",
    "params":
    {
        "code":"1-0000783",
        "pos_id":"00027",
        "session_code":"1-0000086",
        "cashier_name":"Administrator",
        "seller_name":null,
        "positions":
        [
            {
                "name":"Coca-cola",
                "barcode":"000001",
                "code":"000001",
                "articul":"",
                "unit_name":"шт",
                "size_name":null,
                "brand_name":null,
                "producer_name":"Coca Cola",
                "color_name":null,
                "country_name":null,
                "department_name":null,
                "group_name":"Напитки",
                "type_name":"Товар",
                "label":"",
                "quantity":1000,
                "amount":900000,
                "discount":0,
                "vat_value":1500
            }
        ],
        "payments":
        [
            {
                "type":1,
                "value":900000
            }
        ],
        "custom_variables":null
    },
    "jsonrpc":"2.0"
}

Выходные параметры

Название Тип данных Описание параметра
id string id созданного чека в REGOS: VCR

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

{
    "id":1,
    "ok":true,
    "result":
    {
        "id":"58847e73-b40b-4746-8a07-44582991bd6b"
    },
    "jsonrpc":"2.0"
}


receipt.duplicate

Печать дубликата чека.

Входные параметры

Название Тип данных Обязательность Описание параметра
id string Обязательный Id чека в REGOS: VCR

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

{
    "id":1,
    "auth":"a2Fzc2E6MTIzNDU2Nzhh",
    "method":"receipt.duplicate",
    "params":
    {
        "id":"58847e73-b40b-4746-8a07-44582991bd6b"
    },
    "jsonrpc":"2.0"
}

Выходные параметры

Метод не имеет выходных параметров.

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

{
    "id":1,
    "ok":true,
    "result":null,
    "jsonrpc":"2.0"
}


zreport.getinfo

Информация о текущем ZReport-e.

Входные параметры

Метод не имеет входных параметров.

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

{
    "id":1,
    "jsonrpc":"2.0",
    "method":"ZReport.GetInfo",
    "params":null,
    "auth":"a2Fzc2E6MTIzNDU2Nzhh"
}

Выходные параметры

Название Тип данных Описание параметра
TerminalID string Уникальный номер фискального модуля
Number int64 Номер последнего ZReport
Count int64 Количество ZReport на фискальном модуле
CloseTime string Дата и время закрытия ZReport в формате YYYY-MM-DD hh:mm:ss. Пустая строка, если ZReport не закрыт
LastReceiptSeq int64 ID последнего чека в фискальном модуле за ZReport. 0 – если Zreport не открыт или в ZReport не было отправлено ни одного чека
FirstReceiptSeq int64 ID первого чека в фискальном модуле за ZReport. 0 – если Zreport не открыт или в ZReport не было отправлено ни одного чека
OpenTime string Дата и время открытия ZReport в формате YYYY-MM-DD hh:mm:ss. Пустая строка, если ZReport не открыт
TotalRefundVat int64 Сумма НДС по чекам возврата * 100 за текущий ZReport
TotalRefundCard int64 Сумма оплат терминалом по чекам возврата * 100 за текущий ZReport
TotalRefundCash int64 Сумма оплат наличными по чекам возврата * 100 за текущий ZReport
TotalRefundCount int64 Количество чеков возврата за текущий ZReport
TotalSaleVat int64 Сумма НДС по чекам продажи * 100 за текущий ZReport
TotalSaleCard int64 Сумма оплат терминалом по чекам продажи * 100 за текущий ZReport
TotalSaleCash int64 Сумма оплат наличными по чекам продажи * 100 за текущий ZReport
TotalSaleCount int64 Количество чеков продажи за текущий ZReport

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

{
    "id":1,
    "ok":true,
    "result":
    {
        "TerminalID":"UZ16763345345",
        "Number":69,
        "Count":69,
        "CloseTime":"",
        "LastReceiptSeq":357,
        "FirstReceiptSeq":329,
        "OpenTime":"2020-11-20 16:02:27",
        "TotalRefundVat":234782,
        "TotalRefundCard":0,
        "TotalRefundCash":2160000,
        "TotalRefundCount":4,
        "TotalSaleVat":1177315,
        "TotalSaleCard":30100,
        "TotalSaleCash":13175000,
        "TotalSaleCount":25
    },
    "jsonrpc":"2.0"
}


zreport.close

Закрытие ZReport-а.

Входные параметры

Метод не имеет входных параметров.

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

{
    "id":1,
    "jsonrpc":"2.0",
    "method":"ZReport.Close",
    "params":null,
    "auth":"a2Fzc2E6MTIzNDU2Nzhh"
}

Выходные параметры

Название Тип данных Описание параметра
id Int64 id ZReport-а
open_time string Дата и время открытия в формате YYYY-MM-DD hh:mm:ss
close_time string Дата и время закрытия в формате YYYY-MM-DD hh:mm:ss

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

{
    "id":1,
    "ok":true,
    "result":
    {
        "id":69,
        "open_time":"2020-11-20 16:02:27",
        "close_time":"2020-12-01 13:10:01"
    }
    ,
    "jsonrpc":"2.0"
}


zreport.open

Открытие ZReport-а.

Входные параметры

Метод не имеет входных параметров.

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

{
    "id":1,
    "jsonrpc":"2.0",
    "method":"ZReport.Open",
    "params":null,
    "auth":"a2Fzc2E6MTIzNDU2Nzhh"
}

Выходные параметры

Название Тип данных Описание параметра
id Int64 id ZReport-а
open_time string Дата и время открытия в формате YYYY-MM-DD hh:mm:ss
close_time string NULL

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

{
    "id":1,
    "ok":true,
    "result":
    {
        "id":70,
        "open_time":"2020-12-01 13:16:12",
        "close_time":null
    },
    "jsonrpc":"2.0"
}