Интеграция кассовой системы

Документ для разработчика внешней кассовой системы, которая хочет начислять и списывать баллы uget на своём экране. Всё, что нужно: получить ключ, вызвать пять запросов, правильно обработать повторы и ошибки.

---

Что даёт интеграция

Касса магазина остаётся вашей: свой чек, своя смена, своя фискализация. uget добавляет к ней программу лояльности мерчанта:

• кассир находит клиента по коду из QR (шесть цифр из приложения uget) или по номеру телефона;
• до пробития чека видит скидку по акциям, сколько баллов можно списать и сколько начислится;
• при оформлении продажи баллы списываются в оплату, а кешбек начисляется;
• пробитый чек можно вернуть: кешбек снимается, списанные баллы возвращаются клиенту;
• состояние любого своего чека можно перечитать — для сверки после обрыва связи.

Отдельно от этих запросов работают вебхуки (вебхуки): uget сам сообщает вашей системе о продажах и возвратах, включая те, что прошли мимо вашего API — на кассе uget, в приложении, по QR.

Чего интеграция не делает: не открывает кабинет мерчанта, не управляет товарами, не выдаёт отчёты. Ключ умеет ровно пять операций ниже и ничего больше.

Порядок работы кассы

1. Кассир собрал корзину.
2. Клиент предъявил QR (сканер отдаёт шесть цифр) → GET /consumers/resolve?code=…; QR нет — телефон → GET /consumers/resolve?phone=… (без этого шага предпросмотр и продажа с consumerId вернут 422). Не нашли → продолжаем без клиента.
3. POST /sales/preview → показываем скидку, доступные к списанию баллы и будущий бонус.
4. Кассир (или клиент) выбрал, сколько баллов списать — не больше maxRedeemPoints.
5. Нажали «Оплатить» → генерируем idempotencyKey и сохраняем его рядом с чеком.
6. POST /sales → берём cashPaid деньгами, печатаем свой чек.
7. Обрыв связи → повторяем шаг 6 с тем же ключом. 409 с existingSaleId = продажа прошла.

Если uget недоступен совсем, продажу проводите как обычно, без лояльности: начислить баллы задним числом нельзя, зато клиент не останется у кассы без чека.

С чего начать

1. Получите ключ и адрес песочницы
2. Пройдите цикл: найти клиента → итоги → продажа → возврат
3. Обработайте повторы и ошибки
4. При необходимости подключите вебхуки
5. Сверьтесь с чек-листом запуска