## Включить пробный период Маркета

`POST /v1/cowork/activate-market-trial`

Включает одноразовый пробный период подписки Маркета для аккаунта Битрикс24, к которому привязан ключ десктопа Коворк/Код. Аккаунт берётся из привязки ключа, параметра пути нет.

Перед показом шага активации прочитайте `activation.marketTrial.available` в [состоянии подписки](/docs/cowork/state) — этот признак считается заранее и говорит, стоит ли предлагать включение. Вызов самого метода остаётся законным и тогда, когда признак говорит «не предлагать»: подписка Маркета может быть нужна аккаунту для другого — вызовов ботов, развёртывания и пробуждения приложений, создания приложения и замены его ключа, привязки встроек или выдачи ключа агента.

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `acknowledgedOneTimeConsumption` | boolean | да | Только литерал `true`. Подтверждает, что пользователю показали: включается одноразовый период, отозвать его нельзя, и названа дата окончания. Другое значение или пустое тело дают `400 DISCLOSURE_REQUIRED` |

## Примеры

Эндпоинт принимает только ключ десктопа Коворк/Код, поэтому примеров два: ключ приложения с сессией пользователя получает `403 COWORK_DESKTOP_KEY_REQUIRED`.

### curl — ключ десктопа Коворк/Код

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/cowork/activate-market-trial \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"acknowledgedOneTimeConsumption": true}'
```

### JavaScript — ключ десктопа Коворк/Код

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/cowork/activate-market-trial', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ acknowledgedOneTimeConsumption: true }),
})

if (!res.ok) {
  const { error } = await res.json()
  console.error(error.code, error.message)
} else {
  const { data } = await res.json()
  console.log(data.status === 'activated'
    ? `Пробный период включён до ${data.trialEndsAt}`
    : `Состояние: ${data.status}`)
}
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успешном ответе |
| `data.status` | string | Исход включения: `activated` — период включён, `already_active` — период или подписка уже действуют, `pending` — включение состоялось, подтверждения от Битрикс24 ещё нет |
| `data.trialEndsAt` | string или null | Когда период заканчивается, по данным Битрикс24 (ISO 8601). Приходит при `status: activated` |

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

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

Включение состоялось, подтверждение ещё не пришло:

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

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

400 — тело без подтверждения:

```json
{
  "success": false,
  "error": {
    "code": "DISCLOSURE_REQUIRED",
    "message": "Body must contain {\"acknowledgedOneTimeConsumption\": true} — confirm that the user was shown that this starts a one-time trial and when it ends."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `DISCLOSURE_REQUIRED` | В теле нет `acknowledgedOneTimeConsumption` со значением `true`. Этот же код приходит на пустое тело и на запрос без заголовка `Content-Type` |
| 400 | `INVALID_JSON_BODY` | Тело передано, но не читается как JSON |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не опознан: такой строки на платформе нет |
| 403 | `INSUFFICIENT_SCOPE` | У ключа нет скоупа `vibe:cowork` |
| 403 | `COWORK_DESKTOP_KEY_REQUIRED` | Ключ другого класса: личный ключ, ключ приложения или ключ места агента |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ выпущен только для чтения |
| 404 | `NOT_FOUND` | Аккаунт не найден или удалён |
| 409 | `ALREADY_ACTIVATED` | Пробный период для этого аккаунта уже включали через нас |
| 409 | `TRIAL_ACTIVATION_UNAVAILABLE` | Включение недоступно: аккаунт не подходит по условиям, демо Маркета израсходовано либо Битрикс24 отказал окончательно |
| 429 | `RATE_LIMITED` | Больше трёх запросов в час на один аккаунт |
| 503 | `TRIAL_ACTIVATION_RETRY` | Временная ошибка на нашей стороне, повтор безопасен |

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

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

**Пробный период одноразовый, и отозвать его нельзя.** Отсчёт начинается в момент успешного ответа, отмены у этой операции нет ни у нас, ни у Битрикс24. Поэтому включение и требует подтверждения в теле запроса.

**Срок периода задаёт Битрикс24.** Показывайте пользователю дату из `trialEndsAt`, а не собственное число дней: оно менялось и может отличаться от того, что вы видели раньше.

**Статус `pending` — не повод повторять запрос.** Включение уже состоялось, не хватает только подтверждения от Битрикс24. Повтор израсходует попытку и вернёт `409 ALREADY_ACTIVATED`. Отдельного признака подтверждения снаружи сейчас нет: [состояние подписки](/docs/cowork/state) сразу показывает `status: activated`, и `endsAt` там тоже заполняется сразу. Показывайте пользователю включённый период и дату из состояния, а сам ответ `pending` считайте успехом.

**Признак `available` — прогноз, а не гарантия.** Значение `true` в состоянии подписки означает «предлагать можно», но окончательное решение остаётся за Битрикс24: между запросом состояния и включением условия могли измениться, поэтому обработку отказа оставьте.

**Ключ десктопа выдаёт вход в приложение Коворк/Код.** Личный ключ и ключ приложения этот эндпоинт не принимают, для них включение живёт на другом адресе. Ключ места агента несёт тот же скоуп `vibe:cowork`, но тоже получает отказ: за ним нет человека, которому показали бы расход одноразового ресурса.

**Три попытки в час считаются на аккаунт, а не на ключ, и расходуются в том числе на отказах.** Все устройства одного человека и все сотрудники одного аккаунта делят этот предел, а проверка частоты идёт раньше остальных: запрос без подтверждения или с ключом другого класса уменьшает остаток так же, как удачный.

**Отсутствие подтверждения всегда приходит одним кодом.** Пустое тело, отсутствие заголовка `Content-Type` и чужой тип содержимого без тела — всё это `400 DISCLOSURE_REQUIRED`, а не внутренняя ошибка разбора запроса. Отдельной ветки на такие случаи заводить не нужно.

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

- [Активировать пробный период Маркета](/docs/activate-market-trial)
- [Состояние подписки Cowork/Code](/docs/cowork/state)
- [Сводка по подписке Cowork/Code](/docs/cowork/me)
- [Предрасчёт смены тарифа](/docs/cowork/subscription-preview)
- [Cowork/Code](/docs/cowork)
- [Ошибки](/docs/errors)