API подарочных карт для интернет-магазинов: как это работает

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

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

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

Главный вывод: Правильно интегрированный API подарочных карт устраняет четыре главных узких места в перепродаже цифровых товаров: ручное управление запасами, задержку доставки кодов, ошибки сверки и нагрузку на поддержку из-за неполученных кодов. Работа по интеграции выполняется один раз; операционный выигрыш — постоянный.

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

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

Что такое API подарочных карт

API подарочных карт — это набор HTTP-эндпоинтов, которые соединяют ваш магазин с системой инвентаря, ценообразования и фулфилмента поставщика. Вместо того чтобы заранее покупать коды, хранить их в таблице и вручную отправлять покупателям по email, API берёт на себя всю цепочку:

1. Покупатель размещает заказ в вашем магазине
2. Ваш магазин вызывает эндпоинт создания заказа поставщика
3. Поставщик мгновенно возвращает код
4. Ваш магазин доставляет код покупателю

Процесс занимает секунды. Покупатель не знает разницы между предварительно закупленным кодом и кодом, доставленным через вызов API.

Ключевые функции API и их назначение

Как API вписывается в архитектуру вашего магазина

Браузер покупателя
      │
      ▼
Ваш интернет-магазин
  ├── Страница продукта: вызывает API каталога/наличия для отображения доступности
  ├── Оформление заказа: вызывает API наличия для проверки до оплаты
  ├── Оплата: обрабатывает платёж покупателя через ваш шлюз
  ├── Обработчик заказа: вызывает API создания заказа поставщика
  ├── Фулфилмент: доставляет код из ответа API покупателю
  └── Обработчик вебхуков: обновляет статус заказа из событий поставщика

API поставщика ──────────────────────────────────────────────────
  ├── GET /api/categories/
  ├── GET /api/products/?category_id_or_slug=...  (каталог + цены)
  ├── GET /api/products/{id_or_slug}              (доступность из листинга)
  ├── POST /api/orders/                           ({ items: [{ itemId, quantity }] })
  ├── GET /api/orders/{order_id}                  (опрос статуса; код в externalData)
  ├── GET /api/topups/crypto/chains/ (баланс пополняется криптой)
  └── GET /api/orders/?statuses=completed&limit=200&offset=0  (сверка)

Модели интеграции

Что проверить перед подключением к API поставщика

Распространённые ошибки интеграции

1. Не проверяют наличие перед принятием оплаты — приводит к неудачным заказам и трению при возвратах
2. Слишком агрессивное кэширование цен — цена, закэшированная в 9:00, может быть неверной в 15:00 для FX-чувствительных продуктов
3. Не реализуют опрос статусов — заказ создан, но код не получен; нужен фоновый воркер с GET /api/orders/{id}
4. Повторно создают заказ при сетевой ошибке — FoxReload не имеет idempotency-ключей; перед повтором проверяйте статус через GET /api/orders/{id}
5. Не обрабатывают частичное выполнение — для многоединичных заказов часть позиций может выполниться, часть нет; обрабатывайте каждый код независимо
6. Не мониторят баланс — нулевой баланс вызывает сбой всех заказов; установите оповещения
7. Используют один референс заказа для нескольких заказов покупателей — всегда используйте уникальные референсы для корректной сверки

Чек-лист интеграции

• Прочитайте полную документацию API перед написанием кода
• Получите API-ключ в Личном кабинете → API и протестируйте GET /api/access/me
• Реализуйте синхронизацию каталога продуктов (GET /api/categories/, GET /api/products/)
• Реализуйте создание заказа с обработкой ошибок (POST /api/orders/, тело: items с itemId)
• Реализуйте опрос GET /api/orders/{id} до status=="completed" в фоновом воркере
• Обрабатывайте все статусы: completed (externalData), failed (items[].error), cancelled, BalanceNotEnough
• Реализуйте доставку кода покупателю (email, страница заказа, Telegram-сообщение)
• Настройте мониторинг ошибок BalanceNotEnough с оповещениями
• Настройте пополнение баланса через GET /api/topups/crypto/chains/ + POST /api/topups/crypto/
• Протестируйте заказы с isMock:true для тестирования без реального фулфилмента
• Реализуйте экспорт сверки через GET /api/orders/ для финансовой службы
• Настройте логирование ошибок API и оповещения
• Нагрузочное тестирование интеграции при ожидаемом объёме заказов
• Запуск с активным мониторингом