Для 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
curl --max-time 20 "https://vibecode.bitrix24.tech/v1/connect/company/status" \
-H "X-Api-Key: YOUR_COMPANY_SECRET"
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. Пример ответа для подключения, ожидающего администратора:
{
"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 — неизвестный, отозванный или старый после ротации секрет:
{ "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 не позволяет даже опрос. После ротации используйте новый секрет. Уже выданная защита и опрос действуют независимо от доступности новой выдачи. Повторное подключение выполняет администратор аккаунта через отдельное согласие.