Для AI-агентов: markdown этой страницы — /docs-content/partner-connect/company-status.md индекс документации — /llms.txt

Опрос подключения Компании

GET /v1/connect/company/status

Позволяет серверу Продукта проверить своё подключение Компании по уже выданному секрету COMPANY. Пара аккаунта и Продукта определяется секретом.

Параметры

Метод не принимает параметры запроса, включая идентификаторы другой пары. Секрет подключения передайте только в заголовке X-Api-Key. Секрет клиента, cookie и Bearer для этого метода не подходят. Храните секрет подключения на сервере, не передавайте в браузер и не записывайте в журналы.

Примеры

Метод авторизуется секретом подключения Компании — его выдаёт POST /v1/connect/token в поле api_key. Личный ключ и ключ OAuth-приложения здесь не подходят.

curl

Terminal
curl --max-time 20 "https://vibecode.bitrix24.tech/v1/connect/company/status" \
  -H "X-Api-Key: YOUR_COMPANY_SECRET"

JavaScript

javascript
const response = await fetch('https://vibecode.bitrix24.tech/v1/connect/company/status', {
  headers: { 'X-Api-Key': 'YOUR_COMPANY_SECRET' },
  cache: 'no-store',
  signal: AbortSignal.timeout(20000),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.code)
console.log(result.data.status, result.data.revision, result.data.action)

Поля ответа

Поле Тип Значение
Полеsuccess Типboolean Значениеtrue для успешного опроса
Полеdata Типobject ЗначениеДиагностика собственного подключения
Полеdata.connection_id Типstring ЗначениеИдентификатор подключения, полученный этим методом
Полеdata.connection_mode Типstring ЗначениеВсегда COMPANY
Полеdata.portal Типobject ЗначениеПодключённый Битрикс24: только domain и name
Полеdata.portal.domain Типstring ЗначениеДомен подключённого Битрикс24
Полеdata.portal.name Типstring ЗначениеНазвание подключённого Битрикс24, Unknown, если отсутствует
Полеdata.user Типobject | null ЗначениеДержатель текущего согласия: только name и email, либо null
Полеdata.user.name Типstring ЗначениеИмя держателя в учётной записи платформы
Полеdata.user.email Типstring ЗначениеПочта держателя в учётной записи платформы, пустая строка при отсутствии
Полеdata.status Типstring ЗначениеACTIVE, NEEDS_ADMIN, SUSPENDED, DISCONNECTED, DELETION_PENDING
Полеdata.generation Типinteger ЗначениеПоколение согласия подключения
Полеdata.revision Типinteger ЗначениеЗаписанная версия состояния подключения
Полеdata.credential_version Типinteger ЗначениеВерсия текущего секрета подключения
Полеdata.bitrix_ready Типboolean ЗначениеТекущая доступность Битрикс24
Полеdata.reason_code Типstring | null ЗначениеПричина закрытого доступа к Битрикс24, либо null, если доступ открыт
Полеdata.webhook_cleanup Типstring Значениеnone — нет незавершённых попыток, pending — очистка или создание не завершены, в том числе когда прежний вебхук удалить нечем, attention_required — результат создания вебхука неизвестен и требует разбора на стороне платформы
Полеdata.capabilities.bitrix Типboolean ЗначениеТекущая доступность Битрикс24
Полеdata.capabilities.ai Типboolean ЗначениеДоступность AI с учётом scope, разрешения и состояния подключения
Полеdata.capabilities.storage Типboolean ЗначениеДоступность хранилища с учётом scope и состояния подключения
Полеdata.poll_after_seconds Типinteger ЗначениеРекомендуемый интервал опроса: 30 секунд
Полеdata.action Типstring | null Значениеnull, если доступ открыт. Иначе WAIT, AUTHORIZE_ADMIN, CONTACT_SUPPORT, RECONNECT, WAIT_FOR_DELETION
Состояние или условие reason_code action
Состояние или условиеACTIVE, все проверки подключения и согласия пройдены reason_codenull actionnull
Состояние или условиеACTIVE, плановая проверка держателя устарела или не прошла reason_codeADMIN_CHECK_REQUIRED actionWAIT
Состояние или условиеACTIVE, согласие, права держателя или вебхук подключения требуют нового согласия администратора reason_codeCONNECTION_ADMIN_REQUIRED actionAUTHORIZE_ADMIN
Состояние или условиеACTIVE, у согласия нет прав Битрикс24 reason_codeSCOPE_MISSING actionWAIT
Состояние или условиеACTIVE, не завершена очистка вебхука с неизвестным результатом создания reason_codeCONNECTION_WEBHOOK_CLEANUP_PENDING actionWAIT
Состояние или условиеACTIVE, рабочий вебхук ещё не готов reason_codeCONNECT_COMPANY_NOT_READY actionWAIT
Состояние или условиеACTIVE, секрет подключения не действует reason_codeINVALID_API_KEY actionWAIT
Состояние или условиеACTIVE, приложение или аккаунт заблокированы reason_codeCLIENT_BLOCKED или PORTAL_BLOCKED actionWAIT
Состояние или условиеNEEDS_ADMIN reason_codeCONNECTION_ADMIN_REQUIRED actionAUTHORIZE_ADMIN
Состояние или условиеSUSPENDED reason_codeCONNECTION_SUSPENDED actionCONTACT_SUPPORT
Состояние или условиеDISCONNECTED reason_codeCONNECTION_DISCONNECTED actionRECONNECT
Состояние или условиеDELETION_PENDING reason_codeCONNECTION_DELETION_PENDING actionWAIT_FOR_DELETION

Рабочие вызовы при ADMIN_CHECK_REQUIRED получают 503 с заголовком Retry-After: 30. Повторите запрос через 30 секунд.

Пример ответа

Ответ и ошибки возвращаются с Cache-Control: no-store. Пример ответа для подключения, ожидающего администратора:

JSON
{
  "success": true,
  "data": {
    "connection_id": "connection-id",
    "connection_mode": "COMPANY",
    "portal": { "domain": "example.bitrix24.com", "name": "Example" },
    "user": null,
    "status": "NEEDS_ADMIN",
    "generation": 0,
    "revision": 1,
    "credential_version": 1,
    "bitrix_ready": false,
    "reason_code": "CONNECTION_ADMIN_REQUIRED",
    "webhook_cleanup": "none",
    "capabilities": { "bitrix": false, "ai": false, "storage": false },
    "poll_after_seconds": 30,
    "action": "AUTHORIZE_ADMIN"
  }
}

Пример ответа при ошибке

401 — неизвестный, отозванный или старый после ротации секрет:

JSON
{ "success": false, "error": { "code": "INVALID_API_KEY", "message": "Invalid API key" } }

Ошибки

HTTP Код Что делать
HTTP401 КодINVALID_API_KEY Что делатьПроверить текущий секрет. Неизвестный, отозванный, старый после ротации секрет и запрос чужой пары дают одинаковый отказ
HTTP403 КодCLIENT_BLOCKED Что делатьПродукт заблокирован, обратиться в поддержку
HTTP403 КодPORTAL_DELETED Что делатьАккаунт удалён, остановить опрос
HTTP403 КодPORTAL_BLOCKED Что делатьАккаунт заблокирован, обратиться в поддержку
HTTP403 КодPORTAL_SUSPENDED Что делатьАккаунт приостановлен, обратиться в поддержку
HTTP429 КодRATE_LIMITED Что делатьДостигнут лимит IP. Подождать не меньше Retry-After секунд
HTTP429 КодCALLER_RATE_LIMITED Что делатьДостигнут общий лимит подключения или аккаунта. Подождать не меньше Retry-After секунд

Общие коды из таблицы описаны также в справочнике ошибок, а CLIENT_BLOCKED встречается у этого метода и у AI-вызовов подключения Компании.

Известные особенности

ACTIVE само по себе не открывает доступ. Опрос не продлевает проверку держателя. Используйте bitrix_ready и отдельные значения capabilities: сведения о держателе не меняют доступность Битрикс24, AI или хранилища. Ответ содержит только описанные выше сведения о подключённом Битрикс24 и держателе согласия. Перечня людей, внутренних идентификаторов, секретов и URL вебхуков в статусе нет.

Частота опроса. Опрашивайте не чаще poll_after_seconds, при 429 увеличивайте паузу. Базовый лимит IP — 120 запросов в минуту. Действующий порог указан в x-ratelimit-limit. Успешный опрос также расходует общий лимит подключения и аккаунта вместе с другими API-запросами. Ротация секрета не сбрасывает этот лимит.

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

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