GamesDrop.io API - Руководство для мерчантов

Добро пожаловать в документацию Partner API GamesDrop.io! Это руководство содержит все необходимое для интеграции вашей реселлерской платформы с сетью GamesDrop. Интегрируясь с нами, вы получаете доступ к нашему каталогу из более чем 10 000 цифровых продуктов: от пополнения мобильных операторов до внутриигровой валюты популярных мобильных игр. Начните здесь, чтобы оптимизировать свои предложения продуктов и подключить своих клиентов к миру цифровых товаров.

Оглавление

1. Авторизация
   • Получение токена
   • Безопасность токена
2. Основные концепции
   • Статусы заказов
   • Обработка ошибок
3. API Endpoints
   • Управление балансом
     • Проверка баланса
     • История транзакций
   • Управление товарами
   • Управление заказами
   • Валидация игрока
4. Тестирование API
   • Тестовый товар
5. Рекомендации по интеграции
6. Поддержка

Авторизация

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

Процесс получения

1. Войдите в личный кабинет мерчанта
2. Создайте новый магазин
3. После создания магазина вы получите уникальный токен
4. Формат токена: abcdef1234567890abcdef1234567890

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

• 🔒 Токен является конфиденциальной информацией
• ⚠️ Не передавайте токен третьим лицам
• 📝 Токен нельзя восстановить после создания
• 🔄 При необходимости можно сгенерировать новый токен (старый станет недействительным)

Основные концепции

Статусы заказов

Возможные ошибки

API Endpoints

Управление балансом

Проверка баланса

HTTP
GET /api/v1/balance
Authorization: {{token}}

Response:

JSON
{
  "balance": 500.00,
  "draftBalance": 50.00,
  "currency": {
    "id": 3,
    "code": "USD"
  }
}

Описание полей ответа:

История транзакций баланса

HTTP
GET /api/v1/balance/transactions?page=1&limit=20
Authorization: {{token}}

Response:

JSON
{
  "transactions": [
    {
      "id": 12,
      "amount": -75.00,
      "type": "PURCHASE",
      "description": "API Purchase - Virtual credits",
      "balanceAfter": 425.00,
      "createdAt": "2025-07-28T05:21:46.121Z"
    },
    {
      "id": 11,
      "amount": -50.00,
      "type": "PURCHASE",
      "description": "Test Purchase - Mobile game credits",
      "balanceAfter": 500.00,
      "createdAt": "2025-07-28T05:16:23.718Z"
    }
  ],
  "total": 25
}

Описание полей запроса:

Описание полей ответа:

Получение информации о товаре

HTTP
POST /api/v1/offers/find-one
Authorization: {{token}}

{
  "offerId": 1001
}

Response:

JSON
{
  "offerId": 1001,
  "productName": "PUBG MOBILE GIFT",
  "offerName": "60 UC",
  "count": 1,
  "price": 560.10,
  "currency": "RUB",
  "isReturnDataForCustomer": true
}

Описание полей запроса:

Описание полей ответа:

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

HTTP
POST /api/v1/offers/create-order
Authorization: {{token}}

{
  "offerId": 1001,
  "price": 560.10,
  "transactionId": "test112321124214",
  "customer": {
    "email": "user@gmail.com",
    "gameUserId": "52357322414"
  }
}

Описание полей запроса:

Response:

JSON
{
  "orderId": 10222502,
  "count": 1,
  "price": 560.10,
  "currency": "RUB",
  "offerId": 1001,
  "productName": "PUBG MOBILE GIFT",
  "offerName": "60 UC",
  "status": "COMPLETED",
  "isReturnDataForCustomer": true,
  "key": "001434249936",
  "createdAt": "2024-05-28 10:08:04.296+00"
}

Описание полей ответа:

Проверка статуса заказа

HTTP
POST /api/v1/offers/order-status
Authorization: {{token}}

{
  "orderId": 10222502
}

Описание полей запроса:

Response:

JSON
{
  "orderId": 10222502,
  "count": 1,
  "price": 560.10,
  "currency": "RUB",
  "offerId": 1001,
  "productName": "PUBG MOBILE GIFT",
  "offerName": "60 UC",
  "status": "COMPLETED",
  "isReturnDataForCustomer": true,
  "key": "001434249936",
  "createdAt": "2024-05-28 10:08:04.296+00"
}

Описание полей ответа:

Проверка игрока

HTTP
POST /api/v1/offers/check-game-data
Authorization: {{token}}

{
  "offerId": 1001,
  "gameUserId": "52357322414",
  "gameServerId": "1234"
}

Описание полей запроса:

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

JSON
{
  "status": "VALID",
  "gameUserLogin": "JJJ"
}

Описание полей успешного ответа:

Ответ при ошибке:

JSON
{
  "status": "INVALID"
}

Описание полей ответа с ошибкой:

Тестирование API

Тестовый товар

Для тестирования интеграции с API доступен специальный тестовый товар:

• ID товара: 999
• Название: Steam US
• Наименование: TEST OFFER GROUP
• Цена: 23.09 KZT (важно использовать точное значение)
• Возвращает ключ: Да

Пример запроса информации о тестовом товаре:

HTTP
POST /api/v1/offers/find-one
Authorization: {{token}}

{
  "offerId": 999
}

Пример создания тестового заказа:

HTTP
POST /api/v1/offers/create-order
Authorization: {{token}}

{
  "offerId": 999,
  "price": 23.09,
  "transactionId": "test_123456",
  "customer": {
    "email": "test@example.com",
    "gameUserId": "123456789"
  }
}

Особенности тестового товара:

• Всегда возвращает успешный ответ при правильных параметрах
• Генерирует тестовый ключ активации
• Создаёт заказ со статусом COMPLETED
• Проверка игрока всегда возвращает VALID для тестового товара
• Работает в тестовом режиме без реального списания средств

Примеры работы с балансом

Проверка баланса перед покупкой:

JAVASCRIPT
// 1. Проверяем текущий баланс
const balanceResponse = await fetch('/api/v1/balance', {
  headers: { 'Authorization': 'your-token-here' }
});
const { balance } = await balanceResponse.json();

// 2. Получаем информацию о товаре
const offerResponse = await fetch('/api/v1/offers/find-one', {
  method: 'POST',
  headers: {
    'Authorization': 'your-token-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ offerId: 1001 })
});
const { price } = await offerResponse.json();

// 3. Проверяем достаточность средств
if (balance >= price) {
  // Создаем заказ
  console.log('Sufficient balance, creating order...');
} else {
  console.log('Insufficient balance, need to top up');
}

Получение истории транзакций:

JAVASCRIPT
const transactionsResponse = await fetch('/api/v1/balance/transactions', {
  headers: { 'Authorization': 'your-token-here' }
});
const { transactions, total } = await transactionsResponse.json();

console.log(`Total transactions: ${total}`);
transactions.forEach(tx => {
  console.log(`${tx.createdAt}: ${tx.type} ${tx.amount} (Balance: ${tx.balanceAfter})`);
});

Рекомендации по использованию

💰 Работа с балансом

• Регулярно проверяйте баланс перед крупными покупками
• Ведите учет транзакций для сверки с вашей системой
• При недостатке средств уведомляйте пользователей о необходимости пополнения
• Используйте пагинацию при запросе истории транзакций

🔍 Перед созданием заказа

• Получите актуальную информацию о товаре
• Проверьте достаточность баланса для покупки
• Проверьте валидность игрока (в случае прямого пополнения)

📝 При создании заказа

• Используйте уникальный transactionId
• Указывайте актуальную цену
• Указывайте offerId как число, не как строку
• Заполняйте все необходимые поля для данного типа товара

✅ После создания заказа

• Сохраните orderId
• Проверяйте статус заказа
• При статусе COMPLETED получите ключ/товар

⚠️ При возникновении ошибок

• Проверьте токен
• Убедитесь в корректности данных и формате запроса
• Создайте новый заказ при необходимости

Поддержка

При возникновении вопросов обращайтесь в техническую поддержку:

• 📧 Email: support@gamesdrop.io
• 💬 Telegram: @gamesdrop_support

Рекомендации по обработке ошибок

🔍 Проверка перед запросом

• Валидация токена
• Проверка ID товара
• Актуальность цены
• Уникальность transaction_id
• Корректность формата данных (особенно offerId как число)

🛠 Обработка ответов

• Обработка всех кодов ошибок
• Логирование ошибок
• Механизм повторных попыток

📊 Работа с заказами

• Сохранение ID заказов
• Мониторинг статусов
• Актуализация данных

Telegram Stars

🌟 GamesDrop интегрировал поддержку Telegram Stars! Теперь вы можете отправлять Telegram Stars пользователям через те же стандартные API эндпоинты.

Доступные продукты Telegram Stars

Как работает ценообразование:

• A6-Gateway получает актуальный TON/USD курс от kernel currency API
• Цена рассчитывается на основе Fragment.com коэффициентов (100 Stars ≈ 0.3 TON)
• Цены обновляются в реальном времени при каждом запросе

Использование тех же эндпоинтов

1. Получение информации о Telegram Stars:

HTTP
POST /api/v1/offers/find-one
Authorization: {{token}}

{
  "offerId": "telegram_stars_100"
}

Response:

JSON
{
  "offerId": "telegram_stars_100",
  "productName": "Telegram Stars",
  "offerName": "100 Stars",
  "count": 1,
  "price": 0.77,
  "currency": "USD",
  "isReturnDataForCustomer": true
}

2. Создание заказа на Telegram Stars:

HTTP
POST /api/v1/offers/create-order
Authorization: {{token}}

{
  "offerId": "telegram_stars_100",
  "price": 0.77,
  "transactionId": "tg_stars_12345",
  "customer": {
    "email": "user@example.com",
    "gameUserId": "143594291"
  }
}

Response при успешной доставке:

JSON
{
  "orderId": 10228901,
  "count": 1,
  "price": 0.78,
  "currency": "USD",
  "offerId": "telegram_stars_100",
  "productName": "Telegram Stars",
  "offerName": "100 Stars",
  "status": "COMPLETED",
  "isReturnDataForCustomer": true,
  "fulfillmentData": {
    "telegram_user_id": 143594291,
    "stars_amount": 100,
    "transaction_id": "tg_tx_abc123",
    "delivery_status": "completed"
  },
  "createdAt": "2025-08-26T12:30:15.234Z"
}

Response при ошибке доставки:

JSON
{
  "orderId": 10228902,
  "status": "CANCELED",
  "message": "Failed to deliver Stars: user not found",
  "fulfillmentData": {
    "telegram_user_id": 123456789,
    "stars_amount": 100,
    "delivery_status": "failed",
    "error_message": "user not found"
  },
  "createdAt": "2025-08-26T12:30:15.234Z"
}

🔑 Важные особенности Telegram Stars

gameUserId требования:

• gameUserId должен быть числовой Telegram User ID для создания заказа
• Получить User ID можно двумя способами:
  1. 📞 Через @userinfobot в Telegram
  2. 🆕 Через наш API валидации (см. раздел ниже)
• Пример: "gameUserId": "143594291"
• ❌ НЕ username (@username) для создания заказа

Статусы доставки:

• COMPLETED - Stars успешно доставлены пользователю
• CANCELED - Не удалось доставить (неверный user ID, заблокирован бот, etc.)

Типичные ошибки доставки:

• "user not found" - неверный Telegram User ID
• "STARGIFT_INVALID" - пользователь не может получить Stars (restrictions)
• "bot was blocked by user" - пользователь заблокировал бота

🆔 Валидация Telegram пользователей

🎯 Новый endpoint для валидации username и получения User ID!

Если ваши пользователи знают только свой @username, используйте этот endpoint для получения User ID перед созданием заказа.

Endpoint валидации:

HTTP
POST https://gamesdrop.io/api/aggregator/a6/telegram/user-info
Authorization: {{token}}
Content-Type: application/json

{
  "username": "@igoryan34"
}

Response при успешной валидации:

JSON
{
  "valid": true,
  "username": "igoryan34",
  "userInfo": {
    "id": 143594291,
    "first_name": "Igor",
    "username": "igoryan34",
    "photo_url": "AQADAgADRKgxGzMTjwgABCAI..."
  },
  "message": "User account verified successfully"
}

Response при невозможности получить User ID:

JSON
{
  "valid": true,
  "username": "igoryan34",
  "userInfo": {
    "username": "igoryan34",
    "first_name": "igoryan34"
  },
  "message": "Username format is valid, but user details are not publicly available. Full verification requires user interaction with the bot."
}

Описание полей запроса:

Описание полей ответа:

⚠️ Важные особенности:

• Endpoint возвращает User ID только если пользователь взаимодействовал с ботом
• Если userInfo.id отсутствует, попросите пользователя написать боту @gamesdrop_api_bot
• Можно передавать как "@username", так и "username"
• Можно также передавать User ID для получения дополнительной информации

📱 Интеграция для разработчиков

Пример полного flow на JavaScript с валидацией username:

JAVASCRIPT
// 1. Валидировать username и получить User ID
const validateTelegramUser = async (username) => {
  const response = await fetch('https://gamesdrop.io/api/aggregator/a6/telegram/user-info', {
    method: 'POST',
    headers: {
      'Authorization': 'your-token-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ username })
  });

  const result = await response.json();

  if (result.valid && result.userInfo && result.userInfo.id) {
    return {
      userId: result.userInfo.id,
      firstName: result.userInfo.first_name,
      username: result.userInfo.username
    };
  } else {
    throw new Error('Unable to get User ID. Please ask user to message @gamesdrop_api_bot first.');
  }
};

// 2. Получить актуальную цену
const getStarsPrice = async (starsAmount) => {
  const response = await fetch('/api/v1/offers/find-one', {
    method: 'POST',
    headers: {
      'Authorization': 'your-token-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      offerId: `telegram_stars_${starsAmount}`
    })
  });
  return response.json();
};

// 3. Отправить Stars пользователю
const sendStarsByUsername = async (usernameOrId, starsAmount) => {
  // Сначала получаем User ID если передали username
  let userId;
  if (isNaN(usernameOrId)) {
    // Это username, нужно получить User ID
    const userInfo = await validateTelegramUser(usernameOrId);
    userId = userInfo.userId;
    console.log(`✅ Validated user: ${userInfo.firstName} (@${userInfo.username}) - ID: ${userId}`);
  } else {
    // Это уже User ID
    userId = parseInt(usernameOrId);
  }

  // Получаем цену
  const { price } = await getStarsPrice(starsAmount);

  // Создаем заказ
  const response = await fetch('/api/v1/offers/create-order', {
    method: 'POST',
    headers: {
      'Authorization': 'your-token-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      offerId: `telegram_stars_${starsAmount}`,
      price: price,
      transactionId: `stars_${Date.now()}`,
      customer: {
        email: "optional@example.com",
        gameUserId: userId.toString()
      }
    })
  });

  const result = await response.json();

  if (result.status === 'COMPLETED') {
    console.log(`✅ Successfully sent ${starsAmount} Stars to User ID ${userId}`);
    return result;
  } else {
    console.error(`❌ Failed to send Stars: ${result.message}`);
    throw new Error(result.message);
  }
};

// Использование:
// С username:
sendStarsByUsername('@igoryan34', 100)
  .then(order => console.log('Order created:', order.orderId))
  .catch(error => console.error('Delivery failed:', error));

// С User ID:
sendStarsByUsername('143594291', 100)
  .then(order => console.log('Order created:', order.orderId))
  .catch(error => console.error('Delivery failed:', error));

💼 B2B кейсы использования

1. Награды в играх:

JAVASCRIPT
// Наградить игрока за достижение
await sendStars(userTelegramId, 50);

2. Промо-кампании:

JAVASCRIPT
// Отправить Stars всем участникам конкурса
const winners = [143594291, 987654321, 456789123];
for (const userId of winners) {
  await sendStars(userId, 100);
}

3. Кэшбек программы:

JAVASCRIPT
// Вернуть часть покупки в виде Stars
const cashbackAmount = Math.floor(purchaseAmount * 0.05); // 5% кэшбек
const starsAmount = Math.min(cashbackAmount * 100, 1000); // конвертируем в Stars
await sendStars(userTelegramId, starsAmount);

⚡ Performance и лимиты

• Rate limiting: 30 запросов в секунду на Telegram API
• Minimum amount: 1 Star
• Maximum amount: 2500 Stars за одну транзакцию
• Retry logic: Автоматические повторы при временных ошибках
• Delivery time: Мгновенная доставка (< 3 секунды)

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

• Валидация Telegram User ID перед отправкой
• Проверка баланса GamesDrop перед созданием заказа
• Логирование всех операций для аудита
• Защита от дублированных транзакций через transactionId