Погасить купон

POST /v1/cowork/coupon/redeem

Погашает купон Cowork/Code и выдаёт пользователю подаренный тариф на подаренный срок за счёт платформы, без списания с аккаунта Битрикс24.

Пользователь и аккаунт берутся из привязки ключа, параметров пути нет. Операция необратима: погашенный купон обратно не возвращается.

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

Примеры

Ось авторизации одна: эндпоинт принимает только ключ десктопа Cowork/Code. Личный ключ и ключ приложения получают 403 INSUFFICIENT_SCOPE либо 403 COWORK_DESKTOP_KEY_REQUIRED.

curl — ключ десктопа Cowork/Code

curl -X POST https://vibecode.bitrix24.tech/v1/cowork/coupon/redeem \
  -H "X-Api-Key: YOUR_COWORK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "PRAKTIKUM-7HKM4TQZ2RVW-45C80C", "action": "force"}'

JavaScript — ключ десктопа Cowork/Code

const res = await fetch('https://vibecode.bitrix24.tech/v1/cowork/coupon/redeem', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_COWORK_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'PRAKTIKUM-7HKM4TQZ2RVW-45C80C',
    action: 'force',
  }),
})

if (!res.ok) {
  const { error } = await res.json()
  if (error.code === 'CONCURRENT_REDEMPTION') {
    // Единственный код, который повторяют автоматически.
  }
  console.error(error.code)
} else {
  const { data } = await res.json()
  if (data.accessGranted) {
    console.log(`${data.grantedTier} на ${data.grantedTermMonths} мес.`)
  } else {
    // Тариф выдан, доступа ещё нет — заявка ушла администратору аккаунта.
    console.log(`${data.grantedTier} активирован, ждём решения администратора`)
  }
}

Поля ответа

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

{
  "success": true,
  "data": {
    "grantedTier": "PRO",
    "grantedTermMonths": 3,
    "accessGranted": true
  }
}

Тариф выдан, но доступ к Cowork/Code на аккаунте ещё не открыт:

{
  "success": true,
  "data": {
    "grantedTier": "PRO",
    "grantedTermMonths": 3,
    "accessGranted": false
  }
}

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

409 — на месте пользователя уже стоит этот тариф:

{
  "success": false,
  "error": {
    "code": "COUPON_SEAT_ALREADY_ON_TIER",
    "message": "The coupon cannot be redeemed"
  }
}

Ошибки

Отказ по самому купону приходит статусом 409, а error.code называет причину. Текст в message у всех таких отказов один, разбирать его не нужно — решение принимается по коду.

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

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

Общий экран успеха на accessGranted: false — самый дорогой класс обращений в поддержку. Операция для пользователя выглядит удачной, а запустить Cowork/Code он не может, и это читается как поломка. Нужен отдельный экран — «Тариф активирован, заявка на доступ отправлена администратору», — а не общий «Готово».

Присланное действие — намерение, а не разрешение. Между проверкой и погашением место могло измениться: пользователь оплатил тариф в другой вкладке, администратор понизил место, сработала отмена. Решение пересчитывается по свежему состоянию, и если выбранного действия там уже нет, приходит COUPON_ACTION_NOT_AVAILABLE — перечитайте проверку и покажите те действия, что вернулись сейчас.

CONCURRENT_REDEMPTION повторяют, остальные отказы купона — никогда. Купон исправен, правила пройдены, подарок не израсходован: к моменту ответа купон уже вернулся в оборот. Делайте до трёх повторов с задержкой 300–800 мс и случайным разбросом — без разброса десятки клиентов повторят синхронно и воспроизведут ту же конкуренцию. Пользователю на это время показывают ожидание, а не ошибку. Автоматический повтор любого другого отказа купона выжигает счётчик неудач за секунды. Отдельно от них стоит 429 RATE_LIMITED — это не отказ купона, счётчик неудач он не трогает, и повтор после паузы уместен.

Действие force сжигает остаток оплаченного срока без возврата. Сколько именно суток сгорит, приходит в losesDays проверки купона и на клиенте не пересчитывается. Подпись кнопки обязана называть это число до нажатия — после погашения вернуть срок нечем.

Купон одноразов на пользователя, но не обязательно на всех. Часть купонов рассчитана на несколько активаций разными людьми. Сколько людей держит один и тот же купон, наружу не сообщается, и в тексте для пользователя это не упоминают.

Счётчик неудачных попыток общий с проверкой купона — пара, на которую он заведён, и условие обнуления описаны в проверке купона.

Суммарный лимит платформы у погашения — 10 запросов в минуту, у проверки — 20 запросов в минуту. Действующие для вашего ключа значения приходят в заголовке x-ratelimit-limit. Они ниже суммарных, поскольку лимиты делятся между репликами.

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

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

• Проверить купон
• Состояние подписки Cowork/Code
• Сводка по подписке Cowork/Code
• Предрасчёт смены тарифа
• Cowork/Code
• Ошибки