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

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 /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