Быстрый старт

Путь подключения

1. Владелец ресторана регистрирует ваше устройство в Sitora Biz за одной кассой, объявляя его возможности и (для смарт-кассы) ссылку запуска соседнего платёжного приложения.
2. Владелец выпускает одноразовый код подключения и читает его вам или вводит на устройстве.
3. Ваше устройство один раз гасит код и получает учётные данные — показанные ровно один раз.
4. Опрашивайте, действуйте, отчитывайтесь.
5. Пройдите набор проверок соответствия. Успешный прогон записывается как артефакт сертификации по каждой возможности.

Песочница

Попросите у Sitora песочницу — и установка подготовит вам тестовый филиал. В нём есть касса, экран для гостя, компаньон на смарт-кассе, кассир, у которого действительно есть право на приём денег, и конфигурация провайдера в его тестовой среде. Учётные данные устройств и вход кассира выдаются один раз.

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

Первые запросы

# 1. Погасить одноразовый код подключения (анонимно — код и есть секрет)
curl -X POST -H 'Content-Type: application/json' \
  -d '{"code":"<enrollment-code>"}' \
  "https://<host>/api/payments/v1/devices/enroll/"

# 2. Отметиться. Делайте это по таймеру — три минуты без heartbeat, и
#    устройство считается офлайн, поэтому маршруты, которым оно нужно,
#    перестают предлагаться кассиру. Раз в 30 секунд оставляет запас на потерю
#    пакета.
curl -X POST -H "Authorization: Bearer sit_pd_..." \
  -H 'Content-Type: application/json' -d '{"summary":{"battery":91}}' \
  "https://<host>/api/payments/v1/devices/heartbeat/"

# 3. Опросить работу (смарт-касса)
curl -H "Authorization: Bearer sit_pd_..." \
  -H 'If-None-Match: "<last-etag>"' \
  "https://<host>/api/payments/v1/devices/assignment/"

# 3b. …или то, что должен видеть гость (экран для гостя)
curl -H "Authorization: Bearer sit_pd_..." \
  "https://<host>/api/payments/v1/devices/display/"

# 4. Сообщить, что вернуло платёжное приложение
curl -X POST -H "Authorization: Bearer sit_pd_..." \
  -H 'Content-Type: application/json' \
  -d '{"intent_id":42,"outcome":"reported_success",
       "provider_reference":"RRN-000123","provider_code":"00",
       "client_idempotency_key":"collection-42-1"}' \
  "https://<host>/api/payments/v1/devices/assignment/report/"

Шаг 4 не оплачивает заказ. См. передачу на смарт-кассу.

Этикет опроса

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

Частоту задаёт Sitora, а не вы. Каждый ответ обоих чтений — и 200, и 304 — несёт число секунд, которые надо подождать до следующего запроса, в двух заголовках с одним и тем же числом:

X-Sitora-Poll-After: <секунды>
Retry-After: <секунды>

Подождите столько и опрашивайте снова, и не зашивайте значение в код: Sitora может поднять его сразу для всего парка без вашего релиза — так загруженный день решается замедлением устройств, а не отказом им. Сегодня экран просит две секунды, а компаньон — три. Retry-After в успешном ответе — это темп, а не ошибка.

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

Проверки соответствия

Сертификация зарабатывается в песочнице. Sitora по запросу прогоняет там набор проверок, и он ведёт себя на живом API как кассир, как устройство и как владелец филиала. Среди прочего он проверяет:

• приём наличных и подтверждённого терминала, проходящий через единственный платёжный шов Sitora;
• передачу на смарт-кассу, включая то, что сообщённый успех оставляет заказ неоплаченным, пока его не подтвердит кассир;
• идемпотентное повторение дублирующего отчёта;
• платёж по динамическому QR, подтверждённый настоящим обратным вызовом провайдера, и дублирующий вызов, повторяющийся один в один;
• деньги, которые провайдер заявляет по транзакции, никогда не зарегистрированной в Sitora, всплывающие как проблема несопоставленных денег, а не молча оплачивающие что-нибудь;
• соблюдение аварийного выключателя, включая то, что наличные продолжают приниматься сквозь заморозку платформы;
• офлайновое устройство, снимающее собственные маршруты, и heartbeat, возвращающий их;
• сверку с загруженной выпиской провайдера, дающую имя каждому расхождению, и закрытое расхождение, которое не возвращается на следующем прогоне.

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

Записанный прогон пишет по одному неизменяемому артефакту сертификации на каждую задействованную возможность. Сертификация идёт по паре провайдер × возможность: успех для одного аппаратного глагола никогда не сертифицирует другой.