Если вы развиваете интернет-магазин цифровых товаров — игровых ключей, подписок, подарочных карт — рано или поздно ручное пополнение стока становится тормозом роста. API цифровых товаров решает эту проблему: ваш магазин получает живой каталог, автоматически создаёт заказы и мгновенно доставляет коды покупателям без участия менеджера.
В этом руководстве разберём, как устроено API цифровых товаров, что нужно для подключения и как выглядит реальная интеграция на примере FoxReload.
Что такое API цифровых товаров и зачем оно нужно
API (Application Programming Interface) — это набор команд, которые ваш сайт отправляет поставщику, а поставщик отвечает данными или действием. В случае с цифровыми товарами это выглядит так: магазин запрашивает список доступных позиций, получает актуальные остатки и цены, принимает заказ от покупателя, передаёт его через API поставщику и получает в ответ готовый код.
Всё это происходит за секунды, без ручного труда.
Как работает API цифровых товаров: основные эндпоинты
Любой API для продажи цифровых кодов строится вокруг нескольких базовых операций. Разберём их последовательно — именно в таком порядке они используются при реальной интеграции.
Авторизация
Первый шаг — получение токена доступа. Поставщик выдаёт вам API-ключ (или пару ключей: публичный и секретный). При каждом запросе вы передаёте этот ключ в заголовке запроса, например:
Authorization: Bearer YOUR_API_KEY
Без валидного ключа API вернёт ошибку 401. Ключи нужно хранить в переменных окружения, а не в коде.
Получение каталога
Эндпоинт каталога возвращает список доступных товаров с ценами, остатками и метаданными. Обычно это GET-запрос:
GET /v1/catalog
В ответе — массив объектов с полями: идентификатор товара, название, номинал, валюта, количество в наличии, цена для партнёра.
Проверка баланса и резервирование
Перед созданием заказа разумно проверить баланс вашего счёта у поставщика. Некоторые API также поддерживают предварительное резервирование — чтобы товар не ушёл другому покупателю в момент оплаты.
Создание заказа
Это ключевой эндпоинт — POST-запрос с идентификатором товара и количеством:
POST /v1/orders
{ "product_id": "psn-500-rub", "quantity": 1 }
В ответ поставщик возвращает идентификатор заказа и статус. Если товар в наличии — статус сразу становится completed и в ответе присутствует сам код.
Получение кода по заказу
Если доставка не синхронная, код можно запросить отдельным запросом по ID заказа:
GET /v1/orders/{order_id}
Готовы подключить API цифровых товаров?
FoxReload предоставляет партнёрский API с доступом к тысячам позиций: gift cards, игровые коды, подписки. Документация, тестовая среда и поддержка включены.
FoxReload API: как подключиться пошагово
FoxReload — платформа для оптовых партнёров, продающих цифровые товары. Она предоставляет REST API с полной документацией и тестовой средой.
Регистрация партнёрского аккаунта
Перейдите на foxreload.com и подайте заявку на партнёрство. После верификации вы получите доступ в личный кабинет и API-ключи для тестовой и боевой среды.
Изучение документации и тестовая среда
В личном кабинете доступна полная документация по эндпоинтам. Тестовая среда (sandbox) позволяет проверить все сценарии без реальных списаний.
Интеграция каталога на сайте
Запросите каталог через GET /v1/catalog и загрузите товары в базу данных своего магазина. Настройте периодическое обновление цен и остатков — например, раз в 15 минут.
Обработка заказов
После успешной оплаты покупателем ваш бэкенд отправляет POST /v1/orders и получает код в ответе. Код передаётся покупателю — на email, в личный кабинет или сразу на экран.
Настройка вебхуков и мониторинга
Подключите вебхуки для асинхронных уведомлений об изменении статуса заказа. Настройте алерты на ошибки и мониторинг остатков по ключевым позициям.
Всегда разделяйте тестовую и боевую среды. Используйте sandbox-ключи для разработки и никогда не коммитьте реальные API-ключи в репозиторий. Храните их в переменных окружения или в защищённом хранилище секретов.
Сравнение способов продажи цифровых товаров
Не всем подходит прямая интеграция API. Вот как выглядят основные варианты:
| Критерий | Ручное пополнение | Маркетплейс | API интеграция |
|---|---|---|---|
| Скорость доставки кода | Часы / вручную | Мгновенно | Мгновенно |
| Контроль над магазином | Полный | Ограниченный | Полный |
| Автоматизация | Нет | Частичная | Полная |
| Комиссия платформы | Нет | 5–15% | Нет |
| Технические требования | Нет | Нет | Разработчик |
| Масштабирование | Сложно | Среднее | Легко |
| 🏆 Лучший выбор для роста | — | — | ✅ |
Типичные ошибки при интеграции API
Даже опытные разработчики допускают одни и те же ошибки при первой интеграции API цифровых товаров.
Синхронная обработка заказов без таймаута. Если ваш бэкенд ждёт ответа от API синхронно и не задаёт таймаут — при задержке на стороне поставщика запрос покупателя зависнет. Всегда устанавливайте таймаут (5–10 секунд) и обрабатывайте ошибки соединения.
Отсутствие идемпотентных ключей. Сеть ненадёжна: запрос может дойти, но ответ — нет. Без идемпотентного ключа повторный запрос создаст второй заказ. Большинство зрелых API поддерживают заголовок Idempotency-Key — используйте его при создании заказов.
Кэширование каталога слишком долго. Цены и остатки меняются. Если кэшировать каталог на сутки, вы будете продавать товары по устаревшим ценам или продавать то, чего нет. Оптимальный интервал обновления — 10–30 минут.
Отсутствие логирования запросов и ответов. При возникновении проблемы с конкретным заказом вы должны иметь возможность восстановить полный лог: что отправили, что получили, когда. Логируйте все запросы к API в отдельную таблицу или систему логов.
Никогда не показывайте покупателю код до подтверждения оплаты на вашей стороне. Порядок обязательный: оплата подтверждена → запрос к API → получение кода → показ покупателю. Иначе вы рискуете выдать код за неоплаченный заказ.
FAQ
Нужен ли разработчик для подключения API цифровых товаров?
Да, для прямой интеграции API нужен разработчик — или вы сами должны уметь работать с HTTP-запросами и бэкендом. Минимальный стек: умение делать REST-запросы, хранить данные в БД и обрабатывать вебхуки. Если разработчика нет, рассмотрите готовые плагины для WooCommerce или других CMS — некоторые поставщики их предоставляют.
Сколько стоит подключение к API FoxReload?
Само подключение к API обычно бесплатно для партнёров. Вы платите только за товары, которые заказываете через API, по оптовым ценам. Конкретные условия уточняйте при регистрации на foxreload.com — они зависят от объёмов и категорий товаров.
Как обрабатывать ситуацию, когда код оказался нерабочим?
В партнёрских договорах обычно предусмотрена процедура замены или возврата нерабочего кода. В интерфейсе или через API доступен эндпоинт для подачи рекламации по заказу. Важно фиксировать жалобы покупателей с деталями: ID заказа, код (замаскированный), описание ошибки активации.
Можно ли использовать API для автоматического пополнения стока, а не для прямых заказов?
Да, это распространённая схема. Вы заранее закупаете коды через API и храните их в своей базе данных. При покупке покупатель получает код из вашего стока. Минус — вы замораживаете деньги в остатках. Плюс — полная независимость от доступности API в момент продажи.
Какие товары доступны через API FoxReload?
FoxReload специализируется на широком ассортименте цифровых товаров: подарочные карты Steam, PlayStation, Xbox, Nintendo, пополнения мобильных игр, подписки на стриминговые сервисы, VPN-сервисы и многое другое. Актуальный каталог доступен через эндпоинт /v1/catalog после регистрации.