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

​
نظرة عامة

بعد تقديم طلب بطاقة هدية، استعلم عن endpoint /check-order لتتبع حالة الطلب واسترجاع تفاصيل البطاقة عند التنفيذ. تكتمل معظم الطلبات خلال 3-45 ثانية.
استعلم كل 5-10 ثوانٍ حتى يصل الطلب إلى حالة نهائية: FULFILLED أو PARTIALLY_FILLED أو REFUNDED.

​
مرجع API

GET /v3/gift-cards/check-order/{orderId}

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

​
قيم حالة الطلب

الطلب قيد المعالجة. المدة المعتادة: 3-45 ثانية. استمر في الاستعلام كل 5-10 ثوانٍ.
نجاح! تم تسليم البطاقة. تفاصيل البطاقة متاحة. سلّم للعميل فوراً.
نجاح جزئي. تم تسليم بعض البطاقات وإلغاء الباقي. fulfilled_quantity < quantity. يُصدر استرداد جزئي تلقائياً.
فشل. أُلغي الطلب وأُعيد المبلغ تلقائياً. أبلغ العميل بالفشل.

​
الاختبار في بيئة Sandbox

استخدم وضع Sandbox للاختبار دون إنفاق رصيد حقيقي:

اختبار طلب فاشل

استخدم TEST_REFUND كـ type ID ← يحاكي طلباً فاشلاً (حالة REFUNDED)

اختبار نجاح جزئي

استخدم TEST_PARTIAL كـ type ID ← يحاكي تسليم 50% (حالة PARTIALLY_FILLED)
Sandbox Example
// Test different scenarios without real charges
const testScenarios = [
  {
    productId: "507f1f77bcf86cd799439011",
    typeId: "TEST_REFUND", // Will fail and refund
    quantity: 2,
  },
  {
    productId: "507f1f77bcf86cd799439011",
    typeId: "TEST_PARTIAL", // Will deliver 50% of cards
    quantity: 4,
  },
];

// Place test order
const order = await placeOrder(
  testScenarios[0].productId,
  testScenarios[0].typeId,
  testScenarios[0].quantity
);

// Poll for results
const result = await pollOrderUntilComplete(order.orderId);
console.log("Test result:", result.status);

​
فحص الحالة الأساسي

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

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

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

// Usage
const orderId = "6901616fe9e88196b4eb64b2";
const order = await checkOrderStatus(orderId);

console.log(`Status: ${order.status}`);
if (order.status === 'FULFILLED') {
  console.log('Card data available:', order.cards);
}

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

​
قيد المعالجة (HANDLING)

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b3",
    "status": "HANDLING",
    "quantity": 2,
    "product": "507f1f77bcf86cd799439011",
    "type": "type_001",
    "time": "2025-10-29T01:00:00.000Z"
  }
}

​
منفَّذ (FULFILLED)

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b3",
    "status": "FULFILLED",
    "quantity": 2,
    "fulfilled_quantity": 2,
    "fulfilled_amount": 980,
    "price_per_card": 490,
    "cards": [
      {
        "value": "XXXX-XXXX-XXXX-XXXX",
        "serial": "123456789"
      },
      {
        "value": "YYYY-YYYY-YYYY-YYYY",
        "serial": "987654321"
      }
    ],
    "time": "2025-10-29T01:00:00.000Z"
  }
}

​
مُنفَّذ جزئياً (PARTIALLY_FILLED)

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b3",
    "status": "PARTIALLY_FILLED",
    "quantity": 5,
    "fulfilled_quantity": 3,
    "fulfilled_amount": 1470,
    "price_per_card": 490,
    "cards": [
      { "value": "AAAA-AAAA-AAAA-AAAA", "serial": "111111111" },
      { "value": "BBBB-BBBB-BBBB-BBBB", "serial": "222222222" },
      { "value": "CCCC-CCCC-CCCC-CCCC", "serial": "333333333" }
    ],
    "time": "2025-10-29T01:00:00.000Z"
  }
}

​
حلقة الاستعلام الأساسية

async function pollOrderUntilComplete(orderId, maxAttempts = 60) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    console.log(`Checking order status (${attempt}/${maxAttempts})...`);

    const order = await checkOrderStatus(orderId);

    // Order is complete
    if (["FULFILLED", "PARTIALLY_FILLED", "REFUNDED"].includes(order.status)) {
      console.log(`Order completed: ${order.status}`);
      return order;
    }

    // Wait 5 seconds before next check
    if (attempt < maxAttempts) {
      await new Promise((resolve) => setTimeout(resolve, 5000));
    }
  }

  throw new Error("Order still processing after timeout");
}

// Usage
try {
  const order = await pollOrderUntilComplete("6901616fe9e88196b4eb64b3");

  if (order.status === "FULFILLED") {
    console.log("Success! Cards:", order.cards);
  } else if (order.status === "PARTIALLY_FILLED") {
    console.log(
      `Partial delivery: ${order.fulfilled_quantity}/${order.quantity}`
    );
  } else {
    console.log("Order failed and refunded");
  }
} catch (error) {
  console.error("Error:", error.message);
}

​
معالجة الحالات النهائية

function handleOrderResult(order) {
  switch (order.status) {
    case "FULFILLED":
      console.log(`✅ Success: ${order.fulfilled_quantity} cards delivered`);
      console.log(`Cost: ${order.fulfilled_amount} DA`);

      // Process each card
      order.cards.forEach((card, index) => {
        console.log(`Card ${index + 1}: ${card.value}`);
        // Encrypt and deliver to customer
      });
      break;

    case "PARTIALLY_FILLED":
      console.log(
        `⚠️ Partial: ${order.fulfilled_quantity}/${order.quantity} cards`
      );
      console.log(`Charged: ${order.fulfilled_amount} DA`);

      const refund =
        (order.quantity - order.fulfilled_quantity) * order.price_per_card;
      console.log(`Refunded: ${refund} DA`);

      // Deliver available cards
      order.cards.forEach((card) => {
        console.log(`Delivered: ${card.value}`);
      });
      break;

    case "REFUNDED":
      console.log("❌ Order failed - full refund issued");
      break;
  }
}

​
مثال على الاستعلام الكامل

async function processOrder(productId, typeId, quantity) {
  try {
    // 1. Place order
    console.log("Placing order...");
    const order = await placeOrder(productId, typeId, quantity);
    console.log(`Order placed: ${order.orderId}`);

    // 2. Poll for completion
    console.log("Waiting for fulfillment...");
    const result = await pollOrderUntilComplete(order.orderId);

    // 3. Handle result
    handleOrderResult(result);

    return result;
  } catch (error) {
    console.error("Order processing failed:", error.message);
    throw error;
  }
}

// Usage
await processOrder("507f1f77bcf86cd799439011", "type_001", 2);

الاستعلام كل 5-10 ثوانٍ

توازن بين الاستجابة وعدد طلبات API

معالجة PARTIALLY_FILLED بشكل صحيح

قدّم البطاقات المتاحة وأبلغ العميل بالتسليم الجزئي

تحديد حد أقصى للوقت

أوقف الاستعلام بأمان بعد 5 دقائق وأبلغ العميل بالانتظار

تحديث قاعدة البيانات

سجّل تغييرات الحالة وبيانات البطاقة عند كل تحديث

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

استعلم كل 5 ثوانٍ

وازن بين الاستجابة وحمل API

حدّد مهلة زمنية

أوقف الاستعلام بعد 5 دقائق (60 محاولة)

تعامل مع جميع الحالات

اعالج FULFILLED وPARTIALLY_FILLED وREFUNDED

اختبر أولاً

استخدم وضع Sandbox مع TEST_REFUND وTEST_PARTIAL

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

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

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

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

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

مرجع API

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