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

​
نظرة عامة

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

​
مرجع API

GET /v3/internet/check-id/{id}

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

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

الطلب قيد المعالجة مع المشغل. المدة المعتادة: 3-45 ثانية. استمر في الاستعلام كل 5-10 ثوانٍ.
نجاح! تم تسليم البطاقة. card_code وnum_trans وdate_traitement متاحة. سلّم للعميل فوراً.
مجدول لاحقاً. سيُعالَج الطلب خلال 12-48 ساعة. ليس فشلاً - جدوّل إعادة التحقق وأبلغ العميل.
فشل. أُلغي الطلب وأُعيد المبلغ تلقائياً. أبلغ العميل بالفشل.

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

async function checkTopupStatus(topupId) {
  const response = await fetch(
    `https://api.oneclickdz.com/v3/internet/check-id/${topupId}`,
    {
      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 topupId = "6901616fe9e88196b4eb64b2";
const order = await checkTopupStatus(topupId);

console.log(`Status: ${order.status}`);
console.log(`Type: ${order.type}`);

if (order.card_code) {
  console.log(`Card Code: ${order.card_code}`);
  console.log(`Transaction: ${order.num_trans}`);
}

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

​
قيد المعالجة

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b2",
    "ref": "order-123456",
    "status": "HANDLING",
    "type": "ADSL",
    "number": "036362608",
    "topup_amount": 1000,
    "created_at": "2025-11-01T12:00:00.000Z"
  }
}

​
منفَّذ (نجاح)

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b2",
    "ref": "order-123456",
    "status": "FULFILLED",
    "type": "ADSL",
    "number": "036362608",
    "topup_amount": 1000,
    "card_code": "123456789012",
    "num_trans": "AT-2025-12345",
    "date_traitement": "2025-11-01T12:00:45.000Z",
    "created_at": "2025-11-01T12:00:00.000Z"
  }
}

​
في قائمة الانتظار

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b2",
    "ref": "order-123456",
    "status": "QUEUED",
    "type": "ADSL",
    "number": "036362608",
    "topup_amount": 1000,
    "created_at": "2025-11-01T12:00:00.000Z"
  }
}

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

async function pollTopupUntilComplete(topupId, maxAttempts = 60) {
  const pollInterval = 5000; // 5 seconds

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    console.log(`Polling attempt ${attempt}/${maxAttempts}`);

    const order = await checkTopupStatus(topupId);

    const finalStates = ['FULFILLED', 'REFUNDED', 'QUEUED'];
    if (finalStates.includes(order.status)) {
      return order;
    }

    if (attempt < maxAttempts) {
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    }
  }

  throw new Error('Polling timeout - order still processing');
}

// Usage
try {
  const order = await pollTopupUntilComplete('6901616fe9e88196b4eb64b2');

  if (order.status === 'FULFILLED') {
    console.log('✅ Card delivered:', order.card_code);
  } else if (order.status === 'QUEUED') {
    console.log('⏰ Order scheduled for later');
  } else if (order.status === 'REFUNDED') {
    console.log('❌ Order failed and refunded');
  }
} catch (error) {
  console.error('Polling failed:', error.message);
}

​
استراتيجية الاستعلام المتكيفة

اضبط تكرار الاستعلام بناءً على الوقت المنقضي:
async function pollTopupAdaptive(topupId, maxDuration = 5 * 60 * 1000) {
  const startTime = Date.now();
  let pollInterval = 3000; // Start with 3 seconds
  
  while (Date.now() - startTime < maxDuration) {
    const order = await checkTopupStatus(topupId);
    
    // Check for final state
    const finalStates = ['FULFILLED', 'REFUNDED', 'QUEUED'];
    if (finalStates.includes(order.status)) {
      return order;
    }
    
    // Adaptive interval: increase as time passes
    const elapsed = Date.now() - startTime;
    if (elapsed > 60000) {
      pollInterval = 10000; // 10 seconds after 1 minute
    } else if (elapsed > 30000) {
      pollInterval = 5000; // 5 seconds after 30 seconds
    }
    
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
  
  throw new Error('Order processing timeout');
}

// Usage
const order = await pollTopupAdaptive('6901616fe9e88196b4eb64b2');

​
معالجة نتائج الطلب

async function handleTopupResult(topupId, order) {
  switch (order.status) {
    case 'FULFILLED':
      console.log(`✅ Order fulfilled`);
      console.log(`Card: ${order.card_code}`);
      console.log(`Transaction: ${order.num_trans}`);
      
      // Update database
      await db.internetOrders.updateOne(
        { topupId },
        { 
          $set: { 
            status: 'FULFILLED',
            cardCode: order.card_code,
            numTrans: order.num_trans,
            dateTraitement: order.date_traitement,
            fulfilledAt: new Date()
          } 
        }
      );
      
      // Deliver card to customer
      await deliverCard(order);
      break;
    
    case 'QUEUED':
      console.log(`⏰ Order scheduled for later delivery`);
      
      // Update database
      await db.internetOrders.updateOne(
        { topupId },
        { 
          $set: { 
            status: 'SCHEDULED',
            message: 'Card will be delivered within 48 hours',
            nextCheckAt: new Date(Date.now() + 24 * 60 * 60 * 1000)
          } 
        }
      );
      
      // Schedule recheck after 24 hours
      await scheduleRecheck(topupId, 24 * 60 * 60 * 1000);
      
      // Notify customer
      await notifyCustomer(order, 
        'Your order is scheduled and will be delivered within 48 hours.'
      );
      break;
    
    case 'REFUNDED':
      console.log(`❌ Order failed and refunded`);
      
      // Update database
      await db.internetOrders.updateOne(
        { topupId },
        { 
          $set: { 
            status: 'REFUNDED',
            refundedAt: new Date()
          } 
        }
      );
      
      // Notify customer of failure
      await notifyCustomer(order, 
        'Your order could not be completed. A full refund has been issued.'
      );
      break;
  }
}

​
معالجة حالة QUEUED

الطلبات في حالة QUEUED ليست فشلاً! إنها مجدولة للتسليم خلال 12-48 ساعة.
async function handleTopupResult(order) {
  switch (order.status) {
    case 'FULFILLED':
      await storeCardSecurely(order._id, order);
      await deliverCardToCustomer(order._id, order);
      console.log('✅ Topup fulfilled and delivered');
      break;

    case 'QUEUED':
      await updateOrderStatus(order._id, 'QUEUED');
      await scheduleRecheck(order._id, 24 * 60 * 60 * 1000); // 24 hours
      await notifyCustomerQueued(order._id);
      console.log('⏰ Topup queued - will recheck in 24 hours');
      break;

    case 'REFUNDED':
      await updateOrderStatus(order._id, 'FAILED');
      await notifyCustomerRefunded(order._id);
      console.log('❌ Topup failed and refunded');
      break;
  }
}

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

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

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

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

لا تعامل QUEUED كفشل - جدوّل إعادة التحقق بعد 24 ساعة

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

أوقف الاستعلام بأمان بعد 5 دقائق

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

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

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

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

تسليم رموز البطاقات بأمان للعملاء

إرسال الشحنات

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

مرجع API

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