Данные контракта адаптеров
Структуры версии 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"
}