API — Magic Subs

01

Быстрый старт

Нужен API-ключ?

Напишите нам, и мы выдадим отдельный ключ для вашей интеграции.

Получить API-ключ

1 Проверьте CDK

Метод /cards/check показывает, доступен ли ключ. Проверка не списывает ключ.

2 Получите ID аккаунта

ID зависит от продукта: Claude ID, Grok User ID или X Account ID.

3 Создайте активацию

Метод /activations закрепляет ID за ключом, запускает пополнение и возвращает task_id.

4 Покажите результат

Проверяйте статус по task_id до completed или failed.

02

Доступ и формат

Авторизация

Защищенные методы требуют API-ключ. Передавайте его в заголовке Authorization или X-API-Key.

Authorization: Bearer cdk_live_your_api_key

Язык ошибок

API возвращает понятные сообщения на русском или английском. Язык можно выбрать заголовком Accept-Language.

Accept-Language: ru
Accept-Language: en

Лимит

Стандартный лимит: 120 запросов в минуту на один API-ключ. При превышении вернется rate_limited.

Безопасность

Не храните рабочий ключ в открытом JavaScript, публичном GitHub или клиентской части бота. Серверная интеграция безопаснее.

Единый формат ответа

Успешный ответ

{
  "success": true,
  "data": {
    "...": "..."
  }
}

Ошибка

{
  "success": false,
  "error": {
    "code": "card_used",
    "message": "Этот ключ уже был использован."
  }
}

03

Процесс активации

Не нужно собирать цепочку из нескольких отдельных запросов. Один метод POST /activations делает все нужное: проверяет ключ, закрепляет ID аккаунта, запускает пополнение и возвращает задачу для отслеживания.

check Проверка ключа

Ключ должен быть доступен и соответствовать выбранному продукту.

bind Привязка ID

account_id закрепляется за CDK-ключом. После успешного запуска менять ID нельзя.

run Запуск пополнения

API создает задачу и возвращает task_id.

status Ожидание статуса

Сохраняйте task_id у себя в заказе и проверяйте результат по нему.

04

Продукты и ID аккаунта

product_type всегда обязателен. account_id — это ID аккаунта, на который будет выполнено пополнение.

product_type Продукт Что передавать в account_id

claude_pro Claude Pro Claude ID / organization ID из аккаунта Claude.

grok_pro SuperGrok Grok User ID из аккаунта Grok.

x_premium X Premium X Account ID / obfuscated ID аккаунта X.

Важно для Claude Pro

Перед активацией аккаунт должен быть на Free-плане. На аккаунте не должно быть активного платного тарифа, просроченных счетов или неоплаченных инвойсов.

05

Методы API

GET /health

Проверка доступности API. Авторизация не требуется.

curl https://cdk.sale/api/v1/health

{
  "success": true,
  "data": {
    "service": "Magic Subs API",
    "version": "1.0.0",
    "status": "ok"
  }
}

GET /products

Список поддерживаемых продуктов. Авторизация не требуется.

curl https://cdk.sale/api/v1/products

{
  "success": true,
  "data": [
    { "product_type": "claude_pro", "name": "Claude Pro" },
    { "product_type": "grok_pro", "name": "SuperGrok" },
    { "product_type": "x_premium", "name": "X Premium" }
  ]
}

POST /cards/check

Проверяет один CDK-ключ. Метод ничего не активирует и не списывает.

code

Обязательный CDK-ключ. Можно также передать поле card_key.

product_type

Необязателен для простой проверки, но рекомендуется. Если продукт не совпадает, вернется product_mismatch.

curl -X POST https://cdk.sale/api/v1/cards/check \
  -H "Authorization: Bearer cdk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"code\":\"EEE-XXXXXXXXXXXXXX\",\"product_type\":\"claude_pro\"}"

{
  "success": true,
  "data": {
    "available": true,
    "status": "unused",
    "product_type": "claude_pro",
    "message": "Ключ доступен."
  }
}

POST /cards/batch-check

Проверяет до 100 CDK-ключей за один запрос. Подходит для кабинета реселлера, CRM или бота.

codes

Массив CDK-ключей. Можно также передать card_keys.

product_type

Необязательный фильтр по продукту.

{
  "codes": [
    "EEE-XXXXXXXXXXXXXX",
    "GGG-XXXXXXXXXXXXXX"
  ],
  "product_type": "claude_pro"
}

{
  "success": true,
  "data": [
    {
      "code": "EEE-XXXXXXXXXXXXXX",
      "available": true,
      "status": "unused",
      "product_type": "claude_pro"
    },
    {
      "code": "GGG-XXXXXXXXXXXXXX",
      "available": false,
      "status": "product_mismatch",
      "product_type": "grok_pro",
      "error": {
        "code": "product_mismatch",
        "message": "Ключ не подходит для выбранного продукта."
      }
    }
  ]
}

POST /activations

Создает активацию: проверяет CDK, привязывает ID аккаунта к ключу, запускает пополнение и возвращает task_id.

code

Обязательный CDK-ключ. Можно также передать card_key.

account_id

Обязательный ID аккаунта. Также принимаются алиасы user_id и claude_user_id.

product_type

Обязательный продукт: claude_pro, grok_pro или x_premium.

curl -X POST https://cdk.sale/api/v1/activations \
  -H "Authorization: Bearer cdk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"code\":\"EEE-XXXXXXXXXXXXXX\",\"account_id\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\"product_type\":\"claude_pro\"}"

{
  "success": true,
  "data": {
    "task_id": "task_xxxxx",
    "status": "processing",
    "product_type": "claude_pro"
  }
}

GET /activations/{task_id}

Проверяет статус задачи. Передайте product_type в query string.

curl "https://cdk.sale/api/v1/activations/task_xxxxx?product_type=claude_pro" \
  -H "Authorization: Bearer cdk_live_your_api_key"

processing

Пополнение выполняется. Продолжайте проверять статус.

completed

Пополнение успешно завершено. Покажите пользователю успешный результат.

failed

Задача завершилась ошибкой. Покажите сообщение из error.message.

unknown

Задача не найдена или статус недоступен. Проверьте task_id.

{
  "success": true,
  "data": {
    "task_id": "task_xxxxx",
    "status": "completed",
    "product_type": "claude_pro",
    "message": "Активация успешно завершена."
  }
}

Альтернатива: /activations/status?task_id=task_xxxxx&product_type=claude_pro

06

Примеры кода

cURL: полный сценарий

# 1. Проверить ключ
curl -X POST https://cdk.sale/api/v1/cards/check \
  -H "Authorization: Bearer cdk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"code\":\"EEE-XXXXXXXXXXXXXX\",\"product_type\":\"claude_pro\"}"

# 2. Создать активацию
curl -X POST https://cdk.sale/api/v1/activations \
  -H "Authorization: Bearer cdk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"code\":\"EEE-XXXXXXXXXXXXXX\",\"account_id\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\"product_type\":\"claude_pro\"}"

# 3. Проверить статус
curl "https://cdk.sale/api/v1/activations/task_xxxxx?product_type=claude_pro" \
  -H "Authorization: Bearer cdk_live_your_api_key"

JavaScript: создать активацию

const BASE_URL = "https://cdk.sale/api/v1";
const API_KEY = "cdk_live_your_api_key";

async function createActivation({ code, accountId, productType }) {
  const response = await fetch(`${BASE_URL}/activations`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      "Accept-Language": "ru"
    },
    body: JSON.stringify({
      code,
      account_id: accountId,
      product_type: productType
    })
  });

  return response.json();
}

Python: ждать финального статуса

import time
import requests

BASE_URL = "https://cdk.sale/api/v1"
API_KEY = "cdk_live_your_api_key"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept-Language": "ru",
}

def wait_activation(task_id, product_type, attempts=120):
    for _ in range(attempts):
        response = requests.get(
            f"{BASE_URL}/activations/{task_id}",
            params={"product_type": product_type},
            headers=headers,
            timeout=20,
        )
        payload = response.json()
        status = payload.get("data", {}).get("status")

        if status in ("completed", "failed", "unknown"):
            return payload

        time.sleep(5)

    return {"success": False, "error": {"code": "timeout"}}

PHP: проверить список ключей

$apiKey = "cdk_live_your_api_key";
$payload = json_encode([
    "codes" => ["EEE-XXXXXXXXXXXXXX", "EEE-YYYYYYYYYYYYYY"],
    "product_type" => "claude_pro",
], JSON_UNESCAPED_UNICODE);

$ch = curl_init("https://cdk.sale/api/v1/cards/batch-check");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}",
        "Content-Type: application/json",
        "Accept-Language: ru",
    ],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

07

Ошибки

Проверяйте поле success. Если оно равно false, используйте error.code для логики и error.message для текста пользователю.

{
  "success": false,
  "error": {
    "code": "product_mismatch",
    "message": "Ключ не подходит для выбранного продукта."
  }
}

unauthorized

API-ключ не передан или неверный. Проверьте заголовок Authorization.

rate_limited

Слишком много запросов. Сделайте паузу и повторите запрос.

invalid_json

Тело запроса не является корректным JSON.

missing_code

Не передан CDK-ключ.

missing_codes

Не передан массив CDK-ключей для массовой проверки.

too_many_codes

В массовой проверке больше 100 ключей.

missing_account_id

Не передан ID аккаунта для активации.

missing_task_id

Не передан task_id для проверки статуса.

invalid_product

Некорректный или пустой product_type.

card_not_available

Ключ недоступен для активации.

card_used

Этот ключ уже был использован.

card_disabled

Ключ отключен.

product_mismatch

Ключ выпущен под другой продукт.

queue_busy

Не удалось попасть в очередь активации. Повторите через 1-5 минут.

no_stock

Временно нет доступного склада. Повторите позже.

task_in_progress

По этому ключу уже идет активация. Дождитесь завершения текущей задачи.

account_not_eligible

Аккаунт не подходит для пополнения. Проверьте ID, Free-план, активную подписку и неоплаченные счета.

activation_failed

Не удалось выполнить активацию. Проверьте данные и попробуйте еще раз.

upstream_unavailable

Сервис временно недоступен. Повторите запрос позже.

08

Правила интеграции

Один ключ — один аккаунт

После запуска активации CDK закрепляется за переданным account_id. Если ID указан неверно, ключ нельзя переназначить через API.

Сохраняйте task_id

Записывайте task_id в заказе, чтобы восстановить статус после перезагрузки страницы, сбоя бота или повторного обращения пользователя.

Не запускайте дубли

Если задача уже создана, проверяйте ее статус. Повторная активация того же ключа может вернуть task_in_progress или card_used.

Проверяйте продукт

Передавайте правильный product_type. Ключ Claude Pro не должен использоваться для SuperGrok или X Premium.

Показывайте понятные ошибки

Для пользователя используйте error.message. Для автоматической логики используйте стабильный error.code.

Храните ключ на сервере

Ваш backend должен вызывать Magic Subs API сам. Клиентскому браузеру или публичному мини-приложению API-ключ лучше не отдавать.

CDK API

Удобная интеграция в ваш проект

Быстрый старт

Доступ и формат

Единый формат ответа

Процесс активации

Продукты и ID аккаунта

Методы API

Примеры кода

cURL: полный сценарий

JavaScript: создать активацию

Python: ждать финального статуса

PHP: проверить список ключей

Ошибки

Правила интеграции