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

GET /v1/cowork/subscription/preview

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

Параметры

Примеры

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

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

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

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 — личный ключ

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-приложение

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()

Поля ответа

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

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

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

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

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

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

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

Ошибки

Полный список общих ошибок API — Ошибки.

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

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

Цена тарифа и сумма списания — разные числа. Поле tiers[].feeVibes в полном состоянии подписки — это ценник тарифа. Фактическая сумма расходится с ним уже в пяти случаях:

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

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

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

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

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

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

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

Суммарный лимит платформы — 30 запросов в минуту. Действующее для вашего ключа значение приходит в заголовке x-ratelimit-limit. Предел считается на пару портал и пользователь. Ответ не кэшируется (Cache-Control: no-store): суммы считаются на момент запроса.

Сброс лимитов по праву акции возврат не увеличивает. После сброса лимитов creditVibes считается так, будто сброса не было: объём месяца, израсходованный до сброса, остаётся израсходованным и в возврат за остаток не попадает.

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

• Состояние подписки Cowork/Code
• Сводка по подписке Cowork/Code
• Cowork/Code
• Ошибки