⚙️API для продажи Google Play Gift Cards: ключевые точки интеграции

Обзор

REST API FoxReload — основа любой автоматизированной операции с цифровыми товарами. Независимо от того, строите ли вы отдельный магазин, Telegram-бот или плагин для WooCommerce — все функции работают через один набор API-эндпоинтов. Это руководство — технический справочник по ключевым точкам интеграции для продажи Google Play Gift Cards.

Базовый URL: https://api.foxreload.com/api/v1

Все запросы — только через HTTPS.

Аутентификация

FoxReload использует Bearer-аутентификацию. API-ключ выдаётся при подтверждении оптового аккаунта.

Authorization: Bearer fr_live_xxxxxxxxxxxxxxxxxxxxxxxx

Типы ключей

Префикс	Среда	Назначение
fr_live_	Production	Реальные заказы, реальные деньги
fr_test_	Sandbox	Тестирование интеграции, без списаний

Всегда разрабатывайте с ключами fr_test_. Переключайтесь на fr_live_ только при выходе в продакшн.

Правила безопасности ключей

• Храните в переменных окружения или менеджере секретов
• Меняйте не реже одного раза в 90 дней
• Никогда не логируйте чистые API-ключи
• Создавайте отдельные ключи для каждой интеграции

Основные эндпоинты

GET /catalog

Возвращает доступные товары с актуальными ценами и остатками.

GET /api/v1/catalog?category=google-play&in_stock=true

Используйте для: построения витрины, синхронизации цен и остатков.

Частота запросов: каждые 15–30 минут для остатков; каждые 30–60 минут для цен.

GET /catalog/:id

Возвращает один товар по ID FoxReload.

GET /api/v1/catalog/gp-usd-25

Используйте для: проверки остатка перед оформлением заказа.

POST /orders

Размещает заказ и получает коды в ответе (для товаров в наличии с мгновенной доставкой).

POST /api/v1/orders
Content-Type: application/json

{
  "product_id": "gp-usd-25",
  "quantity": 1,
  "external_order_id": "myshop-ord-00492",
  "webhook_url": "https://myshop.com/webhooks/foxreload"
}

Ключевые поля:

Поле	Обязательно	Описание
product_id	Да	ID из каталога FoxReload
quantity	Да	Количество кодов (1–50)
external_order_id	Рекомендуется	Ваш внутренний ID для сверки
webhook_url	Необязательно	Переопределить URL вебхука для заказа

GET /orders/:id

Проверка статуса существующего заказа.

GET /api/v1/orders/fr-ord-98712

{
  "order_id": "fr-ord-98712",
  "external_order_id": "myshop-ord-00492",
  "status": "completed",
  "product_id": "gp-usd-25",
  "quantity": 1,
  "codes": [
    { "code": "ABCD-EFGH-IJKL-MNOP", "serial": "SN789012" }
  ],
  "created_at": "2026-05-27T14:30:00Z",
  "completed_at": "2026-05-27T14:30:01Z"
}

GET /balance

Возвращает текущий баланс оптового аккаунта.

GET /api/v1/balance

{
  "balance": 1250.00,
  "currency": "USD",
  "credit_limit": 0
}

Идемпотентность — критически важна для надёжности заказов

Если запрос на создание заказа завис — не делайте простой повтор. Вы можете разместить тот же заказ дважды и заплатить дважды. Используйте заголовок Idempotency-Key:

POST /api/v1/orders
Idempotency-Key: myshop-ord-00492-attempt-1

При повторной отправке того же Idempotency-Key в течение 24 часов API вернёт оригинальный ответ вместо создания дублирующего заказа.

import hashlib

def idempotency_key(order_id: str, attempt: int = 1) -> str:
    raw = f"{order_id}-attempt-{attempt}"
    return hashlib.sha256(raw.encode()).hexdigest()[:32]

Лимиты запросов

Эндпоинт	Лимит
GET /catalog	60 запросов/минуту
POST /orders	30 запросов/минуту
GET /orders/:id	120 запросов/минуту
GET /balance	30 запросов/минуту

При превышении лимитов — экспоненциальный откат:

import time, random

def request_with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        response = fn()
        if response.status_code == 429:
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
        else:
            return response
    raise Exception("Превышено максимальное количество попыток")

Справочник кодов ошибок

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Недостаточно средств на счёте для выполнения заказа.",
    "details": {
      "required": 22.75,
      "available": 10.00
    }
  }
}

Код	HTTP-статус	Решение
INVALID_API_KEY	401	Перевыпустить ключ в дашборде
INSUFFICIENT_BALANCE	402	Пополнить оптовый счёт
PRODUCT_NOT_FOUND	404	Повторно синхронизировать каталог
OUT_OF_STOCK	409	Проверить инвентарь, повторить позже
RATE_LIMIT_EXCEEDED	429	Откат и повтор
ORDER_DUPLICATE	409	Ключ идемпотентности уже использован
INTERNAL_ERROR	500	Повтор с откатом; при постоянстве — обратиться в поддержку

Вебхуки vs Поллинг

	Вебхуки	Поллинг
Задержка	< 1 секунды	До интервала поллинга
Нагрузка на сервер	Низкая	Высокая при масштабировании
Сложность	Средняя (проверка подписи)	Низкая
Надёжность	Требует публичного эндпоинта	Работает везде

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

• Используйте ключ fr_test_ при разработке
• Всегда передавайте external_order_id для сверки
• Ключи идемпотентности для всех POST /orders
• Корректная обработка 402 (баланс) и 409 (нет в наличии)
• Экспоненциальный откат при лимитах
• Верификация подписей вебхуков
• Мониторинг баланса с автоматическими оповещениями

---

Смотрите также

• Как подключить Google Play Gift Cards к магазину через API
• Как настроить вебхуки для доставки цифровых кодов
• Как реализовать мгновенную доставку Google Play Gift Cards

---

Получите API-ключ сегодня. Зарегистрируйте оптовый аккаунт FoxReload и начните интеграцию с полным доступом к sandbox.