Гейминг ГудсГейминг Гудс
Buyer API

Buyer API — документация

API для покупателей: реселлеров, MCP-клиентов и B2B-партнёров. Интегрируйте каталог Gaming Goods в свои приложения — REST с JSON-ответами, JWT-аутентификацией и предсказуемой структурой ошибок. Продавцам — Seller API.

Base URL

Production
https://gaming-goods.ru/api/v1

Все эндпоинты начинаются с этого базового URL. Ответы возвращаются в формате JSON.

Аутентификация

Есть несколько схем доступа — выбирайте по сценарию:

СхемаГдеДля чего
JWT BearerAuthorizationПользовательский flow (выдаётся после SMS). Заказы от лица пользователя.
gg_live_… BearerAuthorizationPublic API (B2B): каталог + заказы по ключу. Ключ выдаём под интеграцию; при ротации старый инвалидируется.
MCP OAuth 2.1BearerДля AI-агентов через MCP-канал (см. раздел «MCP-канал»).
Partner API keyAuthorizationLegacy Partner API. Каталог партнёра публичен; корзина/заказы/seller требуют ключ.
HTTP Header (JWT или gg_live_)
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Authorization: Bearer gg_live_xxxxxxxxxxxxxxxxxxxx

Публичные эндпоинты (каталог, поиск, категории, бренды) доступны без токена. За получением gg_live_-ключа обращайтесь на ceo@vvv.cash.

Каталог товаров

GET/products

Возвращает список товаров с пагинацией и фильтрами.

ПараметрТипОписание
categorystringФильтр по категории (например, Steam, Xbox)
brandstringФильтр по бренду
localestringЛокаль ответа: ru или en
sortstringСортировка: price_asc, price_desc, name, newest
pageintegerНомер страницы (по умолчанию 1)
page_sizeintegerКоличество на странице (по умолчанию 20, макс. 100)
Response
{
  "data": {
    "products": [
      {
        "id": "a1b2c3d4-...",
        "name": "Cyberpunk 2077",
        "slug": "cyberpunk-2077-steam-key",
        "category": "Steam",
        "brand": "CD Projekt",
        "price": 19.99,
        "currency": "EUR",
        "stock_quantity": 12,
        "image_url": "https://gaming-goods.ru/...",
        "is_active": true
      }
    ],
    "total": 1542,
    "page": 1,
    "page_size": 20
  }
}

Детали товара

GET/products/:slug

Возвращает полную информацию о товаре по его slug.

Response
{
  "data": {
    "id": "a1b2c3d4-...",
    "name": "Cyberpunk 2077",
    "slug": "cyberpunk-2077-steam-key",
    "category": "Steam",
    "brand": "CD Projekt",
    "description": "Открытый мир в жанре...",
    "price": 19.99,
    "currency": "EUR",
    "stock_quantity": 12,
    "image_url": "https://gaming-goods.ru/...",
    "is_active": true,
    "meta": { "activation_details": "..." }
  }
}

Поиск

GET/products/search

Полнотекстовый поиск по каталогу товаров.

ПараметрТипОписание
qstringПоисковый запрос (минимум 2 символа)
localestringЛокаль ответа: ru или en
pageintegerНомер страницы
page_sizeintegerКоличество на странице
Response
{
  "data": {
    "products": [
      {
        "id": "a1b2c3d4-...",
        "name": "Cyberpunk 2077",
        "slug": "cyberpunk-2077-steam-key",
        "price": 19.99,
        "stock_quantity": 12,
        "is_active": true
      }
    ],
    "total": 3,
    "page": 1,
    "page_size": 20
  }
}

Категории

GET/categories

Возвращает список всех категорий с количеством товаров в каждой.

Response
{
  "data": [
    { "name": "Steam", "product_count": 842 },
    { "name": "Xbox", "product_count": 215 },
    { "name": "PlayStation", "product_count": 187 },
    { "name": "Nintendo", "product_count": 94 }
  ]
}

Бренды

GET/brands

Возвращает список всех брендов с количеством товаров.

Response
{
  "data": [
    { "name": "Microsoft", "product_count": 312 },
    { "name": "Electronic Arts", "product_count": 198 },
    { "name": "Ubisoft", "product_count": 156 }
  ]
}

Создание заказа

POST/orders

Создаёт новый заказ. Требуется аутентификация. Заголовок Idempotency-Key ОБЯЗАТЕЛЕН (с GG-278) — без него вернётся 400 MISSING_IDEMPOTENCY_KEY.

ПараметрТипОписание
Idempotency-KeyheaderОБЯЗАТЕЛЬНО. UUID для защиты от дублирования заказа при ретраях
Request Body
{
  "items": [
    {
      "product_id": "a1b2c3d4-...",
      "quantity": 1
    }
  ],
  "payment_method": "balance",
  "promo_code": "SALE10"
}
Response
{
  "data": {
    "id": "e5f6a7b8-...",
    "status": "pending_payment",
    "items": [
      {
        "product_id": "a1b2c3d4-...",
        "product_name": "Cyberpunk 2077",
        "price": 1999,
        "quantity": 1
      }
    ],
    "total": 1799,
    "currency": "EUR",
    "payment_url": "https://...",
    "created_at": "2026-07-13T12:00:00Z"
  }
}

Статус заказа

GET/orders/:id

Возвращает детали заказа включая ключи активации (после оплаты). Требуется аутентификация.

Response
{
  "data": {
    "id": "e5f6a7b8-...",
    "status": "completed",
    "items": [
      {
        "product_id": "a1b2c3d4-...",
        "product_name": "Cyberpunk 2077",
        "price": 1999,
        "quantity": 1,
        "keys": ["XXXXX-XXXXX-XXXXX-XXXXX"]
      }
    ],
    "total": 1999,
    "currency": "EUR",
    "created_at": "2026-07-13T12:00:00Z",
    "completed_at": "2026-07-13T12:00:05Z"
  }
}

Public API (Pub) — B2B

Платный B2B-канал с ключом Authorization: Bearer gg_live_…. Отдаёт «полный-но-маскированный» каталог (без раскрытия поставщика) и позволяет создавать заказы. Base URL: https://gaming-goods.ru/api/v1/pub.

curl-примеры (подставьте свой gg_live_-ключ)
KEY="gg_live_xxxxxxxxxxxxxxxxxxxx"

# 1) Список каталога
curl -sS -H "Authorization: Bearer $KEY" \
  "https://gaming-goods.ru/api/v1/pub/products?q=cyberpunk&page_size=1"

# 2) Детали товара
curl -sS -H "Authorization: Bearer $KEY" \
  "https://gaming-goods.ru/api/v1/pub/products/cyberpunk-2077-steam-key"

# 3) Создание заказа (recipient_data — для recipient-товаров)
curl -sS -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"items":[{"gg_product_id":"a1b2c3d4-...","quantity":1}],"idempotency_key":"550e8400-e29b-41d4-a716-446655440000"}' \
  "https://gaming-goods.ru/api/v1/pub/orders"

# 4) Детали заказа
curl -sS -H "Authorization: Bearer $KEY" \
  "https://gaming-goods.ru/api/v1/pub/orders/e5f6a7b8-..."

Pub: Каталог

GET/pub/products

Список товаров с фильтрами и пагинацией. Требует Bearer gg_live_. provider_type маскируется как "marketplace".

ПараметрТипОписание
brandstringФильтр по бренду
categorystringФильтр по категории
qstringПоиск по названию
min_price / max_pricenumberДиапазон цены
page / page_sizeintegerПагинация (page_size ≤ 500)
Response
{
  "products": [
    {
      "gg_product_id": "a1b2c3d4-...",
      "slug": "cyberpunk-2077-steam-key",
      "name": "Cyberpunk 2077",
      "provider_type": "marketplace",
      "price": 19.99,
      "currency": "EUR",
      "stock_quantity": 12,
      "delivery_type": "playwallet",
      "moderation_status": "approved",
      "is_active": true,
      "steam_app_id": 1091500,
      "steam_url": "https://store.steampowered.com/app/1091500/"
    }
  ],
  "total": 1542,
  "page": 1,
  "page_size": 100
}

Pub: Детали товара

GET/pub/products/{slug}

Полная карточка товара по slug. Требует Bearer gg_live_.

Response
{ "product": { "gg_product_id": "...", "slug": "...", "steam_app_id": 1091500, "steam_url": "https://store.steampowered.com/app/1091500/" } }

Pub: Создание заказа

POST/pub/orders

Создаёт заказ по каталогу. Для recipient-товаров обязателен recipient_data (см. раздел). idempotency_key — поле тела (если не задано, генерируется автоматически; для защиты от дублей при ретраях задавайте свой).

Request Body
{
  "items": [{ "gg_product_id": "a1b2c3d4-...", "quantity": 1 }],
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "recipient_data": { "steam_login": "user123" }
}
Response
{ "data": { "id": "e5f6a7b8-...", "status": "pending_payment", "total": 1999, "currency": "EUR" } }

Pub: Детали заказа

GET/pub/orders/{id}

Статус и содержимое заказа, включая ключи после выполнения. Требует Bearer gg_live_.

Response
{ "data": { "id": "e5f6a7b8-...", "status": "completed", "delivery": { "codes": ["XXXXX-XXXXX"] } } }

Pub: Баланс (в review)

GET/pub/balance

Текущий баланс партнёра. Эндпоинт в review (GG-393) — уточните доступность перед использованием.

Response
{ "data": { "balance": 125000, "currency": "EUR" } }

Контракт recipient_data

Для товаров с доставкой на получателя нужно передавать объект recipient_data при создании заказа (POST /pub/orders и POST /buyer/checkout/virtual). Какое поле нужно — определяется по delivery_type товара (REST-каталог не отдаёт отдельного recipient_requirement — ориентируйтесь на delivery_type).

delivery_typeполедля чего
fragmenttelegram_usernameTelegram Stars / Premium. Формат: @username (5–32, [a-zA-Z0-9_])
playwalletsteam_loginПополнение Steam-кошелька. Логин 3–32 символа
manual_giftrecipient_emailClaude / Anthropic и другие email-подписки
Пример в теле заказа
"recipient_data": {
  "telegram_username": "@durov"   // fragment
  // "steam_login": "user123"     // playwallet
  // "recipient_email": "u@mail.com" // manual_gift
}

Ошибки валидации: recipient_required (поле не передано), recipient_invalid (формат неверный) — HTTP 422.

MCP-канал (для AI-агентов)

MCP-сервер по адресу https://gaming-goods.ru/mcp — для интеграции с AI-клиентами (Claude Desktop, ChatGPT Custom Connector и др.) поверх OAuth 2.1. Транспорт — JSON-RPC поверх HTTP/SSE.

OAuth endpointметодназначение
/mcp/.well-known/oauth-authorization-serverGETDiscovery-метадата (RFC 8414). Также /mcp/.well-known/oauth-protected-resource
/mcp/registerPOSTDynamic Client Registration (DCR)
/mcp/authorizeGETAuthorization Code + PKCE (S256)
/mcp/tokenPOSTОбмен кода на токен; grants: authorization_code, refresh_token
/mcp/revokePOSTОтзыв токена

Доступные MCP-инструменты: search, get_product, add_to_cart, view_cart, remove_from_cart, clear_cart, create_checkout_link. Scope mcp. Инструменты search/get_product отдают requires_recipient + recipient_schema.

Partner API

Partner API предназначен для интеграции сторонних площадок. Аутентификация через заголовок X-API-Key. Для получения ключа обратитесь на ceo@vvv.cash.

Base URL
https://gaming-goods.ru/api/partner/v1

Partner: Бренды

GET/catalog/brands

Возвращает список брендов с количеством доступных товаров.

ПараметрТипОписание
limitintegerКоличество (по умолчанию 20, макс. 100)
offsetintegerСмещение для пагинации
Response
{
  "items": [
    { "brand": "Steam", "product_count": 842 },
    { "brand": "Xbox", "product_count": 215 }
  ],
  "limit": 20,
  "offset": 0,
  "total": 156
}

Partner: Категории бренда

GET/catalog/brands/{brand}/categories

Возвращает категории товаров для указанного бренда.

Response
{
  "brand": "Steam",
  "categories": [
    { "category": "Game Keys", "product_count": 650 },
    { "category": "Gift Card", "product_count": 42 }
  ]
}

Partner: Каталог товаров

GET/catalog/products

Возвращает товары с пагинацией. Цены в евроцентах. product_type=KINGUIN — маркер поставщика.

ПараметрТипОписание
brandstringФильтр по бренду
categorystringФильтр по категории
searchstringПоиск по названию
updated_sincestringRFC3339. Инкрементальная выгрузка изменённых товаров
platform / platformsstringПлатформа (одиночная / множественная)
genres / regions / activationsstringМножественные фильтры по атрибутам
typestringТип товара
providerstringkinguin | dpgame | bamboo | c2c
min_price / max_priceintegerДиапазон цены (евроценты)
min_discountinteger1–100. Скидка к Steam-цене (нужен курс EUR→RUB)
sortstringprice_asc, price_desc, newest, relevance
limit / offsetintegerПагинация
Response
{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "title": "Cyberpunk 2077 Steam Key",
      "brand": "CD Projekt",
      "category": "Game Keys",
      "genres": ["RPG"],
      "platform": "Steam",
      "activation_type": "steam",
      "region": "GLOBAL",
      "price": 1999,
      "currency": "EUR",
      "quantity": 12,
      "is_available": true,
      "delivery_type": "EXTERNAL",
      "product_type": "KINGUIN",
      "images": ["https://gaming-goods.ru/..."],
      "short_description": "",
      "steam_app_id": 1091500,
      "steam_url": "https://store.steampowered.com/app/1091500/"
    }
  ],
  "total": 1542,
  "limit": 20,
  "offset": 0
}

Partner: Детали товара

GET/catalog/products/{productId}

Полная информация о товаре по его UUID. steam_discount_percent, steam_app_id, steam_url, activation_instructions — присутствуют только при наличии данных (для Kinguin с verified-матчем).

Response
{
  "id": "a1b2c3d4-...",
  "title": "Cyberpunk 2077 Steam Key",
  "brand": "CD Projekt",
  "category": "Game Keys",
  "genres": ["RPG"],
  "platform": "Steam",
  "activation_type": "steam",
  "region": "GLOBAL",
  "price": 1999,
  "currency": "EUR",
  "quantity": 12,
  "is_available": true,
  "delivery_type": "EXTERNAL",
  "product_type": "KINGUIN",
  "images": ["https://gaming-goods.ru/..."],
  "description": "Открытый мир в жанре...",
  "short_description": "",
  "specifications": [ { "key": "platform", "value": "Steam" } ],
  "steam_discount_percent": 42,
  "steam_app_id": 1091500,
  "steam_url": "https://store.steampowered.com/app/1091500/",
  "activation_instructions": "..."
}

Partner: Оформление заказа

POST/buyer/checkout/virtual

Создаёт заказ. Источник: "cart" (из корзины) или "lines" (товары в запросе). Требуется X-API-Key.

Request Body
// Из корзины:
{ "source": "cart" }

// Или с указанием товаров:
{
  "source": "lines",
  "lines": [
    { "product_id": "a1b2c3d4-...", "quantity": 1 }
  ]
}
Response
{
  "orders": [
    {
      "id": "e5f6a7b8-...",
      "status": "created",
      "total": 1999,
      "currency": "EUR"
    }
  ]
}

Partner: Список заказов

GET/buyer/orders

Возвращает список заказов партнёра с пагинацией. Требуется X-API-Key.

ПараметрТипОписание
limitintegerКоличество (по умолчанию 20)
offsetintegerСмещение
statusstringФильтр по статусу (created, paid, completed, cancelled_before_payment, cancelled_after_payment)
Response
{
  "items": [
    {
      "id": "e5f6a7b8-...",
      "status": "completed",
      "total": 1999,
      "currency": "EUR",
      "created_at": "2026-07-13T12:00:00Z"
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 47
}

Partner: Детали заказа

GET/buyer/orders/{orderId}

Детали заказа. Ключи доступны в delivery.codes после выполнения. Требуется X-API-Key.

Response
{
  "id": "e5f6a7b8-...",
  "buyer_id": "c3d4e5f6-...",
  "status": "completed",
  "items": [
    {
      "product_id": "a1b2c3d4-...",
      "title": "Cyberpunk 2077 Steam Key",
      "unit_price": 1999,
      "quantity": 1
    }
  ],
  "amounts": {
    "buyer_total": 1999,
    "platform_fee": 0
  },
  "payment": {
    "method": "balance",
    "state": "paid"
  },
  "delivery": {
    "type": "EXTERNAL",
    "codes": ["XXXXX-XXXXX-XXXXX"]
  },
  "created_at": "2026-07-13T12:00:00Z",
  "updated_at": "2026-07-13T12:00:05Z"
}

Rate Limiting

Лимиты зависят от типа доступа. При превышении сервер вернёт 429 Too Many Requests с заголовком Retry-After. Рекомендуем экспоненциальный backoff.

ДоступВ минутуВ сутки
Публичный каталог (без токена)601000 — считается по IP
Public API (gg_live_…)600100 000 — считается по ключу (значения могут отличаться для вашего ключа)
Partner API—Лимит не применяется; используйте разумную нагрузку и пагинацию

Заголовки ответа для лимитируемых эндпоинтов (имена регистронезависимы; по HTTP/2 передаются в нижнем регистре). X-RateLimit-Reset — Unix-время сброса окна.

Response Headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1784617860
X-Request-ID: 500c767f-6e64-4d35-b2bd-1c7698befae7

Формат ошибок

Все ошибки возвращаются в едином конверте { "error": { "code", "message" } }. На REST-поверхностях (публичный API, Public API, Partner API, Seller API) коды в стиле UPPER_SNAKE (напр. VALIDATION_ERROR). Исключение — слой MCP OAuth 2.1: там коды в нижнем регистре по спецификации OAuth (invalid_request, invalid_grant, invalid_token).

Error Response (REST)
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Parameter 'page' must be a positive integer"
  }
}
400VALIDATION_ERROR / MISSING_IDEMPOTENCY_KEY — неверные параметры или отсутствует обязательный заголовок
401UNAUTHORIZED — отсутствует или невалидный токен/ключ
403FORBIDDEN — недостаточно прав
404NOT_FOUND — ресурс не найден
422recipient_required / recipient_invalid — не передан или некорректен recipient_data
429RATE_LIMIT — превышен лимит запросов (см. Retry-After)
500INTERNAL_ERROR — ошибка на сервере

Изменения (Changelog)

07-13Актуализация под прод: реальные rate-limit (60/600), Public API (Pub), MCP-канал (OAuth 2.1), контракт recipient_data, steam_app_id/steam_url в каталоге, Idempotency-Key обязателен на /orders. (GG-408)

Последняя правка: 13 июля 2026.

Получить доступ к API

Для получения API-токена и обсуждения интеграции обратитесь к нам по электронной почте.

ceo@vvv.cashMCP-интеграция