Руководство по открытому API для партнёров

Став одобренным партнёром QCode, управляйте своим партнёрским аккаунтом программно: проверяйте баланс и расход, создавайте и переключайте дочерние API-ключи. Включает предварительное условие, порядок подачи заявки, аутентификацию, справочник эндпоинтов, ограничения частоты и безопасность.

Руководство по открытому API для партнёров¶

Открытый API для партнёров QCode позволяет управлять вашим партнёрским (реселлерским) аккаунтом программно — проверять баланс и расход, создавать и управлять дочерними API-ключами, которые вы перепродаёте, — чтобы встроить выпуск ключей, сверку и выдачу в собственные системы вместо ручной работы в веб-панели.

⚠️ Предварительное условие: сначала нужно стать одобренным партнёром. Этот API доступен только одобренным партнёрам QCode. Если вы ещё не партнёр, сначала подайте заявку; после одобрения вы сможете сгенерировать токен доступа и вызывать API.

1. Что умеет этот API¶

Будучи партнёром QCode, вы получаете партнёрский аккаунт (предоплаченный баланс, множитель скидки в зависимости от уровня) и можете создавать несколько дочерних API-ключей для перепродажи своим клиентам или команде, каждый со своей квотой. Открытый API предоставляет эти возможности панели в виде REST-эндпоинтов:

• Чтение — баланс и расход аккаунта, ежедневный расход за последние 7 / 30 дней, список всех дочерних API-ключей с расходом по каждому.
• Запись — создание дочернего API-ключа (открытый ключ возвращается один раз), включение / отключение дочернего ключа, изменение квоты и параллелизма ключа.

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

2. Как стать партнёром (предварительное условие)¶

Этот API доступен только после одобрения партнёрского доступа.

• Ещё не партнёр → перейдите на страницу Партнёрская программа, ознакомьтесь с уровнями и тарифами и подайте заявку через раздел «Как подать заявку» (e-mail hi@qcode.cc). После одобрения ваш аккаунт активируется как партнёрский.
• Уже партнёр → войдите в партнёрскую панель.

Подключение включает предоплату и партнёрский уровень (A–E, у каждого свой множитель скидки); подробности — на странице Партнёрская программа. Вызов API на неактивированном аккаунте возвращает 403.

3. Быстрый старт: получение токена доступа¶

После одобрения:

1. Войдите на qcode.cc → откройте партнёрскую панель.
2. Откройте раздел «Open API / Токен доступа».
3. Нажмите Сгенерировать токен — получите токен вида rsk_xxxxxxxx.

🔑 Токен полностью показывается только один раз — при генерации или сбросе. Скопируйте и сохраните его в надёжном месте (мы храним только его хэш). При потере или утечке нажмите Сброс на той же странице, чтобы заменить токен; старый токен сразу перестаёт работать.

4. Аутентификация и адрес¶

curl https://api.r.qcode.cc/api/v1/reseller/balance \
  -H "Authorization: Bearer rsk_xxxxxxxx"

5. Справочник эндпоинтов¶

Все эндпоинты находятся под префиксом /api/v1/reseller/.

6. Создание дочернего API-ключа¶

Лимиты указываются в USD вышестоящего провайдера (upstream USD). daily_cost_limit_usd и total_cost_limit_usd должны быть больше 0. Передайте заголовок Idempotency-Key, чтобы повторные запросы были безопасны (чтобы повтор при таймауте не создал два ключа). Открытый ключ cr_… возвращается только один раз — сохраните его и передайте клиенту.

curl -X POST https://api.r.qcode.cc/api/v1/reseller/keys \
  -H "Authorization: Bearer rsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: уникально-для-каждого-создания" \
  -d '{"description":"client-a","daily_cost_limit_usd":5,"total_cost_limit_usd":100,"concurrency_limit":5}'

# → {"ok":true,"data":{"id":"...","name":"...","api_key":"cr_...","warnings":[]}}

Включение / отключение, изменение квоты:

# отключить
curl -X POST https://api.r.qcode.cc/api/v1/reseller/keys/{id}/disable \
  -H "Authorization: Bearer rsk_xxxxxxxx"

# изменить дневной лимит
curl -X PATCH https://api.r.qcode.cc/api/v1/reseller/keys/{id} \
  -H "Authorization: Bearer rsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"daily_cost_limit_usd":10}'

7. Ограничения частоты запросов¶

Это эндпоинты для нечастого управления, поэтому действуют ограничения частоты, снижающие риск при утечке токена:

• На токен: 60 / минуту, 1000 / сутки.
• Создание ключей (POST /keys): 5 / час на токен.
• При превышении возвращается HTTP 429 с заголовком Retry-After (в секундах).

8. Ответы и ошибки¶

• Успех: {"ok": true, "data": { ... }}
• Ошибка: соответствующий HTTP-статус + {"detail": "..."}

9. Безопасность¶

• Относитесь к токену доступа как к паролю: храните его на сервере, только по HTTPS, никогда не коммитьте в репозиторий и не раскрывайте в браузере.
• При утечке токена → немедленно сбросьте его в панели (старый токен умирает) и при необходимости отключите затронутые дочерние ключи.
• Задавайте разумные лимиты total / daily для каждого создаваемого ключа, чтобы ограничить ущерб при утечке одного ключа.
• Дочерние ключи cr_…, которые вы выдаёте, расходуют баланс вашего аккаунта — управляйте ими и сверяйте расход внимательно.

10. Полный справочник и поддержка¶

• После одобрения страница «API Docs» внутри партнёрской панели (/reseller/api-docs) — это авторитетный, версионируемый справочник для разработчиков.
• Ещё не партнёр? → Узнайте о программе и подайте заявку
• Вопросы? → онлайн-чат на сайте или e-mail hi@qcode.cc.