تتبع الحالة والاستعلام

نظرة عامة

بعد تقديم طلب بطاقة هدية، استعلم عن endpoint /check-order لتتبع حالة الطلب واسترجاع تفاصيل البطاقة عند التنفيذ. تكتمل معظم الطلبات خلال 3-45 ثانية.

استعلم كل 5-10 ثوانٍ حتى يصل الطلب إلى حالة نهائية: FULFILLED أو PARTIALLY_FILLED أو REFUNDED.

مرجع API

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

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

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

HANDLING

الطلب قيد المعالجة. المدة المعتادة: 3-45 ثانية. استمر في الاستعلام كل 5-10 ثوانٍ.

FULFILLED

نجاح! تم تسليم البطاقة. تفاصيل البطاقة متاحة. سلّم للعميل فوراً.

PARTIALLY_FILLED

نجاح جزئي. تم تسليم بعض البطاقات وإلغاء الباقي. fulfilled_quantity < quantity. يُصدر استرداد جزئي تلقائياً.

REFUNDED

فشل. أُلغي الطلب وأُعيد المبلغ تلقائياً. أبلغ العميل بالفشل.

الاختبار في بيئة 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);
}

import requests
import os

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

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

# Usage
order_id = '6901616fe9e88196b4eb64b2'
order = check_order_status(order_id)

print(f"Status: {order['status']}")
if order['status'] == 'FULFILLED':
    print('Card data available:', order['cards'])

<?php

function checkOrderStatus($orderId) {
    $url = "https://api.oneclickdz.com/v3/gift-cards/check-order/{$orderId}";

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Access-Token: ' . getenv('API_KEY')
    ]);

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

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

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

// Usage
$orderId = '6901616fe9e88196b4eb64b2';
$order = checkOrderStatus($orderId);

echo "Status: {$order['status']}\n";
if ($order['status'] === 'FULFILLED') {
    echo "Card data available\n";
}
?>

curl https://api.oneclickdz.com/v3/gift-cards/check-order/6901616fe9e88196b4eb64b2 \
  -H "X-Access-Token: YOUR_API_KEY"

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

قيد المعالجة (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);
}

import time

def poll_order_until_complete(order_id, max_attempts=60):
    for attempt in range(1, max_attempts + 1):
        print(f"Checking order status ({attempt}/{max_attempts})...")

        order = check_order_status(order_id)

        # Order is complete
        if order['status'] in ['FULFILLED', 'PARTIALLY_FILLED', 'REFUNDED']:
            print(f"Order completed: {order['status']}")
            return order

        # Wait 5 seconds before next check
        if attempt < max_attempts:
            time.sleep(5)

    raise Exception('Order still processing after timeout')

# Usage
try:
    order = poll_order_until_complete('6901616fe9e88196b4eb64b3')

    if order['status'] == 'FULFILLED':
        print(f"Success! Cards: {len(order['cards'])}")
    elif order['status'] == 'PARTIALLY_FILLED':
        print(f"Partial delivery: {order['fulfilled_quantity']}/{order['quantity']}")
    else:
        print('Order failed and refunded')
except Exception as e:
    print(f"Error: {e}")

<?php

function pollOrderUntilComplete($orderId, $apiKey, $maxAttempts = 60) {
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        echo "Checking order status ({$attempt}/{$maxAttempts})...\n";

        $order = checkOrderStatus($orderId, $apiKey);

        // Order is complete
        $finalStates = ['FULFILLED', 'PARTIALLY_FILLED', 'REFUNDED'];
        if (in_array($order['status'], $finalStates)) {
            echo "Order completed: {$order['status']}\n";
            return $order;
        }

        // Wait 5 seconds before next check
        if ($attempt < $maxAttempts) {
            sleep(5);
        }
    }

    throw new Exception('Order still processing after timeout');
}

// Usage
try {
    $order = pollOrderUntilComplete('6901616fe9e88196b4eb64b3', getenv('API_KEY'));

    if ($order['status'] === 'FULFILLED') {
        echo "Success! Cards: " . count($order['cards']) . "\n";
    } elseif ($order['status'] === 'PARTIALLY_FILLED') {
        echo "Partial delivery: {$order['fulfilled_quantity']}/{$order['quantity']}\n";
    } else {
        echo "Order failed and refunded\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

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

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

def handle_order_result(order):
    if order['status'] == 'FULFILLED':
        print(f"✅ Success: {order['fulfilled_quantity']} cards delivered")
        print(f"Cost: {order['fulfilled_amount']} DA")

        # Process each card
        for i, card in enumerate(order['cards']):
            print(f"Card {i + 1}: {card['value']}")
            # Encrypt and deliver to customer

    elif order['status'] == 'PARTIALLY_FILLED':
        print(f"⚠️ Partial: {order['fulfilled_quantity']}/{order['quantity']} cards")
        print(f"Charged: {order['fulfilled_amount']} DA")

        refund = (order['quantity'] - order['fulfilled_quantity']) * order['price_per_card']
        print(f"Refunded: {refund} DA")

        # Deliver available cards
        for card in order['cards']:
            print(f"Delivered: {card['value']}")

    elif order['status'] == 'REFUNDED':
        print('❌ Order failed - full refund issued')

<?php

function handleOrderResult($order) {
    switch ($order['status']) {
        case 'FULFILLED':
            echo "✅ Success: {$order['fulfilled_quantity']} cards delivered\n";
            echo "Cost: {$order['fulfilled_amount']} DA\n";

            // Process each card
            foreach ($order['cards'] as $index => $card) {
                echo "Card " . ($index + 1) . ": {$card['value']}\n";
                // Encrypt and deliver to customer
            }
            break;

        case 'PARTIALLY_FILLED':
            echo "⚠️ Partial: {$order['fulfilled_quantity']}/{$order['quantity']} cards\n";
            echo "Charged: {$order['fulfilled_amount']} DA\n";

            $refund = ($order['quantity'] - $order['fulfilled_quantity']) * $order['price_per_card'];
            echo "Refunded: {$refund} DA\n";

            // Deliver available cards
            foreach ($order['cards'] as $card) {
                echo "Delivered: {$card['value']}\n";
            }
            break;

        case 'REFUNDED':
            echo "❌ Order failed - full refund issued\n";
            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

​نظرة عامة

​مرجع API

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

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

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

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

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

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

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

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

​منفَّذ (FULFILLED)

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

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

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

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

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

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

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

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

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

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

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

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

اختبر أولاً

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

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

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

مرجع API

نظرة عامة

مرجع API

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

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

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

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

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

منفَّذ (FULFILLED)

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

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

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

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

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

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