Автоматизация доставки подарочных карт с Python SDK FazerCards

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

Что потребуется

Перед написанием кода подготовьте:

Аккаунт FazerCards на любом тарифе или бесплатный 5-дневный Gold-триал — полный доступ к API без ввода карты
API-ключ из панели аккаунта
Python 3.9 или выше
Публично доступный URL для получения вебхуков (на время разработки подойдёт туннель)

Шаг 1: Установите пакет и проверьте подключение

Установите SDK из PyPI — пакет называется fazercards. После установки создайте экземпляр клиента с вашим API-ключом. SDK автоматически устанавливает заголовок X-Api-Key на каждый исходящий запрос.

Для первоначальной проверки вызовите эндпоинт баланса — GET /balance — и убедитесь, что он возвращает ваш текущий баланс в USD. Если пришло число, соединение с продакшн-API установлено. Sandbox-окружения нет: триал работает на той же продакшн-инфраструктуре, что и платные планы, поэтому первые тестовые заказы делайте небольшими и учитывайте их как реальные списания.

Шаг 2: Структура каталога

FazerCards разделяет каталог на три семейства продуктов, у каждого — собственное пространство URL:

Подарочные карты — GET /giftcards возвращает категории; GET /giftcards/cards?category_id=... — офферы с card_id, price_usd и stock
Пополнения — GET /topups для категорий; GET /topups/offers для офферов с offer_id и полями идентификации игрока
Игровые ключи — GET /gamekeys и GET /gamekeys/keys по той же двухэтапной схеме

SDK предоставляет метод для каждого из этих шести вызовов. Сохраняйте результаты в локальный кэш и обновляйте его по расписанию — одного раза в час вполне достаточно. Полный каталог и документация API содержат схему каждого объекта ответа. Если вы только начинаете работу с REST API FazerCards, руководство по интеграции API поможет разобраться с базовыми концепциями.

Шаг 3: Проверяйте остатки перед показом кнопки покупки

Поле stock в каждом оффере отражает доступность прямо сейчас, но локальный кэш быстро устаревает для популярных товаров. На практике работают два подхода:

При открытии страницы товара — не весь каталог, только один оффер.
Если stock равен нулю, немедленно помечайте товар недоступным и не допускайте покупателя до шага оплаты.

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

Шаг 4: Оформляйте заказы с idempotency key

К каждому запросу на создание заказа добавляйте заголовок Idempotency-Key. Генерируйте один UUID на покупку, сохраняйте его в записи о заказе покупателя до вызова API и используйте его при каждом повторе этой покупки. Если из-за тайм-аута возникнет повторный запрос, API вернёт исходный заказ вместо создания нового списания. Ключи хранятся семь дней. Методы заказа в SDK по умолчанию создают ключ автоматически, а он защищает только повторы внутри одного вызова; передавайте свой сохранённый ключ, чтобы был защищён и повтор после сбоя или перезапуска.

Эндпоинты заказов работают по единой схеме для всех типов продуктов:

POST /giftcards/order — требует category_id, card_id и quantity
POST /topups/order — требует category_id, offer_id и поля идентификации игрока
POST /gamekeys/order устроен так же; POST /steam-topup/order вместо этого принимает логин Steam, валюту и сумму — подробности в документации API

Ответ возвращает статус completed (коды подарочных карт уже лежат в поле cards заказа) или processing (доставка в процессе; дальше работает обработчик вебхуков — в SDK есть и помощник ожидания, который опрашивает заказ до финального статуса). Не забудьте обработчики для failed и refund — оба встречаются в продакшне.

Шаг 5: Верифицируйте и обрабатывайте вебхуки

Укажите URL вашего эндпоинта в панели FazerCards и направьте его на отдельный маршрут в приложении. Каждый входящий запрос содержит заголовок X-Webhook-Signature: sha256= и hex HMAC-SHA256 тела запроса, подписанного вашим секретом вебхука. SDK поставляется с хелпером для этой проверки. Отклоняйте любой запрос, не прошедший верификацию, до чтения тела.

По заказам API отправляет два типа событий: order.created и order.status_changed. Каждая полезная нагрузка содержит order_id, type, status и previous_status — кодов в теле вебхука нет. Когда status приходит как completed, сразу вызывайте GET /orders/:orderId и доставляйте коды. Если status равен failed или refund, заказ выполнить не удалось и оптовая сумма возвращается на баланс; сообщите покупателю и верните ему деньги или оформите новый заказ с новым ключом. Тикет в поддержку с order ID нужен, только если неудачный заказ не перешёл в refund или выданный код не активируется — подтверждённые случаи получают замену или возврат на баланс.

Недоставленные вебхуки повторяются через 1, 5 и 30 минут с одинаковым event_id. Сделайте обработчик идемпотентным: записывайте обработанные event_id и пропускайте дубликаты. Deep-dive по вебхукам покрывает граничные случаи повторных доставок, если ваша логика доставки сложная.

Шаг 6: Соберите всё в поток фулфилмента

Когда каталог, заказы и вебхуки настроены, полный цикл запроса выглядит так:

Покупатель выбирает товар; сервер проверяет остатки в обновлённом кэше.
Покупатель подтверждает оплату; сервер генерирует UUID idempotency key и сохраняет его.
Сервер вызывает эндпоинт заказа с ключом в заголовке Idempotency-Key.
Если ответ completed — возьмите коды из ответа и доставьте немедленно.
Если ответ processing — сохраните order_id и дайте обработчику вебхуков доставить коды асинхронно.
Если ответ failed или refund — пометьте заказ и уведомите покупателя; оптовая сумма возвращается на баланс, поэтому верните деньги покупателю или повторите заказ с новым ключом идемпотентности.

Храните API-ключ в переменной окружения, а не в коде. Выставляйте маршрут вебхуков на отдельном пути. Idempotency key храните в долговременном хранилище, которое переживёт перезапуск приложения.

Что вы получите в итоге

После этих шести шагов ваш Python-бэкенд будет уметь:

Кэшировать и обновлять полный каталог — подарочные карты, пополнения и игровые ключи
Безопасно размещать заказы при сетевых сбоях без риска двойного списания
Доставлять коды покупателям в течение секунд после завершения пайплайна
Верифицировать подлинность вебхуков и дедуплицировать повторные доставки

Следующие логичные расширения: интерфейс управления заказами на базе GET /orders/:orderId, алерт о низком балансе через GET /balance, обработка лимитов запросов на транспортном уровне. В кукбуке API есть готовые примеры для обоих сценариев.

Если ваш основной стек — Node.js, пакет fazercards для npm повторяет структуру Python SDK и подключается к тем же эндпоинтам — всё из этого руководства переносится напрямую в JavaScript или TypeScript.

Лучший способ проверить интеграцию — настоящие заказы на реальных данных. Бесплатный 5-дневный Gold-триал открывает полный API, весь каталог и мгновенную доставку — без карты и KYC. Начните с нескольких небольших реальных заказов и проверьте end-to-end доставку до выхода в продакшн.