Loading Product Catalog - OneClickDz Flexy API

Overview

The catalog endpoint returns all available gift cards and digital products organized by categories like Gaming Cards, Streaming Services, etc. Products should be cached to minimize API calls since the catalog changes infrequently.

Cache catalog data for at least 24 hours. Products are added/removed rarely.

API Reference

GET /v3/gift-cards/catalog

Complete endpoint documentation

Basic Catalog Loading

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
  )}`
);

import requests
import os

def load_catalog():
    response = requests.get(
        'https://api.oneclickdz.com/v3/gift-cards/catalog',
        headers={'X-Access-Token': os.getenv('API_KEY')}
    )

    response.raise_for_status()
    return response.json()['data']

# Usage
catalog = load_catalog()
total_products = sum(len(cat['products']) for cat in catalog['categories'])
print(f"Loaded {len(catalog['categories'])} categories with {total_products} products")

<?php

function loadCatalog($apiKey) {
    $ch = curl_init('https://api.oneclickdz.com/v3/gift-cards/catalog');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Access-Token: ' . $apiKey
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("Failed to load catalog: " . $httpCode);
    }

    $result = json_decode($response, true);
    return $result['data'];
}

// Usage
$catalog = loadCatalog(getenv('API_KEY'));
echo "Total categories: " . count($catalog['categories']) . "\n";
?>

curl https://api.oneclickdz.com/v3/gift-cards/catalog \
  -H "X-Access-Token: YOUR_API_KEY"

Response Structure

{
  "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
  }
}

Caching Implementation

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

from datetime import datetime, timedelta
import requests
import os

class CatalogCache:
    def __init__(self, ttl_minutes=10):
        self.data = None
        self.timestamp = None
        self.ttl = timedelta(minutes=ttl_minutes)

    def get(self):
        now = datetime.now()

        # Return cached if still valid
        if self.data and self.timestamp and (now - self.timestamp) < self.ttl:
            print('Returning cached catalog')
            return self.data

        # Fetch fresh data
        print('Fetching fresh catalog')
        response = requests.get(
            'https://api.oneclickdz.com/v3/gift-cards/catalog',
            headers={'X-Access-Token': os.getenv('API_KEY')}
        )
        response.raise_for_status()

        self.data = response.json()
        self.timestamp = now

        return self.data

    def invalidate(self):
        self.data = None
        self.timestamp = None

# Usage
cache = CatalogCache(ttl_minutes=10)

# First call - fetches from API
catalog1 = cache.get()

# Second call within 24 hours - returns cached
catalog2 = cache.get()

# Force refresh
cache.invalidate()
catalog3 = cache.get()

<?php

class CatalogCache {
    private $data = null;
    private $timestamp = 0;
    private $ttl;
    private $apiKey;

    public function __construct($apiKey, $ttlMinutes = 10) {
        $this->apiKey = $apiKey;
        $this->ttl = $ttlMinutes * 60;
    }

    public function get() {
        $now = time();

        // Return cached if still valid
        if ($this->data !== null && ($now - $this->timestamp) < $this->ttl) {
            error_log('Returning cached catalog');
            return $this->data;
        }

        // Fetch fresh data
        error_log('Fetching fresh catalog');
        $ch = curl_init('https://api.oneclickdz.com/v3/gift-cards/catalog');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'X-Access-Token: ' . $this->apiKey
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $this->data = json_decode($response, true);
        $this->timestamp = $now;

        return $this->data;
    }

    public function invalidate() {
        $this->data = null;
        $this->timestamp = 0;
    }
}

// Usage
$cache = new CatalogCache(getenv('API_KEY'), 10);

// First call - fetches from API
$catalog1 = $cache->get();

// Second call within 24 hours - returns cached
$catalog2 = $cache->get();

// Force refresh
$cache->invalidate();
$catalog3 = $cache->get();
?>

Filtering Products

Only show enabled products to customers:

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));

def get_enabled_products(catalog):
    enabled = []

    for category in catalog['categories']:
        enabled_in_category = [p for p in category['products'] if p['enabled']]

        if enabled_in_category:
            enabled.append({
                'categoryName': category['name'],
                'products': enabled_in_category
            })

    return enabled

# Usage
catalog = cache.get()
enabled_products = get_enabled_products(catalog['data'])
print(f"Found {len(enabled_products)} categories with enabled products")

<?php

function getEnabledProducts($catalog) {
    $enabled = [];

    foreach ($catalog['categories'] as $category) {
        $enabledInCategory = array_filter(
            $category['products'],
            function($p) { return $p['enabled']; }
        );

        if (!empty($enabledInCategory)) {
            $enabled[] = [
                'categoryName' => $category['name'],
                'products' => array_values($enabledInCategory)
            ];
        }
    }

    return $enabled;
}

// Usage
$catalog = $cache->get();
$enabledProducts = getEnabledProducts($catalog['data']);
echo "Enabled categories: " . count($enabledProducts) . "\n";
?>

Region Filtering

Filter products by region if targeting specific markets:

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");

Best Practices

Handle Errors Gracefully

Fall back to cached data if API is temporarily unavailable

Organize by Category

Use category structure for better user experience

Next Steps

Check Products

Get pricing and stock for selected products

Place Orders

Submit orders with validation

API Reference

Complete endpoint documentation

Overview

Back to integration overview

Track Status

Monitor order fulfillment

Secure Delivery

Encrypt and deliver cards

​Overview

​API Reference

GET /v3/gift-cards/catalog

​Basic Catalog Loading

​Response Structure

​Caching Implementation

​Filtering Products

​Region Filtering

​Best Practices

Handle Errors Gracefully

Organize by Category

​Next Steps

Check Products

Place Orders

API Reference

Overview

Track Status

Secure Delivery

Overview

API Reference

Basic Catalog Loading

Response Structure

Caching Implementation

Filtering Products

Region Filtering

Best Practices

Next Steps