# Аккаунт и команда

Ключи и баланс принадлежат **аккаунту**. **Участники** входят в кабинет с ролями: владелец,
администратор, разработчик, наблюдатель. Роль ограничивает действия в кабинете; ключами
пользуются владелец, администратор и разработчик. Перевод участника в наблюдатели отзывает
его ключи вместе с ключом плейграунда, а запрос ключом участника ниже разработчика —
`403 forbidden` с `insufficient_role`. У участника — лимит трат на все его ключи, у ключа —
свой потолок.

## Номер аккаунта

У каждого аккаунта есть номер в виде автомобильного: «К 482 МТ · 77» — буква, три цифры,
две буквы и код региона РФ из двух или трёх цифр («Р 105 ОС · 761»). Номер выдаётся при
открытии аккаунта; назовите его, когда пишете в поддержку. Буквы — только А, В, Е, К, М, Н, О, Р, С, Т, У, Х: у них одно
начертание в кириллице и латинице, поэтому номер можно набрать в любой раскладке, с
пробелами или без. В API — `account.number` в `GET /v1/auth/me`.

## Регистрация

Регистрация открыта, паролей нет: первый вход на [souz.ai](https://souz.ai) через Яндекс,
GitHub, Google или Telegram создаёт аккаунт с приветственным бонусом. Ссылка-приглашение от команды Союза (`https://souz.ai/join/<код>`) даёт
свой стартовый бонус; бонусы не суммируются — стартовый бонус один на аккаунт: новый получает
больший из двух, уже получивший приветственный по ссылке — только разницу.

## Команда

Участника добавляют ссылкой-приглашением: владелец или администратор в кабинете («Аккаунт» →
«Команда» → «Пригласить») выбирает роль — администратор, разработчик или наблюдатель — и срок,
от часа до недели, по умолчанию сутки. Ссылка `https://souz.ai/join/team/<код>` одноразовая,
показывается один раз; действующие ссылки видны списком, любую можно отозвать. Человек
открывает ссылку, нажимает «Принять» и входит любым способом — вход заводит его участником
команды. Человек состоит в одном аккаунте: если у него уже есть аккаунт, принять ссылку нельзя.

## Пополнение

Пополняют владелец и администратор в кабинете. После подтверждения оплаты зачисляется вся
сумма, комиссию платит Союз. Кассовый чек формируется один
раз — при оплате; списания за запросы чеков не создают.

## История операций

Пополнения, списания за завершённые запросы, возвраты остатка и отмены начислений — в
кабинете и `GET /v1/balance/history` (ключом управления). У пополнения виден источник —
оплата или бонус — и объект `topup`: остаток (`remaining_micro`), возвращено
(`refunded_micro`), к возврату (`refund_pending_micro`), отменено (`reversed_micro`), ссылка
на чек (`receipt_url`) и способ оплаты (`method`: `card`, `sbp`, `other`), когда известны.
У бонуса от службы поддержки — подпись `label`: `topup_bonus` (бонус к пополнению),
`compensation` (компенсация за запрос, его id — в `job_id`), `bonus`. Отмена начисления
(`kind: reversal`, `source` — что отменено) уменьшает баланс, баланс при этом не уходит в
минус. Бонус расходуется первым и не возвращается. Неизрасходованные оплаченные деньги
возвращает поддержка с учётом незавершённых запросов.

## Блокировка

Служба поддержки может заблокировать аккаунт или отдельный ключ. У заблокированного
аккаунта новые запросы его ключей и плейграунда получают `403 account_blocked`; уже
принятые запросы выполняются, чтение задач, результатов, баланса и истории работает, вход в
кабинет остаётся (`GET /v1/auth/me` → `account.blocked`). Запросы заблокированным ключом
получают `403 key_blocked`, в списке ключей у него `blocked: true`, и включить его снова
нельзя. Снять блокировку — через поддержку.

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.