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

Встройте каталог Gaming Goods в приложение или бота: товары, цены, наличие, заказы — по ключу. Продавцам — Seller API.

Не хотите читать? Заберите документацию одним файлом для ИИ-ассистента.

Купить за 3 шага — просто скопируйте

Нужны ключ gg_live_… (см. «Получить ключ») и баланс аккаунта. Пополнить баланс: Профиль → Баланс на сайте или менеджер по счёту. Подставьте свои значения вместо слов КАПСОМ.

1. Найти товар и его ID

Поиск по каталогу

curl -sS \
  -H "Authorization: Bearer gg_live_ВАШ_КЛЮЧ" \
  "https://gaming-goods.ru/api/v1/pub/products?q=cyberpunk&page_size=5"

В ответе возьмите gg_product_id нужного товара — это ваш ID_ТОВАРА.

2. Купить (оплата с баланса)

Создать заказ

curl -sS -X POST \
  -H "Authorization: Bearer gg_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"lines":[{"product_id":"ID_ТОВАРА","quantity":1}],"recipient_data":{"recipient_email":"ваш@email"},"payment_method":"balance"}' \
  "https://gaming-goods.ru/api/v1/pub/orders"

В ответе — order_id (ваш ID_ЗАКАЗА). recipient_data — только для товаров с получателем, иначе уберите строку.

3. Статус заказа и где ключ

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

curl -sS \
  -H "Authorization: Bearer gg_live_ВАШ_КЛЮЧ" \
  "https://gaming-goods.ru/api/v1/pub/orders/ID_ЗАКАЗА"

Показывает статус. Ключа в ответе нет — он уходит на recipient_data или вебхуком order.delivered, и виден в аккаунте на сайте (Профиль → ключи).

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

Ключ — это пароль вашего приложения. Выглядит как gg_live_… и открывает Buyer API (/api/v1/pub/*): каталог, заказы и баланс под вашим аккаунтом.

Напишите на ceo@vvv.cash (или вашему менеджеру) — коротко опишите, что интегрируете. Мы заведём вам ключ и пришлём его на почту (или иным удобным способом).
Ключ вида gg_live_… действует год. Понадобится новый — просто напишите нам.
Для ИИ-агентов есть отдельный канал MCP с OAuth — см. блок «Продвинутое» и страницу MCP.

Запросить ключ MCP для ИИ-агентов

Основные операции

Заголовок Authorization: Bearer gg_live_…, база https://gaming-goods.ru/api/v1.

Pub: Каталог

GET/pub/products

Каталог с фильтрами и пагинацией. 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": "steam_topup",
      "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.

Response

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

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

POST/pub/orders

Создаёт заказ. Позиции в lines[] (product_id — UUID из каталога). payment_method: "balance" — с баланса; "sbp"/"card" — вернётся payment_url. idempotency_key — UUID от двойного заказа.

Request Body

{
  "lines": [{ "product_id": "a1b2c3d4-...", "quantity": 1 }],
  "recipient_data": { "steam_login": "user123" },
  "payment_method": "balance",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
}

Response

{ "data": { "id": "e5f6a7b8-...", "status": "pending_payment", "total": 1999, "currency": "EUR" } }

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

GET/pub/orders/{id}

Статус и состав заказа (status, payment_status, items). Ключа в ответе нет — см. «Важно знать».

Response

{
  "data": {
    "id": "e5f6a7b8-...",
    "order_number": 318000,
    "status": "completed",
    "payment_status": "charged",
    "total": 1999,
    "currency": "EUR",
    "items": [
      { "product_id": "a1b2c3d4-...", "title": "Cyberpunk 2077", "unit_price": 1999, "quantity": 1 }
    ],
    "created_at": "2026-07-13T12:00:00Z",
    "updated_at": "2026-07-13T12:00:05Z"
  }
}

Pub: Баланс

GET/pub/balance

Баланс аккаунта в евро.

Response

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

Важно знать

Цена (price) — в евро.
Оплата — с баланса (payment_method: "balance"). Пополнение: Профиль → Баланс или менеджер по счёту.
Ключ приходит на recipient_data или вебхуком order.delivered; в ответе заказа ключа нет.
Лимит 600 запросов/мин и 100 000/сутки на ключ; при превышении — 429 + Retry-After.
Песочница: ключ gg_test_ на sandbox.gaming-goods.ru.
Синхронизация: updated_since (товары) и since (заказы), формат RFC3339.
Ошибки — конверт {"error":{"code","message"}}.

Продвинутое: получатель заказа, вебхуки/MCP, Partner API, лимиты и полный reference

Получатель заказа (recipient_data)

Для товаров с получателем передайте recipient_data в POST /pub/orders. Поле зависит от delivery_type:

delivery_typeполедля чего

telegram_gifttelegram_usernameTelegram-получатель. Формат: @username (5–32, [a-zA-Z0-9_])

steam_topupsteam_loginПополнение Steam-кошелька. Логин 3–32 символа

manual_giftrecipient_emailClaude / Anthropic и другие email-подписки

Пример в теле заказа

"recipient_data": {
  "telegram_username": "@durov"   // telegram_gift
  // "steam_login": "user123"     // steam_topup
  // "recipient_email": "u@mail.com" // manual_gift
}

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

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

MCP-сервер https://gaming-goods.ru/mcp поверх OAuth 2.1 (JSON-RPC over HTTP/SSE). Ключ в URL: POST /api/v1/mcp/{api_key}.

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.

Partner API (legacy)

Старый канал для сторонних площадок. База https://gaming-goods.ru/api/partner/v1, ключ другого формата (не gg_live_). Каталог /catalog/* публичен; заказы — по ключу. У price масштаб зависит от валюты — читайте price_unit.

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

Товары с пагинацией. Берите price_total (= price + platform_fee). price_unit: minor — евроценты, major — целые рубли (X-Domain: ru).

ПараметрТипОписание

brandstringФильтр по бренду

categorystringФильтр по категории

searchstringПоиск по названию

updated_sincestringRFC3339. Инкрементальная выгрузка изменённых товаров

platform / platformsstringПлатформа (одиночная / множественная)

genres / regions / activationsstringМножественные фильтры по атрибутам

typestringТип товара

providerstrings1 | s2 | s3 | 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",
      "price_unit": "minor",
      "platform_fee": 199,
      "price_total": 2198,
      "quantity": 12,
      "is_available": true,
      "delivery_type": "EXTERNAL",
      "supply_type": "SUPPLIER",
      "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. price_total — к оплате; price_unit — единица (minor/major).

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",
  "price_unit": "minor",
  "platform_fee": 199,
  "price_total": 2198,
  "quantity": 12,
  "is_available": true,
  "delivery_type": "EXTERNAL",
  "supply_type": "SUPPLIER",
  "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" (товары в запросе). Требуется ключ партнёра (см. раздел «Partner API»).

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

Возвращает список заказов партнёра с пагинацией. Требуется ключ партнёра (см. раздел «Partner API»).

ПараметрТипОписание

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 после выполнения. Требуется ключ партнёра (см. раздел «Partner API»).

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"
}

Partner: Сверка заказов

GET/buyer/reconciliation

Сверка заказов: показанная сумма, списание, статус выдачи, возврат. Суммы в минорных единицах. format=csv — файлом.

ПараметрТипОписание

sincestringRFC3339 — заказы, созданные не раньше

untilstringRFC3339 — заказы, созданные раньше

channelstringКанал заказа, например partner

formatstringcsv — отдать файлом вместо JSON

limitintegerКоличество (по умолчанию 20, максимум 100)

offsetintegerСмещение

Response

{
  "items": [
    {
      "order_id": "e5f6a7b8-...",
      "order_number": 310213,
      "created_at": "2026-07-26T09:07:20Z",
      "channel": "partner",
      "channel_order_id": "",
      "order_status": "completed",
      "delivery_status": "delivered",
      "shown_amount": 1866,
      "charged_amount": 1866,
      "refunded_amount": 0,
      "currency": "EUR",
      "payment_method": "balance",
      "discrepancy": false
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 243
}

Partner: Выписка по пополнениям баланса

GET/buyer/balance-topups

Пополнения баланса: сумма платежа и зачисление. discrepancy=true — суммы различаются.

ПараметрТипОписание

sincestringRFC3339 — платежи не раньше

untilstringRFC3339 — платежи раньше

limitintegerКоличество (по умолчанию 20, максимум 100)

offsetintegerСмещение

Response

{
  "items": [
    {
      "payment_id": "9254f091-...",
      "created_at": "2026-07-16T09:19:24Z",
      "amount": 649,
      "credited_amount": 649,
      "credited_at": "2026-07-16T09:20:05Z",
      "currency": "EUR",
      "status": "completed",
      "provider": "card",
      "method": "card",
      "external_id": "de59b7c6-...",
      "discrepancy": false
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 29
}

Публичный каталог без ключа

Только каталог, без ключа: https://gaming-goods.ru/api/v1/products*. Лимит по IP: 60/мин, 1000/сутки.

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

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

regionstringКод региона (TR, RU, US, DE, GLOBAL…) или имя региона как в карточке. Код страны захватывает и общерегиональные, и глобальные ключи: region=TR вернёт и турецкие, и Global.

denominationstringНоминал карты пополнения: 50, 100, 1000

currencystringВалюта номинала: TRY, EUR, USD…

availabilitystringin_stock (по умолчанию) — только доступное к покупке; any — включая товары вне наличия

pageintegerНомер страницы

page_sizeintegerКоличество на странице

Response

{
  "data": {
    "products": [
      {
        "id": "a1b2c3d4-...",
        "name": "Steam Wallet Card 50 TRY",
        "slug": "steam-wallet-card-50-try",
        "price": 1290.00,
        "currency": "RUB",
        "stock_quantity": 12,
        "region_code": "TR",
        "platform": "Steam",
        "delivery_eta_category": "minutes",
        "delivery_eta_seconds": 90,
        "is_active": true
      }
    ],
    "total": 3,
    "page": 1,
    "page_size": 20
  }
}

region_code — ISO-код страны (TR, DE) или надрегион (GLOBAL, EU, NA, ASIA…).
delivery_eta_category — instant / minutes / hours / manual; delivery_eta_seconds — медиана разряда.

Категории

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

Создаёт заказ от лица пользователя (JWT). Idempotency-Key (UUID) защищает от двойного заказа.

ПараметрТипОписание

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"
  }
}

Лимиты и формат ошибок

Заголовки лимита в ответе

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1784617860
X-Request-ID: 500c767f-6e64-4d35-b2bd-1c7698befae7

Конверт ошибки (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 — ошибка на сервере

Полный машинный reference

API Reference (Redoc)Postman-коллекция OpenAPI 3.1 (JSON)

Получить ключ или обсудить интеграцию

Напишите нам — выпустим ключ Buyer API и поможем с интеграцией.

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