# Подключение Компании

Режим `COMPANY` — общее подключение компании к Битрикс24, которое держит администратор аккаунта. Страница описывает, чем этот режим отличается от личного подключения `PERSONAL`. Остальные страницы раздела [Partner Connect](/docs/partner-connect) описывают выдачу в режиме `PERSONAL`.

## Режим подключения

Новые клиенты используют режим `PERSONAL`: согласие и ключ принадлежат пользователю. Режим `COMPANY` подготавливает общее подключение компании к Битрикс24.

- Режим устанавливает только администратор платформы.
- Режим требует клиента `CONFIDENTIAL`, секрета клиента и PKCE `S256`.
- Вход по коду устройства несовместим с `COMPANY`: попытка включить вторую возможность отклоняется.
- Переключать режим можно, пока клиент не выдал ни одного ключа. История попыток без выдачи переключению не мешает, незавершённые попытки при переключении отменяются.
- Первая выдача закрепляет режим навсегда, даже после отзыва ключей. Попытка сменить режим возвращает `409 CONNECT_COMPANY_MODE_LOCKED` — для режима Компании зарегистрируйте нового клиента.
- Существующее подключение Компании запрещает переход обратно в `PERSONAL`.
- Ключ компании доступен и на коробочных порталах, проверенных платформой.

## Когда выдача недоступна

Если новая выдача для `COMPANY` (`CREATE` и `RECONNECT`) недоступна, приложение получает отказы:

| Шаг | Ответ |
|-----|-------|
| [`GET /v1/connect/authorize`](/docs/partner-connect/authorize) | После проверки адреса возврата — редирект на зарегистрированный `redirect_uri` с `error=access_denied`, исходным `state` и `error_description`, равным `CONNECT_COMPANY_NOT_READY` или `CONNECT_COMPANY_DISABLED`. Код авторизации не создаётся |
| [`POST /v1/connect/token`](/docs/partner-connect/token) с `grant_type=authorization_code` | HTTP 403 с кодом отказа в полях `code` и `error_description` |
| [Вход с устройства](/docs/partner-connect/device-authorize) — запуск и обмен кода | HTTP 400, `error=unauthorized_client`, `code=CONNECT_COMPANY_DEVICE_FLOW_FORBIDDEN` |
| Подтверждение согласия из сессии поддержки, действующей от имени другого пользователя | Отказ `CONNECT_COMPANY_IMPERSONATION_FORBIDDEN`, в том числе на разрешённом для поддержки аккаунте |
| Слишком много попыток | HTTP 429 `CONNECT_COMPANY_ATTEMPT_LIMITED`. Повторите после указанного времени ожидания |

Отказы входа с устройства и сессии поддержки не снимаются ни повторной попыткой, ни выбором другого аккаунта. `CONNECT_COMPANY_DISABLED` означает, что подключение недоступно для выбранного пользователя или портала. `CONNECT_COMPANY_NOT_READY` — что временные технические условия подключения ещё не выполнены. Для ротации существующего секрета действуют отдельные условия — см. [Переподключение и ротация секрета](#переподключение-и-ротация-секрета).

## Что доступно ключу компании

### Битрикс24

Ключ компании действует в Битрикс24 от имени держателя — сотрудника, который дал согласие как администратор, — в пределах согласованных прав и с возможностью записи. Битрикс24 проверяет текущие права держателя на выбранного сотрудника и объект: если держателю сняли права администратора, ключ работает с правами обычного сотрудника.

- **Готовность.** Подключению Битрикс24 не нужно право `crm`: достаточно хотя бы одного согласованного права Битрикс24, например `user`, при действующих проверках держателя и подключения. `bitrix_ready` не означает, что ключ может вызывать любой маршрут API: состав маршрутов и права на конкретные методы проверяются отдельно.
- **Проверка прав.** Перед каждым вызовом Битрикс24 платформа сверяет метод с текущим согласием, включая вспомогательные вызовы. Право `task` равнозначно `tasks`. Сокращённые права `user_basic` и `user_brief` разрешают `user.get`, но не методы, которым нужно полное `user`. Неизвестный префикс метода и метод без нужного согласия дают `403 SCOPE_MISSING` до обращения к Битрикс24.
- **Сущности.** Ключ допускается к сущностным операциям, включая `/v1/users`, `/v1/departments` и `/v1/tasks`, по согласованным правам: чтение, создание, изменение, удаление, поиск, поля, агрегация, импорт и пакетные операции — те, что поддерживает сущность. Доступные операции отмечены `x-company-access: true` в OpenAPI. Сущности, доступные только OAuth-приложениям, и отдельные собственные маршруты закрыты с `403 CONNECT_COMPANY_ROUTE_FORBIDDEN`.
- **Параметр `include` и пользовательские поля** доступны в рамках текущего согласия. Данные разных подключений компании не смешиваются.
- **Запись** проверяется обычными правилами ключа партнёра, без ограничения «только чтение». Пакет с методом вне согласия отклоняется целиком до отправки команд.
- **Поиск** с оконным режимом закрыт для ключа компании: передавайте `autoWindow: false`.
- **Расширение прав.** Без нужного права ответ — `403 SCOPE_MISSING`. Чтобы добавить права, измените права приложения и попросите администратора аккаунта пройти согласие с `operation=RECONNECT`.

### Хранилище и AI

- **Хранилище** требует явного согласия на `vibe:storage`. Без него хранилище отвечает `403 CONNECT_COMPANY_STORAGE_NOT_READY`. Доступность показывает `capabilities.storage` в [опросе подключения](/docs/partner-connect/company-status) независимо от проверки держателя.
- **AI** требует согласия на `vibe:ai` и отдельного разрешения приложению. Текущую доступность показывает `capabilities.ai`.
- Выпуск производных токенов и ключей, а также управление ключами внешних моделей закрыты: `403 CONNECT_COMPANY_DERIVED_TOKEN_FORBIDDEN`.
- Неизвестные маршруты отклоняются: `403 CONNECT_COMPANY_ROUTE_FORBIDDEN`.

Эти отказы не снимаются выбором другого портала. Доступность выдачи зависит от готовности выбранного подключения.

### Уведомления и рабочее время

**Уведомления — при согласии `im`.** Доступны `POST /v1/notifications` и чтения `GET /v1/notifications`, `/v1/notifications/search`, `/v1/notifications/schema`, `/v1/notifications/groups`, `/v1/notifications/settings`.

- `POST /v1/notifications` отправляет личное уведомление или системное при `type=system`, требует `userId` получателя и `message`. Успешный ответ — `201`.
- `GET /v1/notifications` читает входящие держателя, а не общий ящик компании.
- Настройки без `userId` относятся к держателю: тогда нужно ещё согласие `user`. При явном `userId` это согласие не нужно, доступ определяет Битрикс24.

**Рабочее время — при согласии `timeman`, только чтение.** Доступны `GET /v1/workday/status`, `/v1/workday/settings`, `/v1/workday/records`, `/v1/workday/schedule`, `/v1/workday/time-control/settings`, `/v1/workday/time-control/report-settings`, `/v1/workday/time-control/users`, `/v1/workday/time-control/reports`, `/v1/workday/work-reports`, `/v1/workday/work-reports/subordinates`, `/v1/workday/work-reports/{id}`, `/v1/workday/daily-reports`, `/v1/workday/records/{recordId}/report`.

| Маршрут | Условие |
|---------|---------|
| `/v1/workday/status`, `/v1/workday/settings` | Без `userId` читают данные держателя |
| `/v1/workday/records` | Требует `userId` и одно из согласий `user_brief`, `user_basic`, `user`, даже при пустой странице |
| `/v1/workday/time-control/users` | Требует `departmentId` и согласие `department` |
| `/v1/workday/schedule` | Требует `id` |
| `/v1/workday/time-control/reports` | Требует `userId`, `month`, `year` |
| `/v1/workday/work-reports`, `/v1/workday/daily-reports`, `/v1/workday/work-reports/{id}` | Требуют `userId` |
| `/v1/workday/work-reports/subordinates` | Читает отчёты подчинённых держателя |

Недостаточное согласие возвращает `403 SCOPE_MISSING`. Остальные действия уведомлений и изменения рабочего времени ключу компании недоступны и возвращают `403 CONNECT_COMPANY_ROUTE_FORBIDDEN`. Ответы ключу компании содержат `Cache-Control: no-store`.

## Кто подключён

Успешный ответ `POST /v1/connect/token` в режиме `COMPANY` содержит объекты `portal` и `user` на верхнем уровне. В ответе [`GET /v1/connect/company/status`](/docs/partner-connect/company-status) эти объекты находятся в `data`. Имена и почта берутся из учётной записи платформы — это не профиль из Битрикс24 и не список сотрудников.

**Кого показывает `user`:**

- При `CREATE` — администратора, давшего согласие.
- При `RECONNECT` — администратора, принявшего новое согласие.
- При `ROTATE_SECRET` другим администратором — прежнего держателя согласия: ротация сама по себе согласие не передаёт.

Отсутствующая почта приходит пустой строкой.

**`user` равен `null`**, если текущего согласия нет, оно завершено или относится к другому поколению, держатель отсутствует, заблокирован, удалён или его `erasureState` отличается от `ACTIVE`, либо членство держателя не готово. Устаревшая или не пройденная проверка держателя сама по себе личность не меняет. Состояние `NEEDS_ADMIN` без согласия возвращает сведения о Битрикс24 и `user: null`.

**Снимок, а не кэш.** Объекты описывают состояние на момент ответа. Изменение имени или почты не обязано увеличивать `revision`, поэтому не используйте `revision` для кэширования профиля. Ответы обмена и статуса, включая отказы, приходят с `Cache-Control: no-store`. Поля не открывают дополнительных маршрутов и не продлевают проверку держателя. `api_key` возвращается однократно при `CREATE` и `ROTATE_SECRET` и отсутствует при `RECONNECT`. Ошибки обмена не содержат `portal` и `user`.

Пример успешного ответа `CREATE` в режиме `COMPANY` — секрет ниже фиктивный. `bitrix_ready: false` описывает доступность этого подключения и не открывает выдачу.

```json
{
  "connection_mode": "COMPANY",
  "connection_id": "connection-id",
  "portal": { "domain": "example.bitrix24.com", "name": "Example" },
  "user": { "name": "Admin", "email": "admin@example.com" },
  "status": "ACTIVE",
  "generation": 1,
  "credential_version": 1,
  "credential_unchanged": false,
  "bitrix_ready": false,
  "scope": "crm",
  "api_key": "FAKE-example-only"
}
```

## Переподключение и ротация секрета

Пока новая выдача недоступна, `CREATE` и `RECONNECT` получают отказы из раздела [Когда выдача недоступна](#когда-выдача-недоступна), а ротация секрета для существующего подключения работает.

[`GET /v1/connect/authorize`](/docs/partner-connect/authorize) принимает параметр `operation`:

| `operation` | Что делает |
|-------------|------------|
| `CREATE` | Новое подключение. Значение по умолчанию |
| `RECONNECT` | Новое согласие администратора. Прежний секрет сохраняется: переподключение не устраняет его возможную кражу |
| `ROTATE_SECRET` | Замена секрета. Согласованные права сохраняются и не расширяются. Требует `credential_version`, равный текущей версии. Остаётся доступной для существующего подключения при закрытой новой выдаче, если остальные проверки пройдены |

Все операции требуют серверного клиента с секретом, PKCE `S256`, действующего согласия и свежей проверки прав администратора Битрикс24.

- Для `CREATE` и `RECONNECT` код авторизации выдаётся только после того, как платформа сохранила кандидата на подключение и обязательство очистить прежний вебхук.
- Ротация меняет секрет без нового вебхука.
- Дополнительные права при `RECONNECT` требуют отдельного явного согласия на экране.
- Первый обмен и успешная ротация показывают секрет один раз.

**Отказы:**

| HTTP | Код | Что произошло |
|------|-----|---------------|
| 409 | `CONNECTION_GENERATION_CONFLICT` | Победила другая попытка. Секрет не возвращается, проигравший кандидат отзывается. Начните новую авторизацию |
| 409 | `CONNECTION_WEBHOOK_CLEANUP_PENDING` | Достигнут предел незавершённой очистки. Дождитесь её завершения |
| 403 | `CONNECTION_SCOPE_CONSENT_REQUIRED` | Дополнительные права не подтверждены явным согласием |
| 403 | `CONNECTION_SUSPENDED` | Обычное переподключение не снимает блокировку по безопасности |
| 503 | `CONNECTION_ADMIN_CHECK_UNAVAILABLE` | Права администратора проверить не удалось. Прежнее подключение сохранено |

**Очистка вебхуков.** Прежние вебхуки платформа удаляет в фоне, и доступ к Битрикс24 этим не закрывается: подключение работает через вебхук текущего держателя, пока очистка идёт. Вебхук, который удалить нечем, остаётся записанным долгом очистки, и `webhook_cleanup` показывает для него `pending`. Если результат создания вебхука неизвестен, обязательство очистки сохраняется, и в этом случае, пока у подключения нет рабочего вебхука, доступ к Битрикс24 закрыт с причиной `CONNECTION_WEBHOOK_CLEANUP_PENDING`. Автоматический поиск такого вебхука по метке не включён.

**Дневные потолки.** Потолки портала и подключения независимы и необязательны: `null` означает отсутствие дневного потолка, а не ноль запросов. Ноль не является допустимым значением. Общие ограничения запросов, защита от частых попыток, учёт расхода и тарификация действуют всегда. Отсутствие дневных потолков само по себе не открывает выдачу. Отказы `CONNECT_COMPANY_DISABLED`, `CONNECT_COMPANY_NOT_READY` и `CONNECT_COMPANY_ATTEMPT_LIMITED` не связаны с заданием дневного потолка.

## Уход держателя

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

**Когда подключение переходит в `NEEDS_ADMIN`.** Держатель уходит: его уволили, отключили или удалили в Битрикс24, он стал гостем или отозвал своё согласие, а также если его учётную запись на платформе перенесли или удалили. Платформа раз в несколько минут проверяет держателя его собственным ключом. Если держатель больше не может авторизоваться своим ключом и это подтвердила повторная проверка не раньше чем через 30 секунд, подключение переходит в `NEEDS_ADMIN`.

Пока проверка не прошла, доступ к Битрикс24 закрыт: опрос статуса показывает `reason_code` — `ADMIN_CHECK_REQUIRED` и `action` — `WAIT`, рабочие вызовы получают `503 ADMIN_CHECK_REQUIRED` с заголовком `Retry-After: 30`. Повторите запрос через 30 секунд. После успешной проверки доступ открывается сам.

**Что показывает опрос статуса после ухода держателя:**

- `status` — `NEEDS_ADMIN`, `reason_code` — `CONNECTION_ADMIN_REQUIRED`, `action` — `AUTHORIZE_ADMIN`.
- `generation` и `revision` выросли на 1.
- `webhook_cleanup` — `pending`, пока платформа удаляет вебхук прежнего держателя в Битрикс24 или когда удалить его нечем, либо `attention_required`, если результат создания вебхука неизвестен.

**Как восстановить доступ.** Секрет подключения остаётся действующим, менять его не нужно. Незавершённые попытки авторизации отменяются, неиспользованные коды авторизации больше не обмениваются. Возвращение человека на работу подключение не восстанавливает: доступ возвращает администратор аккаунта, пройдя согласие с `operation=RECONNECT`. Битрикс24 становится доступен сразу после этого, очистка вебхука прежнего держателя продолжается в фоне. Если в коробочном Битрикс24 нет постоянного администратора, выдайте сотруднику права администратора на время переподключения: после согласия права можно снять, подключение продолжит работать.

Отключение приложения его владельцем и блокировка приложения платформой переводят все его подключения Компании в `SUSPENDED` и отзывают их секреты.

## Смотрите также

- [Опрос подключения Компании](/docs/partner-connect/company-status)
- [Обменять код на API-ключ](/docs/partner-connect/token)
- [Начать авторизацию пользователя](/docs/partner-connect/authorize)
- [Partner Connect](/docs/partner-connect)
