Для AI-агентов: markdown этой страницы — /docs-content/partner-connect/company.md индекс документации — /llms.txt
Подключение Компании
Режим COMPANY — общее подключение компании к Битрикс24, которое держит администратор аккаунта. Страница описывает, чем этот режим отличается от личного подключения PERSONAL. Остальные страницы раздела Partner Connect описывают выдачу в режиме PERSONAL.
Режим подключения
Новые клиенты используют режим PERSONAL: согласие и ключ принадлежат пользователю. Режим COMPANY подготавливает общее подключение компании к Битрикс24.
- Режим устанавливает только администратор платформы.
- Режим требует клиента
CONFIDENTIAL, секрета клиента и PKCES256. - Вход по коду устройства несовместим с
COMPANY: попытка включить вторую возможность отклоняется. - Переключать режим можно, пока клиент не выдал ни одного ключа. История попыток без выдачи переключению не мешает, незавершённые попытки при переключении отменяются.
- Первая выдача закрепляет режим навсегда, даже после отзыва ключей. Попытка сменить режим возвращает
409 CONNECT_COMPANY_MODE_LOCKED— для режима Компании зарегистрируйте нового клиента. - Существующее подключение Компании запрещает переход обратно в
PERSONAL. - Ключ компании доступен и на коробочных порталах, проверенных платформой.
Когда выдача недоступна
Если новая выдача для COMPANY (CREATE и RECONNECT) недоступна, приложение получает отказы:
| Шаг | Ответ |
|---|---|
ШагGET /v1/connect/authorize |
ОтветПосле проверки адреса возврата — редирект на зарегистрированный redirect_uri с error=access_denied, исходным state и error_description, равным CONNECT_COMPANY_NOT_READY или CONNECT_COMPANY_DISABLED. Код авторизации не создаётся |
ШагPOST /v1/connect/token с grant_type=authorization_code |
ОтветHTTP 403 с кодом отказа в полях code и error_description |
| ШагВход с устройства — запуск и обмен кода | Ответ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в опросе подключения независимо от проверки держателя. - 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 эти объекты находятся в 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 описывает доступность этого подключения и не открывает выдачу.
{
"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 принимает параметр operation:
operation |
Что делает |
|---|---|
operationCREATE |
Что делаетНовое подключение. Значение по умолчанию |
operationRECONNECT |
Что делаетНовое согласие администратора. Прежний секрет сохраняется: переподключение не устраняет его возможную кражу |
operationROTATE_SECRET |
Что делаетЗамена секрета. Согласованные права сохраняются и не расширяются. Требует credential_version, равный текущей версии. Остаётся доступной для существующего подключения при закрытой новой выдаче, если остальные проверки пройдены |
Все операции требуют серверного клиента с секретом, PKCE S256, действующего согласия и свежей проверки прав администратора Битрикс24.
- Для
CREATEиRECONNECTкод авторизации выдаётся только после того, как платформа сохранила кандидата на подключение и обязательство очистить прежний вебхук. - Ротация меняет секрет без нового вебхука.
- Дополнительные права при
RECONNECTтребуют отдельного явного согласия на экране. - Первый обмен и успешная ротация показывают секрет один раз.
Отказы:
| HTTP | Код | Что произошло |
|---|---|---|
| HTTP409 | КодCONNECTION_GENERATION_CONFLICT |
Что произошлоПобедила другая попытка. Секрет не возвращается, проигравший кандидат отзывается. Начните новую авторизацию |
| HTTP409 | КодCONNECTION_WEBHOOK_CLEANUP_PENDING |
Что произошлоДостигнут предел незавершённой очистки. Дождитесь её завершения |
| HTTP403 | КодCONNECTION_SCOPE_CONSENT_REQUIRED |
Что произошлоДополнительные права не подтверждены явным согласием |
| HTTP403 | КодCONNECTION_SUSPENDED |
Что произошлоОбычное переподключение не снимает блокировку по безопасности |
| HTTP503 | Код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 и отзывают их секреты.