Как подключить каталог цифровых товаров к маркетплейсу

Краткий ответ

Подключение цифровых товаров к маркетплейсу означает интеграцию API поставщика в существующую инфраструктуру маркетплейса для добавления подарочных карт, игровых пополнений и аналогичных продуктов как новой категории. Интеграция состоит из трёх фаз: импорт каталога (получение продуктов от поставщика и создание листингов), флоу заказа (вызов API поставщика при покупке) и управление стоком (синхронизация листингов с доступностью поставщика). Техническая работа — разовая сборка; текущие операции автоматизированы.

Определение: Подключение каталога цифровых товаров к маркетплейсу означает использование API оптового поставщика для заполнения новой категории продуктов, автоматического фулфилмента заказов и поддержания актуального стока и ценообразования — без управления физическим инвентарём.

Главный вывод: Цифровые товары — наиболее удобная для бэкенд-интеграции категория при расширении маркетплейса. Нет склада, нет логистики, нет процесса возвратов. Вся цепочка фулфилмента: API-вызов → код в ответе. Сложность — в управлении каталогом (точность региона, именование, ценообразование) и надёжности флоу заказа, не в физических операциях.

Для кого это руководство

• Операторы маркетплейсов, добавляющие цифровые товары как новую категорию
• Разработчики, интегрирующие API поставщика цифровых товаров в существующую платформу
• Продакт-менеджеры, определяющие требования к интеграции цифровых товаров

Обзор архитектуры интеграции

Маркетплейс                    API поставщика
    │                               │
    ├─ Фаза 1: Импорт каталога ─────▶ GET /api/categories/
    │  Получить дерево категорий      GET /api/products/?category_id_or_slug=...
    │  Создать листинги               (ежедневно или при изменении)
    │                               │
    ├─ Фаза 2: Синхронизация стока ──▶ GET /api/products/{id_or_slug}
    │  Проверка перед показом          Доступность отражена в листинге товара
    │  (реальное время на странице)    (отдельного эндпоинта стока нет)
    │                               │
    ├─ Фаза 3: Флоу заказа ──────────▶ POST /api/orders/
    │  Покупатель завершает оплату     { "items": [{ "itemId": "product_01k...",
    │  Маркетплейс списывает платёж                 "quantity": 1 }] }
    │                               │
    │  Опрос статуса ────────────────▶ GET /api/orders/{order_id}
    │                          ◀──────┤ status=="completed" → items[].externalData
    │  Доставить код покупателю        │
    │                               │
    └─ Фаза 4: Сверка ───────────────▶ GET /api/orders/?statuses=completed&limit=200&offset=0
       Ежедневный финансовый экспорт  Пагинация для получения всех заказов

Фаза 1: Импорт каталога

Что возвращает API

Типичный эндпоинт каталога поставщика возвращает:

{
  "items": [
    {
      "id": "product_01k...",
      "name": "Steam Gift Card $20",
      "category": {"slug": "steam"},
      "price": {"amount": "18.40", "currency": "USD"}
    }
  ]
}

Маппинг на листинги маркетплейса

Правила:

• Один листинг маркетплейса на продукт поставщика — без объединения
• Всегда включать регион в название продукта
• Хранить itemId (id продукта) в базе данных для использования в поле items[].itemId при создании заказа

Расписание обновления каталога

Фаза 2: Управление стоком

Показывать покупателям только товары в наличии. Проверять доступность в двух точках:

1. Загрузка страницы листинга — запросить GET /api/products/{id_or_slug} для отображения «В наличии» или «Временно недоступно»; доступность отражена в поле товара (отдельного эндпоинта стока нет)
2. Начало оформления заказа — снова проверить; блокировать оформление при недоступности с момента загрузки страницы

GET /api/products/steam-20-usd
→ { "id": "product_01k...", "name": "Steam Gift Card $20", "available": true, ... }

Кэшировать ответы 5–15 минут (не дольше) для снижения нагрузки на API при сохранении актуальности.

Фаза 3: Флоу заказа

Когда покупатель завершает оформление:

1. Маркетплейс подтверждает платёж (покупатель списан)
2. Вызвать POST /api/orders/ с { "items": [{ "itemId": "product_01k...", "quantity": 1 }] }
3. Опрашивать GET /api/orders/{order_id} до status=="completed" → items[].externalData содержит коды
4. Сохранить order_id и код в своей базе данных
5. Доставить код покупателю (push-уведомление, email или страница истории заказов)
6. Отметить заказ как выполненный

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

Фаза 4: Сверка

Ежедневно получать историю заказов из API поставщика для финансовой сверки:

GET /api/orders/?statuses=completed&limit=200&offset=0
→ список заказов с id, status, items, временными метками (пагинация через offset)

Сопоставлять с записями транзакций маркетплейса. Расхождения требуют расследования.

Стратегия ценообразования для цифровых товаров маркетплейса

Устанавливать розничную цену выше оптовой + комиссия маркетплейса + комиссия платежа + целевая маржа:

Розничная цена = Оптовая ÷ (1 − комиссия_маркетплейса% − комиссия_платежа% − целевая_маржа%)

Пример (комиссия маркетплейса 10%, оплата картой 2,5%, целевая маржа 5%):

Розничная = $18,40 ÷ (1 − 0,10 − 0,025 − 0,05)
Розничная = $18,40 ÷ 0,825
Розничная = $22,30

Проверьте, что эта розничная цена конкурентоспособна. Если нет — либо договоритесь о лучших оптовых ценах, либо оцените, жизнеспособен ли этот канал для данного продукта.

Рекомендации по размеру каталога

Начать узко; расширять после валидации интеграции:

Запуск с 200 SKU до валидации флоу фулфилмента создаёт сложность отладки. Начать узко; масштабировать после доказательства пайплайна.

Технический чек-лист

Каталог:

• Учётные данные API поставщика настроены в production
• Задание импорта каталога запланировано (минимум ежедневно)
• Каждый SKU поставщика сопоставлен 1:1 с листингом маркетплейса
• Регион включён в название продукта для всех региональных товаров
• Розничная цена рассчитана с формулой маржи для каждого продукта

Сток:

• Проверка стока реализована при загрузке страницы продукта
• Проверка стока реализована при начале оформления заказа
• TTL кэша установлен 5–15 минут
• Товары не в наличии скрыты или отмечены как недоступные

Заказы:

• Вызов создания заказа триггерится на подтверждение платежа (не на инициацию)
• ID заказа поставщика хранится в вашей базе заказов
• Код доставлен покупателю при завершении заказа
• Состояния ошибок обработаны: таймаут, сбой, нет в наличии
• Оповещение настроено для сбоев заказов выше порога

Финансы:

• Ежедневная сверка с API заказов поставщика
• Оповещение о расхождениях настроено
• Оптовая стоимость записывается на каждый заказ для отчётности по марже
• Ошибка BalanceNotEnough обрабатывается: пополнение через POST /api/topups/crypto/