⚙️Как импортировать подарочные карты в каталог цифровых товаров

Зачем нужен программный импорт каталога

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

FoxReload предоставляет API каталога с полными данными по каждому SKU: Google Play Gift Cards, Apple Gift Cards, Steam Wallet, PSN, Xbox и игровые пополнения. В этом руководстве — как получить эти данные и загрузить их в собственную базу данных.

Описание эндпоинта каталога

GET /api/v1/catalog
Authorization: Bearer YOUR_API_KEY

Необязательные параметры:

Параметр	Значения	Описание
category	google-play, apple, steam, psn, xbox	Фильтр по бренду
currency	USD, EUR, GBP, TRY, INR…	Фильтр по валюте номинала
region	US, EU, TR, IN…	Фильтр по региону карты
in_stock	true	Только SKU с доступным остатком

Структура ответа каталога

{
  "updated_at": "2026-05-27T10:00:00Z",
  "products": [
    {
      "id": "gp-usd-10",
      "sku": "GP-US-10USD",
      "name": "Google Play Gift Card $10 (US)",
      "category": "google-play",
      "brand": "Google",
      "face_value": 10,
      "currency": "USD",
      "region": "US",
      "wholesale_price": 9.10,
      "stock": 450,
      "image_url": "https://cdn.foxreload.com/products/gp-usd-10.png",
      "description": "Активируется в Google Play Store в регионе US.",
      "delivery_type": "instant",
      "tags": ["google-play", "us", "usd"]
    }
  ],
  "total": 87
}

Шаг 1 — Спроектируйте локальную схему

Перед импортом соотнесите поля FoxReload с колонками вашей базы данных.

CREATE TABLE digital_products (
    id            VARCHAR(64) PRIMARY KEY,   -- product id из FoxReload
    sku           VARCHAR(64),
    name          VARCHAR(255),
    category      VARCHAR(64),
    face_value    DECIMAL(10,2),
    currency      CHAR(3),
    region        VARCHAR(10),
    cost_price    DECIMAL(10,2),             -- wholesale_price из API
    retail_price  DECIMAL(10,2),             -- ваша наценка
    stock         INT,
    image_url     TEXT,
    description   TEXT,
    active        BOOLEAN DEFAULT TRUE,
    synced_at     TIMESTAMP
);

Шаг 2 — Первоначальный массовый импорт

Выполните один раз, чтобы заполнить каталог с нуля.

import requests, os, psycopg2
from datetime import datetime

API_KEY = os.environ["FOXRELOAD_API_KEY"]
BASE_URL = "https://api.foxreload.com/api/v1"
MARGIN = 1.15  # наценка 15%

headers = {"Authorization": f"Bearer {API_KEY}"}

def fetch_all_products():
    r = requests.get(f"{BASE_URL}/catalog", headers=headers,
                     params={"in_stock": "true"})
    r.raise_for_status()
    return r.json()["products"]

def compute_retail(wholesale):
    return round(wholesale * MARGIN, 2)

def import_products(conn, products):
    cur = conn.cursor()
    for p in products:
        cur.execute("""
            INSERT INTO digital_products
              (id, sku, name, category, face_value, currency, region,
               cost_price, retail_price, stock, image_url, description, synced_at)
            VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s)
            ON CONFLICT (id) DO UPDATE SET
              cost_price=EXCLUDED.cost_price,
              retail_price=EXCLUDED.retail_price,
              stock=EXCLUDED.stock,
              synced_at=EXCLUDED.synced_at
        """, (
            p["id"], p["sku"], p["name"], p["category"],
            p["face_value"], p["currency"], p["region"],
            p["wholesale_price"], compute_retail(p["wholesale_price"]),
            p["stock"], p["image_url"], p["description"],
            datetime.utcnow()
        ))
    conn.commit()

conn = psycopg2.connect(os.environ["DATABASE_URL"])
products = fetch_all_products()
import_products(conn, products)
print(f"Импортировано {len(products)} товаров.")

Шаг 3 — Настройте инкрементальную синхронизацию

После первоначального импорта запускайте лёгкий sync-job каждые 15 минут для обновления остатков и цен.

# cron: */15 * * * * python sync_catalog.py
def sync_catalog():
    products = fetch_all_products()
    import_products(conn, products)
    # Деактивировать товары, которых больше нет у поставщика
    supplier_ids = {p["id"] for p in products}
    cur = conn.cursor()
    cur.execute(
        "UPDATE digital_products SET active=FALSE WHERE id != ALL(%s)",
        (list(supplier_ids),)
    )
    conn.commit()

Шаг 4 — Дополните каталог собственными данными

API FoxReload даёт базовые данные. Добавьте поверх:

• SEO-слаги — URL-friendly slugs из name
• Переводы — названия товаров на нескольких языках
• Дерево категорий — группировка по бренду и номиналу
• Рекламные флаги — выделите высокомаржинальные или популярные карты

Шаг 5 — Отобразите каталог в магазине

# Flask пример
@app.route("/shop/google-play")
def google_play_shop():
    cur.execute("""
        SELECT id, name, face_value, currency, retail_price, stock, image_url
        FROM digital_products
        WHERE category='google-play' AND active=TRUE AND stock > 0
        ORDER BY face_value ASC
    """)
    products = cur.fetchall()
    return render_template("shop.html", products=products)

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

• Импорт товаров без остатка — фильтруйте stock > 0 перед показом
• Жёстко заданные цены — синхронизируйте цены каждый час, оптовые цены меняются
• Игнорирование поля region — продажа турецкой карты российскому покупателю приведёт к ошибке активации
• Отсутствие пагинации — если каталог вырастет более 100 позиций, реализуйте offset/limit

Что делать дальше

После импорта и синхронизации каталога переходите к:

• Настройке размещения заказов при покупке
• Настройке мгновенной доставки кодов через вебхуки
• Автоматизации обновления цен при изменении оптовых закупочных цен

---

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

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

---

Готовы заполнить магазин? Получите полный каталог FoxReload через API и запустите магазин цифровых товаров за несколько часов.