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

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

GET /v3/gift-cards/checkProduct/{productId}

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

الفحص الأساسي للمنتج

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

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

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

// Usage
const productId = "507f1f77bcf86cd799439011";
const product = await checkProduct(productId);

console.log(`Product: ${product.productTitle}`);
console.log(`Available types: ${product.types.length}`);
product.types.forEach((type) => {
  console.log(`  - ${type.name}: ${type.price} DA (stock: ${type.quantity})`);
});

مثال على الاستجابة

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "productTitle": "PlayStation Store",
    "types": [
      {
        "_id": "type_10",
        "name": "PSN 10 USD",
        "price": 1450,
        "quantity": 25,
        "available": true
      },
      {
        "_id": "type_25",
        "name": "PSN 25 USD",
        "price": 3600,
        "quantity": 0,
        "available": false
      }
    ]
  }
}

الحصول على الأنواع المتاحة فقط

function getAvailableTypes(product) {
  return product.types.filter((type) => type.quantity > 0);
}

// Usage
const product = await checkProduct(productId);
const available = getAvailableTypes(product);

if (available.length === 0) {
  console.log("Product currently out of stock");
} else {
  console.log(`${available.length} denominations available`);
}

تطبيق هامش الربح

لا تعرض أسعار الجملة أبداً - طبّق دائماً هامشك الخاص قبل العرض للعملاء.
function applyMarkup(types, markupPercent = 5) {
  return types
    .filter((type) => type.quantity > 0)
    .map((type) => ({
      id: type.id,
      name: type.name,
      wholesalePrice: type.price, // Store but don't show
      customerPrice: Math.ceil(type.price * (1 + markupPercent / 100)),
      available: true,
    }));
}

// Usage
const product = await checkProduct(productId);
const customerPrices = applyMarkup(product.types, 5); // 5% markup

customerPrices.forEach((type) => {
  console.log(`${type.name}: ${type.customerPrice} DA`);
  // Don't log wholesalePrice in production!
});

التحقق من المخزون قبل الطلب

async function validateStock(productId, typeId, quantity) {
  const product = await checkProduct(productId);
  const type = product.types.find((t) => t.id === typeId);

  if (!type) {
    throw new Error("Invalid type ID");
  }

  if (type.quantity === 0) {
    throw new Error("Product out of stock");
  }

  if (type.quantity < quantity) {
    throw new Error(
      `Insufficient stock. Available: ${type.quantity}, Requested: ${quantity}`
    );
  }

  return {
    valid: true,
    type,
    totalCost: type.price * quantity,
  };
}

// Usage
try {
  const validation = await validateStock(productId, "type_001", 5);
  console.log(`Order valid. Total cost: ${validation.totalCost} DA`);
} catch (error) {
  console.error("Validation failed:", error.message);
}

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

التحقق قبل الطلب

تحقق دائماً من المخزون قبل تقديم الطلبات

إخفاء أسعار الجملة

لا تعرض أبداً قيم price الخام للعملاء

التخزين المؤقت

خزّن مؤقتاً لمدة 1-2 دقيقة خلال سير الدفع

معالجة نفاد المخزون

تعامل بشكل أنيق مع سيناريوهات الكمية الصفرية

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

async function checkProductSafely(productId) {
  try {
    return await checkProduct(productId);
  } catch (error) {
    if (error.message.includes("404")) {
      throw new Error("Product not found or disabled");
    }

    if (error.message.includes("401")) {
      throw new Error("Invalid API key");
    }

    console.error("Failed to check product:", error);
    throw new Error("Unable to load product details. Please try again.");
  }
}

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

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

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

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

جلب المنتجات المتاحة

مرجع API

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

نظرة عامة

العودة إلى نظرة عامة على التكامل

التسليم الآمن

تشفير وتسليم البطاقات