Данные контракта адаптеров

Структуры версии 1.0. Если не указано иное, поля обязательны, идентификаторы — непустые строки до 100 символов, суммы — неотрицательные int64 в тийинах. Числа не передаются строками. Необязательные поля без значения отсутствуют.

Товар

Карточка product используется в каталоге и позиции чека.

Название Тип данных Описание
code string Код карточки, 1–100 символов; используется при разборе весовых и штучных масок
name string Наименование, 1–60 символов; сохраняется без замены названием из справочника ИКПУ
barcode string Единственный штрихкод, от 0 до 21 символа; пустая строка допустима
article string Артикул, от 0 до 100 символов
price int64 Цена за одну единицу, в тийинах, включая НДС
quantity_kind string piece — штучный, weight — весовой
unit_kkm_code int64 Положительный код единицы VCR; для weight обязательно 5 — килограмм
unit_name string Название единицы, 1–100 символов; для weight — обозначение килограммов
icps string Ровно 17 ASCII-цифр
package_code string Необязательно: код упаковки ИКПУ, 1–100 символов; без него VCR выбирает допустимую упаковку при применении карточки
vat_value int64 Ставка НДС × 100 либо -1 — без НДС
owner_type int32 0 — купля-продажа; 1 — производство; 2 — услуги

unit_kkm_code должен существовать в справочнике кассы. Основные коды: 1 — штуки, 5 — килограмм; базовый список.

Для piece количество кратно 1000: 1000 означает одну штуку. Для weight значение 735 означает 0,735 кг, цена задаётся за 1 кг. Точность количества — до трёх знаков после запятой.

Повтор barcode у разных товаров допустим, но не объединяет их. В новых продажах VCR предлагает выбор при нескольких совпадениях. Для масок code должен однозначно определять карточку; неоднозначность возвращает ошибку. external_id передаётся в записи каталога или позиции отдельно от product.

Чек

Чек передаётся в событии receipt и возвращается при поиске исходной продажи. Внешние ID товаров и реквизиты позиций относятся к сохранённому документу; адаптер не пересчитывает его по текущим ценам каталога.

Название Тип данных Описание
id string Постоянный ID чека VCR, уникальный в источнике
serial_number string Серийный номер кассы REGOS: VCR, оформившей чек
cash_register_id string Внешняя касса, к которой относился чек
shift_id string Постоянный ID смены VCR
datetime string Время оформления с часовым смещением
operation string sale — продажа, refund — возврат; суммы и количество в обоих случаях положительны или нулевые по правилам поля
receipt_type int32 0 — обычный, 1 — авансовый, 2 — кредитный
original_receipt_id string Необязательно: известный ID исходной продажи для возврата; отсутствие допустимо
cashier object id и name пользователя VCR; name — 1–200 символов
positions array От 1 до 150 позиций
payments array От 0 до 150 оплат; пустой список допустим только при total=0
total int64 Итог после скидок, равен сумме positions[].amount и payments[].amount
cash_received int64 Для продажи — полученная наличная сумма до сдачи; для возврата — 0
change int64 Сдача; для возврата — 0
fiscal object receipt_no, fiscal_sign, qr_url — строковые поля со значением ***

Поля fiscal.receipt_no, fiscal.fiscal_sign и fiscal.qr_url всегда содержат ***. Для связи документов используется ID чека.

Для продажи cash_received - change равно сумме оплат с method: "cash". В payments[].amount указывается сумма без сдачи. Для возврата используются неотрицательные суммы, cash_received и change равны 0.

Позиция

Название Тип данных Описание
line_id string Постоянный ID позиции, уникальный в чеке
external_id string ID товара источника; соответствует связи карточки на момент продажи
product object Снимок товара, включая фактическую цену позиции
quantity int64 От 1 до 999999000 тысячных долей; для piece кратно 1000
discount int64 Скидка всей позиции, не одной единицы
amount int64 Стоимость позиции после скидки
labels array Считанные коды маркировки; пустой список при их отсутствии; один код — 1–2048 символов

Стоимость до скидки равна round(price × quantity / 1000) в тийинах. Округление — до целого, половины от нуля. amount равен этой стоимости минус discount и не может быть отрицательным.

Используются цена и реквизиты позиции на момент оформления чека. Адаптер не пересчитывает их по текущему каталогу.

Оплата

Название Тип данных Описание
id string Постоянный ID строки оплаты, уникальный в чеке
method string cash, card или payment_system
payment_system_id int32 ID из таблицы ниже
name string Название для отображения, 1–100 символов; сопоставление не строится только по названию
amount int64 Подтверждённая сумма оплаты/возврата без сдачи
card_type int32 Необязательно: 1 — корпоративная, 2 — личная, 3 — социальная
rrn string Необязательно: RRN, 1–100 символов
method payment_system_id Значение
cash 0 Наличные
card 0 Карта с оплатой, подтверждённой вне VCR
card -2 Uzcard (PAX)
card -1 Humo (Ingenico)
card -3 RahmatPOS
payment_system 1 PaymeGo
payment_system 2 ClickPass
payment_system 3 UzumPay
payment_system 4 AnorCheck
payment_system 5 UzQR
payment_system 6 PaynetPass
payment_system 7 KaftPay

Для сопоставления способов оплаты используются method и payment_system_id. Если способ не настроен, адаптер возвращает ошибку. Номера банковских карт и платёжные токены не передаются.

Пример события самостоятельного возврата

ИКПУ и штрихкод фиктивные. Исходный чек не найден, original_receipt_id отсутствует.

{
    "jsonrpc": "2.0",
    "method": "Event.Accept",
    "params": {
        "serial_number": "VCR-DEMO-001",
        "cash_register_id": "register-001",
        "event": {
            "created_at": "2026-11-15T10:00:00+05:00",
            "type": "receipt",
            "receipt": {
                "id": "receipt-demo-002",
                "serial_number": "VCR-DEMO-001",
                "cash_register_id": "register-001",
                "shift_id": "shift-demo-001",
                "datetime": "2026-11-15T10:00:00+05:00",
                "operation": "refund",
                "receipt_type": 0,
                "cashier": {
                    "id": "3",
                    "name": "Кассир"
                },
                "positions": [
                    {
                        "line_id": "1",
                        "external_id": "product-001",
                        "product": {
                            "code": "12345",
                            "name": "Демонстрационный весовой товар",
                            "barcode": "4780000000000",
                            "article": "",
                            "price": 1000000,
                            "quantity_kind": "weight",
                            "unit_kkm_code": 5,
                            "unit_name": "кг",
                            "icps": "00000000000000000",
                            "vat_value": 0,
                            "owner_type": 0
                        },
                        "quantity": 735,
                        "discount": 0,
                        "amount": 735000,
                        "labels": []
                    }
                ],
                "payments": [
                    {
                        "id": "payment-001",
                        "method": "cash",
                        "payment_system_id": 0,
                        "name": "Наличные",
                        "amount": 735000
                    }
                ],
                "total": 735000,
                "cash_received": 0,
                "change": 0,
                "fiscal": {
                    "receipt_no": "***",
                    "fiscal_sign": "***",
                    "qr_url": "***"
                }
            }
        }
    },
    "id": "request-006"
}

Смена

Название Тип данных Описание
id string Постоянный ID Z-отчёта VCR, общий для открытия и закрытия
number int64 Положительный номер смены для отображения; не заменяет id
opened_at string Время открытия с часовым смещением
opened_by object id и name пользователя VCR
closed_at string Только для закрытия: время не раньше opened_at
closed_by object Только для закрытия: id и name пользователя VCR
totals object Только для закрытия: итоговые данные смены

В событии shift_opened поля closed_at, closed_by и totals отсутствуют. В shift_closed все три обязательны. Исходная касса и VCR задаются общими параметрами события.

Итоги смены

Название Тип данных Описание
sale_count int64 Количество завершённых продаж, не меньше 0
refund_count int64 Количество завершённых возвратов, не меньше 0
sales_amount int64 Сумма продаж после скидок
refunds_amount int64 Сумма возвратов после скидок, не меньше 0
payments array До 150 итоговых строк по способам оплаты
payments[].method string Как в оплате чека
payments[].payment_system_id int32 Как в оплате чека
payments[].name string Название способа
payments[].sales_amount int64 Сумма продаж по способу
payments[].refunds_amount int64 Сумма возвратов по способу

Суммы sales_amount и refunds_amount равны соответствующим суммам строк payments. Счётчики и итоги включают обычные, авансовые и кредитные чеки, оформленные в этой смене. Внесение, изъятие и начальный остаток наличных в эти итоги не включаются.

Пример события закрытия

{
    "jsonrpc": "2.0",
    "method": "Event.Accept",
    "params": {
        "serial_number": "VCR-DEMO-001",
        "cash_register_id": "register-001",
        "event": {
            "created_at": "2026-11-15T18:00:00+05:00",
            "type": "shift_closed",
            "zreport": {
                "id": "shift-demo-001",
                "number": 29,
                "opened_at": "2026-11-15T09:00:00+05:00",
                "opened_by": {
                    "id": "3",
                    "name": "Кассир"
                },
                "closed_at": "2026-11-15T18:00:00+05:00",
                "closed_by": {
                    "id": "3",
                    "name": "Кассир"
                },
                "totals": {
                    "sale_count": 0,
                    "refund_count": 1,
                    "sales_amount": 0,
                    "refunds_amount": 735000,
                    "payments": [
                        {
                            "method": "cash",
                            "payment_system_id": 0,
                            "name": "Наличные",
                            "sales_amount": 0,
                            "refunds_amount": 735000
                        }
                    ]
                }
            }
        }
    },
    "id": "request-007"
}