# Руководство по открытому API для партнёров Открытый API для партнёров QCode позволяет управлять вашим партнёрским (реселлерским) аккаунтом программно — проверять баланс и расход, создавать и управлять дочерними API-ключами, которые вы перепродаёте, — чтобы встроить выпуск ключей, сверку и выдачу в собственные системы вместо ручной работы в веб-панели. > ⚠️ **Предварительное условие: сначала нужно стать одобренным партнёром.** > Этот API доступен **только одобренным партнёрам QCode**. Если вы ещё не партнёр, [сначала подайте заявку](https://qcode.cc/partner-program); после одобрения вы сможете сгенерировать токен доступа и вызывать API. --- ## 1. Что умеет этот API Будучи партнёром QCode, вы получаете партнёрский аккаунт (предоплаченный баланс, множитель скидки в зависимости от уровня) и можете создавать несколько **дочерних API-ключей** для перепродажи своим клиентам или команде, каждый со своей квотой. Открытый API предоставляет эти возможности панели в виде REST-эндпоинтов: - **Чтение** — баланс и расход аккаунта, ежедневный расход за последние 7 / 30 дней, список всех дочерних API-ключей с расходом по каждому. - **Запись** — создание дочернего API-ключа (открытый ключ возвращается один раз), включение / отключение дочернего ключа, изменение квоты и параллелизма ключа. Подходит партнёрам, которым нужно встроить выпуск ключей и сверку в собственную биллинговую систему, автоматически выдавать ключи клиентам или периодически выгружать статистику для мониторинга. --- ## 2. Как стать партнёром (предварительное условие) Этот API доступен **только после одобрения партнёрского доступа**. - **Ещё не партнёр** → перейдите на страницу [Партнёрская программа](https://qcode.cc/partner-program), ознакомьтесь с уровнями и тарифами и подайте заявку через раздел «Как подать заявку» (e-mail `hi@qcode.cc`). После одобрения ваш аккаунт активируется как партнёрский. - **Уже партнёр** → войдите в [партнёрскую панель](https://qcode.cc/reseller/dashboard). > Подключение включает предоплату и партнёрский уровень (A–E, у каждого свой множитель скидки); подробности — на странице [Партнёрская программа](https://qcode.cc/partner-program). Вызов API на неактивированном аккаунте возвращает `403`. --- ## 3. Быстрый старт: получение токена доступа После одобрения: 1. Войдите на [qcode.cc](https://qcode.cc) → откройте **партнёрскую панель**. 2. Откройте раздел **«Open API / Токен доступа»**. 3. Нажмите **Сгенерировать токен** — получите токен вида `rsk_xxxxxxxx`. > 🔑 **Токен полностью показывается только один раз — при генерации или сбросе.** Скопируйте и сохраните его в надёжном месте (мы храним только его хэш). При потере или утечке нажмите **Сброс** на той же странице, чтобы заменить токен; **старый токен сразу перестаёт работать**. --- ## 4. Аутентификация и адрес | Параметр | Значение | |---|---| | Основной адрес (рекомендуется) | `https://api.r.qcode.cc` | | Резервный | `https://qcode.cc` (тот же API) | | Аутентификация | Заголовок `Authorization: Bearer rsk_xxxxxxxx` | | Тело запроса (запись) | JSON, с `Content-Type: application/json` | ```bash curl https://api.r.qcode.cc/api/v1/reseller/balance \ -H "Authorization: Bearer rsk_xxxxxxxx" ``` --- ## 5. Справочник эндпоинтов Все эндпоинты находятся под префиксом `/api/v1/reseller/`. | Метод | Путь | Описание | |---|---|---| | GET | `/api/v1/reseller/me` | Сводка аккаунта (уровень, регион, валюта, статус) | | GET | `/api/v1/reseller/balance` | Баланс и расход (в вашей валюте расчётов) | | GET | `/api/v1/reseller/usage?range=7d` | Серия ежедневного расхода (`range` = `7d` / `30d`) | | GET | `/api/v1/reseller/keys` | Список ваших дочерних API-ключей + расход по каждому | | GET | `/api/v1/reseller/keys/{id}` | Детали одного ключа | | POST | `/api/v1/reseller/keys` | Создать дочерний ключ (**открытый ключ возвращается один раз**) | | POST | `/api/v1/reseller/keys/{id}/enable` | Включить ключ | | POST | `/api/v1/reseller/keys/{id}/disable` | Отключить ключ | | PATCH | `/api/v1/reseller/keys/{id}` | Изменить квоту / параллелизм | --- ## 6. Создание дочернего API-ключа Лимиты указываются в **USD вышестоящего провайдера (upstream USD)**. `daily_cost_limit_usd` и `total_cost_limit_usd` должны быть **больше 0**. Передайте заголовок `Idempotency-Key`, чтобы повторные запросы были безопасны (чтобы повтор при таймауте не создал два ключа). Открытый ключ `cr_…` возвращается **только один раз** — сохраните его и передайте клиенту. ```bash 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":[]}} ``` Включение / отключение, изменение квоты: ```bash # отключить 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": "..."}` | Статус | Значение | |---|---| | 401 | Неверный или отсутствующий токен | | 403 | Аккаунт не активен (партнёрский доступ не одобрен или приостановлен) | | 404 | Ключ не найден или не принадлежит вам | | 422 | Ошибка валидации или квоты | | 429 | Превышен лимит частоты | --- ## 9. Безопасность - Относитесь к токену доступа как к паролю: храните его на сервере, только по HTTPS, **никогда** не коммитьте в репозиторий и не раскрывайте в браузере. - При утечке токена → немедленно **сбросьте** его в панели (старый токен умирает) и при необходимости отключите затронутые дочерние ключи. - Задавайте разумные лимиты `total` / `daily` для каждого создаваемого ключа, чтобы ограничить ущерб при утечке одного ключа. - Дочерние ключи `cr_…`, которые вы выдаёте, расходуют баланс вашего аккаунта — управляйте ими и сверяйте расход внимательно. --- ## 10. Полный справочник и поддержка - После одобрения страница **«API Docs»** внутри партнёрской панели (`/reseller/api-docs`) — это авторитетный, версионируемый справочник для разработчиков. - Ещё не партнёр? → [Узнайте о программе и подайте заявку](https://qcode.cc/partner-program) - Вопросы? → онлайн-чат на сайте или e-mail `hi@qcode.cc`.