Контракт адаптеров REGOS: VCR

Контракт 1.0 описывает загрузку товаров из внешней системы и передачу завершённых чеков и смен REGOS: VCR через адаптер.

REGOS: VCR загружает товары, передаёт завершённые продажи, возвраты и смены, а также запрашивает исходную продажу для возврата. Адаптер может быть реализован на любом языке и подключается по этому контракту без изменения REGOS: VCR.

Подключение

  1. Войдите как руководитель или администратор. Откройте «Обмен данными» → «Внешняя система».
  2. Укажите адрес адаптера и ключ доступа. Серийный номер кассы подставляется автоматически.
  3. Нажмите «Проверить связь», выберите внешнюю кассу и нажмите «Сохранить».

Сохраняйте новое подключение при закрытой смене, без незавершённого чека и неотправленных документов. Изменение ключа доступа для прежней кассы не меняет её привязку.

После сохранения товары загружаются автоматически. При запуске 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 не заменяет отсутствие поля.

Структуры товара, чека, оплат и смены приведены в разделе «Данные». Неизвестные поля игнорируются. Изменение типов, обязательности или смысла существующих полей требует новой версии контракта.