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

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

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

Base URL

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

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

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

API использует JWT Bearer-токены. Передавайте токен в заголовке Authorization каждого запроса. Токен выдаётся после авторизации через SMS или по запросу для интеграционных сценариев.

HTTP Header
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Публичные эндпоинты (каталог, поиск, категории, бренды) доступны без токена. Для создания и просмотра заказов требуется аутентификация.

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

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.

ПараметрТипОписание
Idempotency-KeyheaderUUID для предотвращения дублирования заказов
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-03-14T12: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-03-14T12:00:00Z",
    "completed_at": "2026-03-14T12:00:05Z"
  }
}

Partner API

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

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

Возвращает товары с пагинацией. Цены в евроцентах.

ПараметрТипОписание
brandstringФильтр по бренду
categorystringФильтр по категории
searchstringПоиск по названию
sortstringСортировка: price_asc, price_desc, newest
limitintegerКоличество (по умолчанию 20, макс. 100)
offsetintegerСмещение для пагинации
Response
{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "title": "Cyberpunk 2077 Steam Key",
      "brand": "CD Projekt",
      "category": "Game Keys",
      "price": 1999,
      "currency": "EUR",
      "quantity": 12,
      "is_available": true,
      "delivery_type": "EXTERNAL",
      "product_type": "KINGUIN",
      "images": ["https://gaming-goods.ru/..."],
      "short_description": ""
    }
  ],
  "total": 1542,
  "limit": 20,
  "offset": 0
}

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

GET/catalog/products/{productId}

Полная информация о товаре по его UUID.

Response
{
  "id": "a1b2c3d4-...",
  "title": "Cyberpunk 2077 Steam Key",
  "brand": "CD Projekt",
  "category": "Game Keys",
  "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" }
  ]
}

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-03-14T12: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-03-14T12:00:00Z",
  "updated_at": "2026-03-14T12:00:05Z"
}

Rate Limiting

API ограничивает количество запросов до 100 запросов в минуту на один IP-адрес. При превышении лимита сервер вернёт ответ с кодом 429 Too Many Requests. Рекомендуем использовать экспоненциальный backoff при повторных попытках.

Response Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1710403200

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

Все ошибки возвращаются в едином формате. Поле code содержит машиночитаемый идентификатор, message — человекочитаемое описание.

Error Response
{
  "error": {
    "code": "invalid_request",
    "message": "Parameter 'page' must be a positive integer"
  }
}
400Bad Request — неверные параметры запроса
401Unauthorized — отсутствует или невалидный токен
403Forbidden — недостаточно прав
404Not Found — ресурс не найден
429Too Many Requests — превышен лимит запросов
500Internal Server Error — ошибка на сервере

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

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

business@gaming-goods.comMCP-интеграция