Экраны для гостя

Экран для гостя показывает гостю, что происходит на кассе. Он читает один эндпоинт и рисует то, что получил:

GET /api/payments/v1/devices/display/
If-None-Match: "<last etag>"

{
  "state": "qr",
  "order_display_number": 118,
  "amount": "100000.00",
  "currency": "UZS",
  "qr_payload": "https://checkout.example/…",
  "intent_status": "presented",
  "server_time": "2026-08-09T12:00:11Z"
}

Состояния

state	Что показывать
idle	Ваш брендинг, время, всё что захочет заведение
total	Номер заказа и сумму к оплате
qr	Сумму плюс qr_payload, нарисованный сканируемым кодом
paid	Короткое подтверждение только что оплаченной суммы

paid показывается недолго после оплаты и сам возвращается в idle. Не залипайте на нём.

qr_payload — только для устройств, которым позволено его рисовать

Полезная нагрузка включается только тогда, когда устройство объявляет qr_dynamic_present. Экран, зарегистрированный без этой возможности, получает пустую строку при каждом чтении — возможность проверяется на сервере, а не просьбой вести себя прилично. Рисуйте ровно то, что вам дали, без изменений.

Полезная нагрузка — собственная ссылка провайдера на оплату. Секрета в ней нет, и переписывать, укорачивать или заворачивать её в редирект — не ваше дело.

Опрос

Опрашивайте с If-None-Match; неизменившееся состояние отвечает 304 без тела, что делает плотный темп дешёвым.

Насколько плотный — решает Sitora, а не вы. Каждый ответ несёт X-Sitora-Poll-After и Retry-After, оба с одним и тем же числом секунд до следующего чтения — сегодня их две. Слушайтесь его и не зашивайте в код: число можно поднять сразу для всего парка без вашего релиза. Retry-After на 200 или 304 — это темп, а не ошибка. Эндпоинт вдобавок ограничен по частоте на учётные данные, но это мера последней инстанции — экран, который слушается заголовка, до неё не доходит.

Push в реальном времени намеренно не предлагается. Контракт — это опрос.

Когда платформа заморожена

Экраны существуют, чтобы показывать приём денег через провайдера, поэтому их поверхность замерзает вместе с ним: под заморозкой платформы учётным данным экрана отказывают с platform_frozen. Покажите нейтральный экран покоя и продолжайте опрашивать — заморозка снимется без единого действия с вашей стороны.

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