Организации

Организация в AI Gateway — это рабочее пространство с общим рублёвым балансом, API-ключами и единым учётом использования AI Gateway. После регистрации первый пользователь становится администратором: он пополняет баланс, создаёт ключи, смотрит расходы и работает со счетами и документами. Роль участника предназначена для выданных ему доступов и не даёт права управлять общими ключами, биллингом или аналитикой организации.

Главное отличие от сервисов с личным и корпоративным режимами: в текущем кабинете AI Gateway нет переключателя между несколькими организациями и нет отдельной кнопки «Создать организацию». Рабочее пространство подготавливается автоматически при регистрации в AI Gateway.

Начало работы с организацией

1. Откройте регистрацию AI Gateway.
2. Укажите email и пароль, пройдите проверку и подтвердите согласие на обработку персональных данных.
3. Введите код, который придёт на email.
4. После подтверждения адреса AI Gateway автоматически создаст организацию со статусом active и добавит вас как активного участника с ролью admin.
5. Перейдите в кабинет, пополните баланс и создайте первый API-ключ.

Создание идемпотентно: повторный вход не создаёт ещё одну организацию. Если рабочее пространство по какой-то причине не было подготовлено сразу после подтверждения email, кабинет повторяет эту операцию при открытии организационных разделов.

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

Участники и роли

В AI Gateway используются ровно две роли:

Права действуют для активного членства. Само рабочее пространство также должно иметь статус active; для заблокированной или архивной организации административные операции ограничены.

Как принимается приглашение

Если вы получили действительную ссылку-приглашение, войдите с тем же email, на который оно оформлено. После входа AI Gateway проверяет токен, адрес, срок действия и состояние организации, а затем создаёт активное членство с ролью, записанной в приглашении.

Приглашение проходит через состояния pending, accepted, expired или cancelled. Принять можно только приглашение со статусом pending, которое ещё не истекло. Попытка войти с другим email завершится ошибкой invite_email_mismatch.

Новый пользователь после обычной регистрации уже получает своё пустое рабочее пространство. При принятии приглашения AI Gateway может автоматически архивировать его только тогда, когда оно действительно пустое: в нём нет ключей, использования, денег, пополнений, счетов, документов, реквизитов и других участников. Если рабочее пространство уже использовалось, присоединение останавливается с кодом workspace_not_empty; обратитесь в поддержку, чтобы не потерять данные или деньги.

В текущем пользовательском кабинете нет самостоятельных действий для создания, повторной отправки и отмены приглашений, смены роли или удаления участника. Поэтому не планируйте эти операции как часть доступного интерфейса. Для добавления участника, смены администратора или ухода последнего администратора используйте поддержку. Ограничение «последнего администратора» и самостоятельная передача владения в текущих пользовательских маршрутах не реализованы.

Общий баланс и биллинг

Все запросы по организационным API-ключам оплачиваются из одного баланса организации. Списание создаётся по фактически учтённому использованию ключа; подробнее о связи запросов, токенов и финансовых записей читайте в материале об учёте использования.

Балансом управляет только admin. В разделе «Биллинг» администратор видит текущий остаток, историю операций и прогноз, может пополнить счёт картой или выставить счёт для оплаты с расчётного счёта.

Эти способы пополнения проходят по разным контурам:

• оплата картой создаёт отдельную сессию пополнения баланса организации; после успешного платежа на баланс проводится карточное пополнение;
• оплата по счёту создаёт банковский документ; баланс увеличивается после сопоставления поступившей банковской операции со счётом;
• расходы AI Gateway проводятся отдельными записями usage_charge.

Не считайте созданный PDF-счёт подтверждением пополнения: деньги появятся на балансе только после обработки платежа. Администратор может скачать PDF, отправить счёт на email и отменить счёт, пока его состояние это допускает.

Если баланс закончится или будет достигнут лимит расходов, новые запросы могут быть отклонены. Практика контроля и коды ошибок описаны в руководстве по лимитам API. Актуальные цены моделей проверяйте на странице цен и в каталоге моделей.

Управление API-ключами

Организационные ключи создаёт и обслуживает только активный admin. Обычный member не может создавать ключи, просматривать весь список ключей организации или управлять ими.

Рабочий порядок такой:

1. Откройте раздел API-ключей в кабинете.
2. Создайте ключ с понятным названием, например prod-orders или stage-support-bot.
3. Скопируйте полный секрет сразу: он показывается только один раз.
4. Сохраните его в защищённом хранилище приложения, а не в коде, чате или задаче.
5. Используйте ключ в заголовке Authorization по инструкции об авторизации.

В кабинете администратор может:

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

Отключение обратимо, удаление — нет. История использования остаётся для учёта, но удалённый секрет восстановить нельзя. Для плановой замены используйте отдельную инструкцию по ротации API-ключей.

В текущем интерфейсе нет автоматической ротации, отдельного ключа управления и настройки срока действия. Не стройте процесс вокруг несуществующего Management API: для смены секрета создайте новый ключ, переведите приложения, проверьте трафик, отключите старый и только потом удалите его.

Активность и аналитика

Организационные данные использования доступны только admin в двух разделах:

• «Использование» помогает найти отдельные учтённые операции по диапазону дат, точному ID ключа и model_id; в строках видны модель, ключ, токены, стоимость и связь с финансовым списанием;
• «Аналитика» показывает сводку за 7, 30, 90 дней или собственный период, сравнение с предыдущим периодом, затраты, запросы, токены, ключи, модели, поставщиков и доступную разбивку токенов.

На странице аналитики можно выбрать один API-ключ или посмотреть все ключи организации и вручную запросить обновление доступных данных. Это не означает мгновенную синхронизацию: свежая операция может появиться в разных представлениях не одновременно.

Обычный участник не получает общую статистику организации. Текущий пользовательский кабинет также не предлагает выгрузку журнала или аналитики в CSV. Не передавайте участнику административный пароль ради отчёта — запросите нужную выборку у администратора.

Административные настройки

Администратор может заполнить и изменить реквизиты юридического лица или ИП в «Биллинге». В форме используются наименование, ИНН, КПП при необходимости, регистрационный номер, юридический адрес, бухгалтерский email, email административного контакта и телефон.

После заполнения реквизитов становятся доступны связанные операции:

• создание, скачивание, отправка и отмена счетов в разделе «Биллинг»;
• просмотр и скачивание сформированных закрывающих документов в разделе «Документы»;
• отображение состояния электронного документооборота.

В кабинете закрывающий документ доступен для скачивания в XML, когда файл сформирован. Подключение и изменение параметров Диадок не являются самостоятельной пользовательской настройкой: интерфейс показывает состояние ЭДО, а настройку подключения следует согласовывать через поддержку.

Реквизиты, счета, закрывающие документы и биллинг скрыты от роли member на уровне серверных проверок. Не передавайте участнику роль admin только ради просмотра одного документа: безопаснее получить документ через ответственного администратора.

Практические сценарии

Минимальная настройка для нового проекта

1. Администратор регистрируется через страницу входа и регистрации и подтверждает email.
2. При необходимости заполняет реквизиты компании.
3. Пополняет общий баланс картой или выставляет счёт.
4. Создаёт отдельный ключ для каждого приложения и каждой среды.
5. Передаёт секрет приложению через защищённое хранилище.
6. Проверяет модель и цену в каталоге и выполняет первый запрос.
7. Контролирует операции в журнале использования и общую картину в аналитике.
8. Планово меняет ключи по инструкции о ротации.

Такой минимум готовит проект к работе с клиентами: расходы отделены по приложениям, секреты не разделяются без необходимости, а у команды есть ответственный администратор.

Разделение разработки и промышленной среды

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

Подключение сотрудника без передачи общего секрета

Не рассылайте один ключ всем участникам. Если сотрудник развёртывает приложение, администратор создаёт отдельный ключ под этот сервис и помещает его в защищённое хранилище среды. Если сотруднику нужен только назначенный доступ к другому сервису, API-секрет AI Gateway ему не требуется.

Самостоятельной отправки приглашения из кабинета сейчас нет. Для оформления участия обратитесь в поддержку, укажите рабочий email и требуемую роль, но не отправляйте пароли или API-ключи.

Уход администратора

Заранее назначьте внутри компании ответственного за баланс, документы и ротацию ключей. Самостоятельной передачи роли или удаления администратора в текущем кабинете нет. До отключения корпоративного email обратитесь в поддержку, чтобы согласовать безопасную передачу управления и подтвердить полномочия.

Частые вопросы

Кто управляет ключами и оплатой?

Только активный участник с ролью admin. Он создаёт, отключает, включает и удаляет организационные API-ключи, пополняет баланс, работает со счетами и видит финансовые данные.

Может ли member видеть аналитику всей организации?

Нет. Маршруты организационного журнала использования и аналитики требуют роль admin. Участник видит свою роль и назначенные ему доступы, но не общие расходы и ключи AI Gateway.

Нужен ли участнику полный секрет API-ключа?

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

Что произойдёт, если администратор уйдёт?

В текущем пользовательском интерфейсе нет самостоятельной передачи владения, смены роли или удаления участника. Обратитесь в поддержку до отключения доступа прежнего администратора.

Можно ли состоять в нескольких организациях и переключаться между ними?

Текущий кабинет не предлагает переключатель организаций. Не переносите в AI Gateway процессы, рассчитанные на несколько рабочих пространств одного пользователя.

Где искать счета и закрывающие документы?

Счета создаются и обслуживаются администратором в «Биллинге». Сформированные закрывающие документы находятся в разделе «Документы». Для этих операций сначала заполните реквизиты организации.

Получение помощи

Если не удаётся принять приглашение, подготовить реквизиты, сопоставить банковский платёж, передать управление организацией или найти расход, обратитесь в поддержку AI Gateway.

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