Проверить купон

POST /v1/cowork/coupon/preview

Проверяет купон 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/preview \
  -H "X-Api-Key: YOUR_COWORK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "PRAKTIKUM-7HKM4TQZ2RVW-45C80C"}'

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

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

if (!res.ok) {
  const { error } = await res.json()
  console.error(error.code)
} else {
  const { data } = await res.json()

  if (!data.valid) {
    // Текст для пользователя выбирают по data.reason — таблица «Причины отказа».
    console.log(data.reason)
  } else {
    console.log(`${data.grant.tier} на ${data.grant.termMonths} мес.`)
    console.log('Что можно сделать:', data.decision.kind)
  }
}

Поля ответа

Формы решения

Поле data.decision описывает, что случится с местом пользователя, если купон погасить сейчас.

Состав facts у решения choose:

Состав элемента options:

Причины отказа

Значения поля data.reason при valid: false.

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

Купон годен, место пользователя свободно:

{
  "success": true,
  "data": {
    "valid": true,
    "reason": null,
    "grant": {
      "tier": "PRO",
      "termMonths": 3,
      "campaignName": "Практикум партнёров, август"
    },
    "decision": { "kind": "apply" }
  }
}

Купон годен, но место занято старшим оплаченным тарифом — пользователь выбирает:

{
  "success": true,
  "data": {
    "valid": true,
    "reason": null,
    "grant": {
      "tier": "PRO",
      "termMonths": 3,
      "campaignName": "Практикум партнёров, август"
    },
    "decision": {
      "kind": "choose",
      "facts": {
        "currentTier": "MAX",
        "paidThroughAt": "2026-09-14T10:00:00.000Z",
        "isPaid": true,
        "cancellationScheduled": false,
        "grantTier": "PRO",
        "grantTermMonths": 3
      },
      "options": [
        { "kind": "force", "losesDays": 24, "losesTier": "MAX" }
      ]
    }
  }
}

Купон не годен — статус ответа тот же 200, поля decision в теле нет:

{
  "success": true,
  "data": {
    "valid": false,
    "reason": "COUPON_INVALID",
    "grant": null
  }
}

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

400 — тело без поля code:

{
  "success": false,
  "error": {
    "code": "INVALID_CODE",
    "message": "Field `code` is required"
  }
}

Ошибки

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

Отказ по самому купону ошибкой не считается и приходит статусом 200 с data.valid: false.

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

Проверка не отвечает на вопрос «погашение пройдёт». Поле data.valid смотрит только на купон и кампанию: код живой, срок не вышел, кампания открыта, личный лимит и лимит аккаунта не выбраны. Условия самого места отвечают отдельным полем data.decision, но и оно не гарантия: штучный потолок кампании проверяется только при погашении, а место могло измениться между двумя вызовами. Готовьте экран отказа на шаге погашения даже после зелёной проверки.

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

Неудачные попытки жгут тот же счётчик, что и погашение. Счёт ведётся по паре «аккаунт плюс пользователь», коллеги по аккаунту чужими попытками не страдают. Десять неудач за час закрывают попытки на тридцать минут. Успешное погашение счётчик обнуляет.

Опечатка счётчик не тратит. Хвост купона — контрольная сумма над префиксом и телом. Ввод, который её не прошёл, до базы не доходит, поэтому пользователь, переписывающий код с раздатки или диктующий его по телефону, ничего не теряет.

Не вызывайте проверку на каждое нажатие клавиши. Она дешевле погашения и повторяема, поэтому для подбора опаснее него. Вешайте вызов на кнопку либо на задержку от 500 мс после последнего нажатия.

Семь разных отказов схлопнуты в COUPON_INVALID намеренно, и различать их не понадобится. Отдельная причина на каждый случай подсказывала бы подбирающему, какие префиксы живые: чтобы увидеть ответ «лимит выбран», надо предъявить настоящий код этой кампании. Ветки под «код отозван» и «лимит выбран» заводить не нужно — таких значений в ответе не появится.

Отказ занимает не меньше четырёхсот миллисекунд. Время ответа выровнено по нижней границе, чтобы секундомер не отличал «такого кода нет» от «код есть, но отозван». Ответ, который сам по себе занял дольше, не укорачивается.

Отложенного применения не существует. Действия «применить подарок в конце оплаченного срока» в options не бывает. Появление такого варианта означает ошибку на нашей стороне, а не сигнал рисовать под него кнопку.

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

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