الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt

Use this file to discover all available pages before exploring further.

نظرة عامة

يُرجع endpoint الكتالوج جميع بطاقات الهدايا والمنتجات الرقمية المتاحة مصنفةً حسب الفئات مثل بطاقات الألعاب وخدمات البث وغيرها. يُنصح بالتخزين المؤقت للبيانات لتقليل استدعاءات API، إذ نادراً ما تتغير قائمة المنتجات.
قم بتخزين بيانات الكتالوج مؤقتاً لمدة 24 ساعة على الأقل. نادراً ما يُضاف أو يُزال منتج.

مرجع API

GET /v3/gift-cards/catalog

التوثيق الكامل للـ endpoint

التحميل الأساسي للكتالوج

async function loadCatalog() {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/gift-cards/catalog",
    {
      headers: {
        "X-Access-Token": process.env.API_KEY,
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to load catalog: ${response.status}`);
  }

  const result = await response.json();
  return result.data;
}

// Usage
const catalog = await loadCatalog();
console.log(`Total categories: ${catalog.categories.length}`);
console.log(
  `Total products: ${catalog.categories.reduce(
    (sum, cat) => sum + cat.products.length,
    0
  )}`
);

بنية الاستجابة

{
  "success": true,
  "data": {
    "categories": [
      {
        "name": "Gaming Cards",
        "products": [
          {
            "id": "507f1f77bcf86cd799439011",
            "title": "PlayStation Network",
            "enabled": true,
            "region": "dz"
          },
          {
            "id": "507f1f77bcf86cd799439012",
            "title": "Google Play Gift Card",
            "enabled": true
          }
        ]
      },
      {
        "name": "Streaming Services",
        "products": [
          {
            "id": "507f1f77bcf86cd799439014",
            "title": "Netflix Gift Card",
            "enabled": true
          }
        ]
      }
    ]
  },
  "meta": {
    "totalCategories": 8,
    "totalProducts": 127
  }
}

التخزين المؤقت للكتالوج

احفظ الكتالوج في الذاكرة المؤقتة لتجنب طلبات API زائدة:
class CatalogCache {
  constructor(ttlMinutes = 10) {
    this.data = null;
    this.timestamp = 0;
    this.ttl = ttlMinutes * 60 * 1000;
  }

  async get() {
    const now = Date.now();

    // Return cached if still valid
    if (this.data && now - this.timestamp < this.ttl) {
      console.log("Returning cached catalog");
      return this.data;
    }

    // Fetch fresh data
    console.log("Fetching fresh catalog");
    const response = await fetch(
      "https://api.oneclickdz.com/v3/gift-cards/catalog",
      {
        headers: { "X-Access-Token": process.env.API_KEY },
      }
    );

    this.data = await response.json();
    this.timestamp = now;

    return this.data;
  }

  invalidate() {
    this.data = null;
    this.timestamp = 0;
  }
}

// Usage
const cache = new CatalogCache(10); // 24 hours TTL

// First call - fetches from API
const catalog1 = await cache.get();

// Second call within 24 hours - returns cached
const catalog2 = await cache.get();

// Force refresh
cache.invalidate();
const catalog3 = await cache.get(); // Fetches fresh

تصفية المنتجات المتاحة

عرض المنتجات الممكّنة فقط للعملاء:
function getEnabledProducts(catalog) {
  const enabled = [];

  for (const category of catalog.categories) {
    const enabledInCategory = category.products.filter((p) => p.enabled);

    if (enabledInCategory.length > 0) {
      enabled.push({
        categoryName: category.name,
        products: enabledInCategory,
      });
    }
  }

  return enabled;
}

// Usage
const catalog = await cache.get();
const enabledProducts = getEnabledProducts(catalog.data);
console.log("Enabled products:", JSON.stringify(enabledProducts, null, 2));

تصفية حسب المنطقة

تصفية المنتجات حسب المنطقة إذا كنت تستهدف أسواقاً محددة:
function filterByRegion(catalog, region = "dz") {
  return catalog.categories
    .map((category) => ({
      ...category,
      products: category.products.filter(
        (p) => p.enabled && (!p.region || p.region === region)
      ),
    }))
    .filter((cat) => cat.products.length > 0);
}

// Usage
const algerianProducts = filterByRegion(catalog.data, "dz");

أفضل الممارسات

معالجة الأخطاء بلطف

استخدم البيانات المخزنة مؤقتاً إذا كانت واجهة API غير متاحة مؤقتاً

التنظيم حسب الفئة

استخدم هيكل الفئات لتجربة مستخدم أفضل

الخطوات التالية

التحقق من المنتجات

الحصول على الأسعار الفورية ومستويات المخزون

تقديم الطلبات

تقديم طلبات بطاقات الهدايا

مرجع API

التوثيق الكامل للـ endpoint