Разделите роли систем до интеграции

Хорошая интеграция начинается не с перечня API-методов, а с ответа на вопрос: какая система за что отвечает. POS фиксирует заказ и продажу. QR CTRL управляет цифровым правом на розлив и проверяет его в момент использования. Контроллер исполняет решение на оборудовании.

Если эти роли смешать, логика refill начинает дублироваться сразу в нескольких системах. Тогда любое изменение правила требует синхронных доработок и увеличивает количество труднообъяснимых ошибок.

Какое событие должно создавать право

Нужно точно определить коммерческое событие, после которого гость получает доступ. Это может быть продажа отдельного напитка, конкретного комбо, тарифа или другой позиции. Важно заранее решить, что происходит при отмене, возврате и изменении заказа.

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

Какие идентификаторы нужны

Системам нужен способ связать событие продажи, созданное право и последующие операции. Обычно для этого используются идентификатор заказа или строки заказа, идентификатор точки, тип продукта и уникальный идентификатор самого права.

Конкретный состав зависит от архитектуры заказчика. Критично другое: идентификаторы должны позволять однозначно разобрать спорный случай постфактум. Если в логе нельзя ответить, к какой продаже относился QR, поддержке придётся восстанавливать цепочку вручную.

Где гость получает QR-код

QR может быть напечатан на чеке, показан на экране, выдан в приложении или другом интерфейсе. Выбор канала влияет не только на UX, но и на интеграцию.

Нужно проверить размер и качество печати, срок жизни кода, повторное открытие экрана, возможность повторной печати и поведение при отмене заказа. Сам QR должен быть удобен гостю, но не обязан содержать в открытом виде всю бизнес-логику — достаточно безопасно идентифицировать право.

Что происходит после сканирования

Станция передаёт считанный идентификатор в QR CTRL. Платформа находит право и проверяет текущее состояние: срок, количество операций, интервал, точку и другие правила. Результат должен быть однозначным — разрешение либо отказ с понятной причиной для журнала и, при необходимости, пользовательского интерфейса.

Отдельно нужно определить поведение при недоступности внешних систем. Не стоит заставлять каждое сканирование синхронно обращаться к кассе, если право уже создано и может быть проверено в QR CTRL. Чем короче критический путь операции, тем устойчивее пользовательский сценарий.

Какие исключения согласовать заранее

До разработки полезно пройти несколько неприятных, но неизбежных сценариев: заказ отменён после выдачи QR; код распечатан дважды; сеть на точке нестабильна; гость сканирует просроченное право; одна операция отправлена повторно; станция временно недоступна.

Для каждого случая нужен владелец решения и понятное состояние данных. Такие вопросы дешевле закрывать на схеме, чем во время открытия ресторана.

Минимальный контракт пилота

Для первого сквозного запуска достаточно зафиксировать: событие создания права, обязательные идентификаторы, способ доставки QR, набор правил, формат ответа станции и журналирование результата. После того как этот путь стабильно работает, интеграционный контракт можно расширять.

Когда нужен более технический контракт интеграции

Если базовая схема уже согласована, следующий уровень — идемпотентность, повторы событий, стабильные идентификаторы и обработка частичных отказов. Это разобрано отдельно в материале «Интеграция POS и системы розлива: события, идентификаторы и ошибки».

Как выглядит здоровая сквозная цепочка

Гость оплачивает заказ. POS фиксирует продажу и передаёт событие с устойчивым идентификатором. QR CTRL создаёт право, которое связано с этой покупкой. QR появляется на чеке или в другом выбранном канале. У станции сканирование возвращает тот же контекст, система проверяет состояние и отправляет решение контроллеру.

Если операция успешна, в журнале остаётся событие с идентификаторами заказа, права, точки, станции и самой операции. Если отказ — сохраняется та же связь плюс причина. Такой путь можно пройти в обе стороны без ручного поиска по времени и сумме чека.

Это и есть хороший интеграционный контракт: не максимальное количество полей, а возможность однозначно объяснить каждую операцию.