Ключ, адреса и песочница

Что нужно получить от мерчанта

Ключ выпускает владелец бизнеса в своём кабинете uget: Настройки → API-ключи внешних касс. Разработчику кассы ключ приходит уже готовым; выпустить его самому нельзя.

При выпуске владелец выбирает:

Что	Зачем это важно вам
Точку продажи	Все чеки по этому ключу записываются на неё. В запросе точку передать нельзя — она берётся из ключа. Для второй точки нужен второй ключ.
Сотрудника-автора	Чек обязан иметь автора. Обычно владелец заводит отдельного «сотрудника-интеграцию». Если этого сотрудника уволят, ключ перестанет работать.
Имя ключа	Только для владельца, чтобы он понимал, какую кассу отзывает.

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

ugetpos_a1b2c3_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

В базе uget хранится только префикс (a1b2c3) и SHA-256 секрета. Восстановить потерянный ключ нельзя — владелец выпускает новый. Префикс открытый: по нему владелец узнаёт свой ключ в списке и в настройках вашей кассы, не раскрывая секрет.

Хранение ключа на вашей стороне. Ключ долгоживущий и не истекает сам. Держите его там же, где держите пароль к своей БД: не в исходниках, не в мобильном клиенте, не в логах. Если ключ утёк — владелец отзывает его в кабинете одной кнопкой, и все запросы с ним немедленно начинают получать 401. Отзыв мгновенный, никакого «доживания» токена нет.

Адрес и общие правила

Боевой адрес	https://connect.uget.uz
Песочница	https://sandbox.uget.uz
Формат	JSON, UTF-8, Content-Type: application/json
Аутентификация	заголовок X-Api-Key в каждом запросе
Язык ошибок	заголовок Accept-Language: uz или ru (по умолчанию ru)

connect.uget.uz — то же приложение и та же база, что api.uget.uz, но отдельное имя: по нему считаются лимиты частоты, ведутся отдельные логи и при необходимости ограничивается список IP. Используйте именно его — так проблемы вашей кассы не смешиваются с трафиком мобильных приложений.

Отлаживайтесь в песочнице, а не на боевом адресе. sandbox.uget.uz — отдельный экземпляр со своей базой: там свой демо-мерчант, свои товары и опубликованный ключ, а SMS, push, фискализация и платежи работают заглушками. Продажи и возвраты, сделанные там, не касаются живых мерчантов.

Покупателей в песочнице заводите сами по тестовым номерам +998900000001 … +998900000010: OTP по ним не отправляет SMS и принимает код 112233.

Чтобы получить код «из QR» для проверки поиска по code: войдите таким номером как покупатель (POST /api/auth/otp/request, затем POST /api/auth/otp/verify с кодом 112233 — в ответе accessToken) и вызовите POST /api/consumer/pos-code с заголовком Authorization: Bearer <accessToken>. В ответе code — те же шесть цифр, что покупатель видит в приложении и что закодированы в его QR; действуют они 5 минут (expiresAt).

Ключ песочницы опубликован — данные там одноразовые:

X-Api-Key: ugetpos_pCfYNh-U_wp7bworxMa7o9y-5a1TJqxdpZJJ7aDScnSvUVDxQnlI

В песочнице уже заведены магазин с одной точкой, три товара и акция «кешбек 5%» — этого хватает, чтобы пройти весь цикл: найти клиента, показать итог, провести продажу, вернуть чек.

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

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