# Активировать пробный период Маркета

`POST /v1/portals/:id/activate-market-trial`

Включает одноразовый пробный период подписки BitrixGPT + Маркетплейс для аккаунта Битрикс24, к которому привязан вызывающий ключ. Результат тот же, что при оформлении пробного периода в кабинете, но без браузера. Возможность зависит от региона аккаунта: в регионе, где такой подписки нет, вызов пробный период не включает.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `id` (path) | string (UUID) | да | Идентификатор аккаунта Битрикс24. Обязан совпадать с аккаунтом вызывающего ключа. Личный ключ берёт значение из поля `portalId` записей `GET /v1/apps` — [Список приложений](/docs/apps/list). Список всех аккаунтов с идентификаторами отдаёт `GET /v1/portals` — [Менеджмент-ключи](/docs/management-keys) |

Тело запроса не требуется, поэтому запрос отправляется без заголовка `Content-Type`. Клиент, который ставит `Content-Type: application/json` на любой запрос, обязан прислать тело `{}` — заголовок с пустым телом отклоняется до обработки вызова.

## Примеры

### curl — личный ключ

```bash
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/portals/YOUR_PORTAL_ID/activate-market-trial
```

### curl — OAuth-приложение

```bash
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/portals/YOUR_PORTAL_ID/activate-market-trial
```

### JavaScript — личный ключ

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/portals/${portalId}/activate-market-trial`,
  {
    method: 'POST',
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  },
)

const { success, data } = await res.json()
if (success) {
  // activated — включили сейчас, already_active — доступ был и до вызова
  console.log(data.status, data.trialEndsAt)
}
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/portals/${portalId}/activate-market-trial`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  },
)

const { success, data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.status` | string | `activated` — пробный период включён этим вызовом. `already_active` — доступ у аккаунта уже был, вызов ничего не менял |
| `data.trialEndsAt` | string \| null | Дата и время окончания пробного периода в формате ISO 8601. Приходит только при статусе `activated`. Значение `null` означает, что Битрикс24 дату не вернул |

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

Пробный период включён этим вызовом:

```json
{
  "success": true,
  "data": {
    "status": "activated",
    "trialEndsAt": "2026-08-01T00:00:00.000Z"
  }
}
```

Доступ у аккаунта уже был — поля `trialEndsAt` в ответе нет:

```json
{
  "success": true,
  "data": {
    "status": "already_active"
  }
}
```

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

403 — идентификатор в пути принадлежит другому аккаунту:

```json
{
  "success": false,
  "error": {
    "code": "PORTAL_MISMATCH",
    "message": "This key is not authorized for the requested portal"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `FST_ERR_CTP_EMPTY_JSON_BODY` | Передан заголовок `Content-Type: application/json`, а тело пустое. Пришлите тело `{}` либо уберите заголовок |
| 403 | `PORTAL_MISMATCH` | Идентификатор в пути не совпадает с аккаунтом ключа. Этот же код получает менеджмент-ключ — он не привязан к аккаунту и активировать пробный период не может |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ работает в режиме только для чтения. Адрес страницы, где режим переключается, приходит в `error.details.switchUrl` — [Режим доступа ключа](/docs/keys-auth/access-mode) |
| 403 | `PURPOSE_KEY_FORBIDDEN` | Служебный ключ специального назначения — ключ настольного приложения [Cowork](/docs/cowork) или ключ деплоя проекта Cowork |
| 403 | `AGENT_MAINTENANCE_KEY_OUT_OF_SCOPE` | Ключ обслуживания агента. Он допущен только к операциям с сервером, поэтому до активации пробного периода не доходит |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Ключ со скоупом `vibe:cowork` без служебной пометки назначения — например, ключ рабочего места агента [Коворка](/docs/cowork). Он работает только с данными и состояние аккаунта не меняет. Ключ настольного приложения отклоняется раньше, кодом `PURPOSE_KEY_FORBIDDEN`. Поле `error.details.requiredAction` предлагает выписать ключ деплоя проекта, но для этой операции он тоже не подойдёт: нужен личный ключ или ключ приложения |
| 404 | `NOT_FOUND` | Аккаунт удалён между проверкой ключа и обработкой запроса. Удалённый аккаунт отклоняется раньше, кодом `403 PORTAL_DELETED` — [состояние аккаунта Битрикс24](/docs/errors#состояние-аккаунта-битрикс24) |
| 409 | `ALREADY_ACTIVATED` | Пробный период для этого аккаунта через Вайбкод уже включали |
| 409 | `TRIAL_ACTIVATION_UNAVAILABLE` | Пробный период для аккаунта недоступен. Условия перечислены в «Известных особенностях» |
| 415 | `FST_ERR_CTP_INVALID_MEDIA_TYPE` | Тело отправлено с типом, отличным от `application/json` |
| 429 | `RATE_LIMITED` | Превышен лимит — три запроса в час на аккаунт. Остаток и время сброса приходят в заголовках `X-RateLimit-Remaining` и `X-RateLimit-Reset`, рекомендованная пауза — в заголовке `Retry-After` |
| 503 | `TRIAL_ACTIVATION_RETRY` | Временный сбой на стороне Битрикс24. Повтор через несколько минут имеет смысл |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**В ответе `GET /v1/me` идентификатора аккаунта нет.** Там приходит только домен. Личный ключ берёт идентификатор из поля `portalId` записей [`GET /v1/apps`](/docs/apps/list) — это работает, когда у аккаунта есть хотя бы одно приложение. Остальные источники — ответ `GET /v1/portals` по [менеджмент-ключу](/docs/management-keys) либо кабинет. Без идентификатора вызов упирается в `403 PORTAL_MISMATCH`.

**Повторный вызов после успеха ничего не включает.** Аккаунт, для которого пробный период уже активировали через Вайбкод, отвечает `409 ALREADY_ACTIVATED` — платформа помнит факт активации и второй раз в Битрикс24 не обращается.

**Ответ `200` не означает, что вызов что-то изменил.** Аккаунт, у которого доступ уже есть, получает `200` со статусом `already_active` вместо отказа. Различать «включили сейчас» и «доступ был» нужно по полю `data.status`, а не по коду ответа.

**Причину недоступности ответ не раскрывает.** Код `409 TRIAL_ACTIVATION_UNAVAILABLE` приходит на все условия одной формулировкой. Основные — аккаунт коробочный, аккаунт вне России и Беларуси, пробный период на стороне Битрикс24 уже израсходован, у аккаунта нет ключа разработчика. Перечень основными не ограничен: тем же кодом отвечает сбой на стороне платформы, который снимается только вмешательством поддержки. Поэтому отказ, противоречащий состоянию аккаунта, стоит переслать в поддержку, а не считать окончательным.

**Лимит частоты считается на аккаунт и расходуется в том числе на отказах.** Три запроса в час, и проверка идёт раньше остальных условий, поэтому неудачная попытка — с чужим идентификатором, с ключом только для чтения — уменьшает остаток так же, как удачная. Остаток и время сброса приходят в заголовках `X-RateLimit-Remaining` и `X-RateLimit-Reset`.

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

- [Менеджмент-ключи](/docs/management-keys)
- [Список приложений](/docs/apps/list)
- [Ключи и авторизация](/docs/keys-auth)
- [Режим доступа ключа](/docs/keys-auth/access-mode)
- [Создать приложение](/docs/apps/create)
- [Ошибки](/docs/errors)