Контракт адаптеров REGOS: VCR
Контракт 1.0 описывает загрузку товаров из внешней системы и передачу завершённых чеков и смен REGOS: VCR через адаптер.
REGOS: VCR загружает товары, передаёт завершённые продажи, возвраты и смены, а также запрашивает исходную продажу для возврата. Адаптер может быть реализован на любом языке и подключается по этому контракту без изменения REGOS: VCR.
Подключение
- Войдите как руководитель или администратор. Откройте «Обмен данными» → «Внешняя система».
- Укажите адрес адаптера и ключ доступа. Серийный номер кассы подставляется автоматически.
- Нажмите «Проверить связь», выберите внешнюю кассу и нажмите «Сохранить».
Сохраняйте новое подключение при закрытой смене, без незавершённого чека и неотправленных документов. Изменение ключа доступа для прежней кассы не меняет её привязку.
После сохранения товары загружаются автоматически. При запуске REGOS: VCR обмен возобновляется; следующие проверки выполняются через 5 минут после завершения предыдущей. Кнопка «Выполнить обмен» запускает отправку чеков и смен и загрузку товаров вручную; повторное нажатие останавливает обмен. Результат и число неотправленных документов отображаются в этом же разделе.
Выбранная внешняя касса определяет каталог и цены. Внешние товары связываются по external_id в пределах подключения; совпадение штрихкода или ИКПУ не объединяет карточки. При смене подключения начинается полная загрузка. Ранее созданные вручную товары сохраняются; для новых продаж при подключённом адаптере используются товары выбранной внешней кассы.
Чеки и смены
Передаются документы, завершённые после подключения обмена: открытие смены, её обычные продажи и возвраты, затем закрытие. При подключённом адаптере авансовые и кредитные чеки недоступны, в том числе через входящий API; проверка выполняется до фискализации. Состав, цены, скидки, оплаты и кассир сохраняются на момент операции; последующее обновление каталога не меняет передаваемый чек. Фискальные реквизиты передаются с маской ***.
При отсутствии связи касса продолжает работу и повторяет передачу сохранённых документов. До подтверждения текущего документа следующие события не передаются. Постоянная ошибка требует исправления адаптера и ручного запуска обмена. Повтор обмена не повторяет оплату или фискализацию.
При возврате кнопка «Найти чек» запрашивает исходную продажу. Несколько результатов выводятся для выбора. При пустом ответе или отсутствии связи кассир заполняет возвращаемые товары вручную. Поскольку контракт не раскрывает фискальные реквизиты, они указываются отдельно при оформлении возврата.
Реализация стороннего адаптера
Предоставьте HTTP-адрес с методами из таблицы ниже и настройте отдельный ключ доступа. Поддержите версию 1.0, каталог выбранной кассы, устойчивое продолжение постраничной выдачи и повторный приём документов по правилам Event.Accept. Поиск исходного чека необязателен; это указывается в receipt_lookup.
Перед подключением проверьте полную и повторную загрузку, изменение и удаление товара, продажу, возврат, смешанную оплату и закрытие смены. После потери ответа повтор того же события должен возвращать duplicate с первоначальными реквизитами подтверждения. Примеры запросов, ответов и публичных ошибок приведены на страницах методов.
Методы
REGOS: VCR отправляет запросы адаптеру. Это отдельный интерфейс: методы и токены входящего API REGOS: VCR здесь не используются.
| Метод | Назначение | Поддержка |
|---|---|---|
| Connector.GetInfo | Версия контракта и возможности адаптера | Обязательная |
| CashRegister.Get | Доступные внешние кассы | Обязательная |
| Item.GetChanges | Каталог товаров и его изменения | Обязательная |
| Receipt.Find | Поиск исходной продажи | Необязательная |
| Event.Accept | Приём завершённого чека, открытия или закрытия смены | Обязательная |
Запросы и авторизация
Используется HTTP POST на адрес адаптера, указанный в настройках. Для адаптера на этом компьютере разрешён HTTP, для сетевого адреса требуется HTTPS. Перенаправления не поддерживаются.
Authorization: Bearer <adapter-token>
Content-Type: application/json;charset=utf-8
Ключ передаётся только в заголовке. Тело запроса и ответа — JSON в UTF-8 размером не более 4 МиБ.
Каждый запрос содержит jsonrpc: "2.0", точное имя method, объект params и непустой строковый id. Имена методов и полей чувствительны к регистру. Пакетные запросы и уведомления без id не поддерживаются.
| Общий параметр | Тип данных | Где передаётся |
|---|---|---|
| serial_number | string | Во всех методах; серийный номер REGOS: VCR, 1–100 символов |
| cash_register_id | string | В Item.GetChanges, Receipt.Find и Event.Accept; ID внешней кассы, 1–100 символов |
| contract_version | string | Только в Connector.GetInfo; значение 1.0 |
В ответе возвращаются jsonrpc: "2.0", исходный id, ok и result. При ok: true результат описан на странице метода, при ok: false — в перечне ошибок. Ошибка метода может возвращаться с HTTP 200, поэтому проверяйте ok.
Форматы данных
- ID и серийные номера — строки с учётом регистра. Числовой ID внешней системы также передаётся строкой.
- Деньги —
int64в тийинах; количество —int64в тысячных долях единицы; НДС —int64в сотых долях процента. Значение НДС-1означает «без НДС». - Время — RFC 3339 с секундами и часовым смещением, например
2026-11-15T10:00:00+05:00или2026-11-15T05:00:00Z. Допускаются до семи знаков долей секунды. - Числовые строки и дробные числа вместо целочисленных значений не принимаются. Необязательные поля без значения не передаются;
nullне заменяет отсутствие поля.
Структуры товара, чека, оплат и смены приведены в разделе «Данные». Неизвестные поля игнорируются. Изменение типов, обязательности или смысла существующих полей требует новой версии контракта.