Интеграция магазина QuickPass с основным продуктом

Определения

Кредиты - внутренняя валюта основного продукта
Монеты QuickPass - внутренняя валюта QuickPass, которую пользователи тратят в магазине
Номинальный товар - товар с фиксированным количеством кредитов и ограниченным остатком

Что такое интеграция магазина

Интеграция магазина позволяет продавать кредиты основного продукта через магазин QuickPass. Пользователи могут тратить монеты QuickPass на получение кредитов в основном продукте.

Принцип работы

Пользователь выбирает товар в магазине QuickPass (например, "500 кредитов")
Платит монетами QuickPass за покупку
QuickPass отправляет запрос основному продукту на начисление кредитов
Основной продукт подтверждает начисление
Пользователь получает кредиты в основном продукте

Пример товара

"500 кредитов"

Пользователь видит товар в магазине QuickPass
Стоимость: 100 монет QuickPass
Доступно: 50 штук (остаток контролируется QuickPass)
При покупке получает 500 кредитов основного продукта
Остаток автоматически уменьшается: 49 штук

Что нужно от команды основного продукта

Минимальные требования

API для начисления кредитов - endpoint для получения запросов на начисление
Валидация пользователей - проверка существования пользователя в системе
Подтверждение операций - возврат статуса успешного/неуспешного начисления

Техническая реализация интеграции

API endpoint для начисления:

POST /api/v1/credits/increase
Content-Type: application/json
Authorization: Bearer {api_key}

{
  "user_id": "12345",
  "amount": 500,
  "currency": "credits",
  "order_id": "qp_order_789",
  "product_name": "500 кредитов",
  "source": "quickpass_store"
}

Ответ от основного продукта:

{
  "success": true,
  "transaction_id": "tx_456",
  "new_balance": 2500, // при необходимости
  "credited_amount": 500
}

При ошибке:

{
  "success": false,
  "error_code": "USER_NOT_FOUND",
  "error_message": "Пользователь не найден",
  "retry_allowed": false
}

Типы товаров основного продукта

Игровая валюта (номинальные товары)

Кредиты - основная валюта для ставок и покупок
- 100 кредитов (остаток: 200 шт.)
- 500 кредитов (остаток: 150 шт.)
- 1000 кредитов (остаток: 75 шт.)
Премиум валюта - для эксклюзивных возможностей
- 50 кристаллов (остаток: 30 шт.)
Бонусные баллы - накопительная система лояльности
- 200 бонусных баллов (остаток: 100 шт.)

Игровые преимущества

Фриспины/фрибеты - бесплатные игры или ставки
Множители - повышенные коэффициенты на определённое время
Кешбэк бонусы - возврат части проигранных средств

Статусы и привилегии

VIP статус - премиум возможности на период
Повышенные лимиты - увеличенные суммы ставок
Эксклюзивный доступ - к закрытым играм и турнирам

Флоу обработки покупки

Последовательность действий

Выбор товара в QuickPass
- Пользователь выбирает товар основного продукта
- Проверяется баланс монет QuickPass
Создание заказа
- QuickPass проверяет остаток товара (есть ли в наличии)
- Создаёт заказ со статусом "В обработке"
- Уменьшает остаток товара на 1 единицу
- Резервируются монеты QuickPass на счету пользователя
Запрос к основному продукту
- Отправка данных о покупке через API
- Ожидание подтверждения в течение 30 секунд
Обработка ответа
- При успехе: списание монет QuickPass, завершение заказа
- При ошибке: возврат монет QuickPass, отмена заказа
Уведомление пользователя
- О успешной покупке и зачислении кредитов
- Или об ошибке с возвратом средств

Обработка ошибок

Временные ошибки (сеть, таймаут):

Автоматические повторные попытки (3 раза с интервалом 10 сек)
При неудаче - возврат монет и уведомление пользователя

Критические ошибки (пользователь не найден):

Немедленная отмена заказа
Возврат монет QuickPass
Восстановление остатка товара (+1 единица)
Логирование для анализа

Частичные ошибки (недостаточно средств в основном продукте):

Возврат монет QuickPass
Восстановление остатка товара (+1 единица)
Уведомление с объяснением причины

Ошибки "Товар закончился":

Отображение "Нет в наличии" в магазине
Автоматическое скрытие товара при остатке = 0
Уведомление администраторов о необходимости пополнения

Настройка товаров в QuickPass

Создание товара основного продукта

Основная информация:
- Название: "1000 кредитов"
- Описание: "Пополни баланс в основном продукте"
- Цена: 200 монет QuickPass
Управление остатками:
- Начальный остаток: 100 штук
- Текущий остаток: 67 штук
- Минимальный остаток для алерта: 10 штук
- Автоскрытие при остатке: 0
Параметры интеграции:
- Тип ресурса: "external_currency"
- API endpoint: "/api/v1/credits/increase"
- Количество для зачисления: 1000
- Валюта: "credits"
Настройки доставки:
- Способ: "API вызов"
- Таймаут: 30 секунд
- Повторы: 3 попытки

Управление доступностью

Лимиты на пользователя: максимум X покупок в одни руки
Временные ограничения: доступно 24/7 или по расписанию
Привилегии: доступ к магазину для выполнивших задание основного продукта

Мониторинг и аналитика

Ключевые метрики

Количество успешных покупок кредитов основного продукта
Процент успешных транзакций
Среднее время обработки запроса
Популярность разных номиналов кредитов
Конверсия из монет QuickPass в кредиты основного продукта
Оборачиваемость товарных остатков
Частота пополнения остатков администраторами

Отслеживание проблем

Логи всех API запросов и ответов
Алерты при превышении времени ответа (>10 сек)
Уведомления при проценте ошибок >5%
Мониторинг баланса пользователей после операций
Алерты при критически низких остатках товаров (<10 штук)

Безопасность и валидация

Защита от мошенничества

Лимиты на частоту покупок (не более 1 в минуту)
Проверка IP адресов и устройств пользователей
Блокировка подозрительных аккаунтов
Двойная проверка крупных транзакций

Целостность данных

Идемпотентность операций (защита от дублирования)
Атомарность транзакций (либо всё, либо ничего)
Регулярная сверка балансов между системами
Резервные копии логов транзакций

Аналитика эффективности

Пользовательские метрики

Процент пользователей, покупающих монеты основного продукта
Средняя сумма покупки на пользователя
Частота покупок (раз в неделю/месяц)
Retention пользователей после первой покупки

Финансовые показатели

Общий объём проданных монет основного продукта
Средний чек в монетах QuickPass
Маржинальность операций
ROI от интеграции магазина

Техническая поддержка

Обработка проблем пользователей

Автоматический возврат средств при технических сбоях
Служба поддержки для решения спорных ситуаций
Возможность ручной корректировки балансов
История всех операций для расследования

Масштабирование

Rate limiting для защиты от перегрузок
Очереди для обработки пиковых нагрузок
Кеширование часто запрашиваемых данных
Горизонтальное масштабирование API

Административное управление остатками

Пополнение остатков

Ручное пополнение: администратор устанавливает новый остаток товара
Автопополнение: настройка автоматического пополнения при достижении минимума
Массовое управление: пополнение остатков для группы товаров одновременно
История изменений: полный аудит-лог всех операций с остатками

Контроль продаж

Лимиты продаж: ограничение количества продаж в день/неделю
Приоритетные пользователи: резерв товаров для VIP клиентов

Аналитика остатков

Прогноз расхода: когда закончится товар при текущих темпах продаж
Оптимальные остатки: рекомендации по размеру остатков