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

`GET /v1/connect/company/status`

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

## Параметры

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

## Примеры

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

### curl

```bash
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`, все проверки подключения и согласия пройдены | `null` | `null` |
| `ACTIVE`, плановая проверка держателя устарела или не прошла | `ADMIN_CHECK_REQUIRED` | `WAIT` |
| `ACTIVE`, согласие, права держателя или вебхук подключения требуют нового согласия администратора | `CONNECTION_ADMIN_REQUIRED` | `AUTHORIZE_ADMIN` |
| `ACTIVE`, у согласия нет прав Битрикс24 | `SCOPE_MISSING` | `WAIT` |
| `ACTIVE`, не завершена очистка вебхука с неизвестным результатом создания | `CONNECTION_WEBHOOK_CLEANUP_PENDING` | `WAIT` |
| `ACTIVE`, рабочий вебхук ещё не готов | `CONNECT_COMPANY_NOT_READY` | `WAIT` |
| `ACTIVE`, секрет подключения не действует | `INVALID_API_KEY` | `WAIT` |
| `ACTIVE`, приложение или аккаунт заблокированы | `CLIENT_BLOCKED` или `PORTAL_BLOCKED` | `WAIT` |
| `NEEDS_ADMIN` | `CONNECTION_ADMIN_REQUIRED` | `AUTHORIZE_ADMIN` |
| `SUSPENDED` | `CONNECTION_SUSPENDED` | `CONTACT_SUPPORT` |
| `DISCONNECTED` | `CONNECTION_DISCONNECTED` | `RECONNECT` |
| `DELETION_PENDING` | `CONNECTION_DELETION_PENDING` | `WAIT_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 | Код | Что делать |
|------|-----|------------|
| 401 | `INVALID_API_KEY` | Проверить текущий секрет. Неизвестный, отозванный, старый после ротации секрет и запрос чужой пары дают одинаковый отказ |
| 403 | `CLIENT_BLOCKED` | Продукт заблокирован, обратиться в поддержку |
| 403 | `PORTAL_DELETED` | Аккаунт удалён, остановить опрос |
| 403 | `PORTAL_BLOCKED` | Аккаунт заблокирован, обратиться в поддержку |
| 403 | `PORTAL_SUSPENDED` | Аккаунт приостановлен, обратиться в поддержку |
| 429 | `RATE_LIMITED` | Достигнут лимит IP. Подождать не меньше `Retry-After` секунд |
| 429 | `CALLER_RATE_LIMITED` | Достигнут общий лимит подключения или аккаунта. Подождать не меньше `Retry-After` секунд |

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

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

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

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

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

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

- [Подключение Компании](/docs/partner-connect/company)
- [Обменять код на API-ключ](/docs/partner-connect/token)
- [Partner Connect](/docs/partner-connect)
