## Предрасчёт смены тарифа Cowork/Code

`GET /v1/cowork/subscription/preview`

Возвращает сумму, которая спишется прямо сейчас при переходе на указанный тариф, и дату, с которой изменение вступит в силу. Это предрасчёт конкретной операции, а не цена тарифа из каталога.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `tier` (query) | string | да | Тариф, для которого считается переход: `FREE`, `PRO`, `MAX`, `ULTRA`. Каталог тарифов — [`GET /v1/cowork/state`](/docs/cowork/state) |

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/cowork/subscription/preview?tier=PRO" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/cowork/subscription/preview?tier=PRO" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const url = 'https://vibecode.bitrix24.tech/v1/cowork/subscription/preview?tier=PRO'
const res = await fetch(url, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

if (!res.ok) {
  const { error } = await res.json()
  console.error(error.code, error.message)
} else {
  const preview = await res.json()
  console.log(preview.scheduled
    ? `Сейчас не списывается, изменение вступит в силу ${preview.effectiveFrom}`
    : `Спишется ${preview.netVibes} Вайбов`)
}
```

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

```javascript
const url = 'https://vibecode.bitrix24.tech/v1/cowork/subscription/preview?tier=PRO'
const res = await fetch(url, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const preview = await res.json()
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `tier` | string | Тариф из запроса |
| `chargeVibes` | string | Полная цена операции в Вайбах, десятичная строка. `"0"`, когда операция бесплатна |
| `creditVibes` | string | Возврат за неиспользованный остаток оплаченного месяца. Отличается от `"0"` только при повышении тарифа и только когда возможность включена для аккаунта |
| `netVibes` | string | Сколько спишется прямо сейчас: `chargeVibes` минус `creditVibes`, но не меньше нуля. Это число и показывают человеку |
| `effectiveFrom` | string | Когда изменение вступит в силу, ISO 8601. Момент ответа, либо конец оплаченного периода при `scheduled: true` |
| `scheduled` | boolean | `true` — изменение применится в конце оплаченного периода, сейчас не списывается |
| `currency` | string или null | Код валюты пополнения кошелька по ISO 4217, либо `null`, когда пополнение недоступно |
| `topUpAvailable` | boolean | Доступно ли пополнение кошелька для этого аккаунта |

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

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

Переход с бесплатного тарифа на `PRO`, пополнение кошелька доступно:

```json
{
  "tier": "PRO",
  "chargeVibes": "2000",
  "creditVibes": "0",
  "netVibes": "2000",
  "effectiveFrom": "2026-08-11T11:11:14.115Z",
  "scheduled": false,
  "currency": "RUB",
  "topUpAvailable": true
}
```

Повторный выбор тарифа, который уже подключён — операция бесплатна, пополнение кошелька недоступно:

```json
{
  "tier": "FREE",
  "chargeVibes": "0",
  "creditVibes": "0",
  "netVibes": "0",
  "effectiveFrom": "2026-08-11T11:10:25.859Z",
  "scheduled": false,
  "currency": null,
  "topUpAvailable": false
}
```

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

400 — параметр `tier` не передан или содержит неизвестное значение:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_QUERY",
    "message": "Query parameter `tier` is required and must be one of FREE, PRO, MAX, ULTRA."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_QUERY` | Параметр `tier` не передан, либо его значение не входит в список `FREE`, `PRO`, `MAX`, `ULTRA` |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный API-ключ |
| 403 | `INSUFFICIENT_SCOPE` | У ключа нет скоупа `vibe:cowork` |
| 404 | `COWORK_NOT_ACTIVATED` | Подписка Cowork/Code не найдена для пары пользователь и портал |
| 503 | `COWORK_FEATURE_DISABLED` | Cowork/Code отключён на уровне платформы |

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

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

**Успешный ответ (200) — это сам объект предрасчёта, без обёртки `success`.** Ошибки приходят в конверте `{ success: false, error: { code, message } }`. Определяйте успех по HTTP-статусу (`res.ok`).

**Цена тарифа и сумма списания — разные числа.** Поле `tiers[].feeVibes` в [полном состоянии подписки](/docs/cowork/state) — это ценник тарифа. Фактическая сумма расходится с ним уже в четырёх случаях:

- повторный выбор тарифа, который уже подключён, — списывается ноль,
- понижение тарифа, которое встаёт в очередь на конец оплаченного периода, — сейчас не списывается ничего,
- повторный запрос про понижение, уже стоящее в очереди, — тоже ноль,
- повышение с зачётом неиспользованного остатка оплаченного месяца — полная цена минус возврат.

Две последние возможности включаются на стороне платформы и появляются без обновления клиента. Поэтому экран подтверждения строят на предрасчёте, а не на ценнике.

**Пара `netVibes` и `scheduled` — это готовое решение «списывать сейчас или нет».** Повторять правила бесплатных переходов у себя не нужно: `netVibes: "0"` вместе с `scheduled: true` означает, что сейчас ничего не спишется, а изменение применится в конце оплаченного периода.

**Запрос не удался — покажите ценник тарифа как верхнюю границу.** Фактическое списание никогда не бывает больше цены тарифа, поэтому при сетевой ошибке или отказе экран подтверждения показывает `feeVibes` и не завышает сумму. Так сделано в личном кабинете.

**Кнопку пополнения кошелька рисуйте по значению `topUpAvailable`, а не по наличию поля в ответе.** Ответ `topUpAvailable: false` вместе с `currency: null` — штатное состояние: пополнение для этого аккаунта сейчас недоступно. Это не ошибка запроса.

**Суммы приходят только в Вайбах — денежной цены тарифа в ответе нет, и `currency` ею не является.** `currency` — это валюта, в которой владелец кошелька его пополнит; пары «сумма и валюта» для тарифа не существует. Причина не в наборе полей: единого курса Вайба к деньгам нет. Курс возникает в момент покупки конкретного пакета пополнения, различается по пакетам и по валютам, Вайбы начисляются по сумме без налога, тогда как платит клиент с налогом, а акция Битрикс24 меняет уплаченные деньги, не меняя количество Вайбов. Любое одно число было бы обещанием, которого платформа не даёт.

Что с этим делать на экране: показывайте `netVibes` в Вайбах, рядом ведите в кассу по `topUpAvailable` — денежную сумму человек увидит на кассе, в своей валюте и с налогом, перед оплатой.

**Ограничение частоты — 30 запросов в минуту на пару портал и пользователь.** Ответ не кэшируется (`Cache-Control: no-store`): суммы считаются на момент запроса.

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

- [Состояние подписки Cowork/Code](/docs/cowork/state)
- [Сводка по подписке Cowork/Code](/docs/cowork/me)
- [Cowork/Code](/docs/cowork)
- [Ошибки](/docs/errors)