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

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.

نظرة عامة

أرسل طلبات شحن الإنترنت بعد التحقق من أرقام الهاتف والتأكد من توفر المنتجات. تُعالَج الطلبات مع المشغل وتكتمل عادةً في 3-45 ثانية.
تحقق دائماً من الأرقام أولاً باستخدام /check-number لتقليل الفشل وطلبات الاسترداد.

مرجع API

POST /v3/internet/send

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

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

async function sendInternetTopup(orderData) {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/internet/send",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Access-Token": process.env.API_KEY,
      },
      body: JSON.stringify({
        type: orderData.type,
        number: orderData.number,
        value: orderData.value,
        ref: orderData.ref,
      }),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || `HTTP ${response.status}`);
  }

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

// Usage
const order = await sendInternetTopup({
  type: 'ADSL',
  number: '036362608',
  value: 1000,
  ref: `order-${Date.now()}`
});

console.log('Top-up sent:', order.topupId);

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

{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b2",
    "topupRef": "order-123456"
  },
  "meta": {
    "timestamp": "2025-11-01T12:00:00.000Z"
  }
}

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

تحقق دائماً قبل إرسال الطلبات:
async function validateAndSend(orderData) {
  // Step 1: Validate phone number
  try {
    await validateInternetNumber(orderData.type, orderData.number);
  } catch (error) {
    throw new Error(`Invalid phone number: ${error.message}`);
  }

  // Step 2: Check product availability
  const products = await loadInternetProducts(orderData.type);
  const product = products.find(
    p => p.value === orderData.value && p.available
  );

  if (!product) {
    throw new Error(`Product ${orderData.value} DA not available for ${orderData.type}`);
  }

  // Step 3: Check balance
  const balance = await getBalance();
  if (balance < product.cost) {
    throw new Error(
      `Insufficient balance. Required: ${product.cost} DA, Available: ${balance} DA`
    );
  }

  // Step 4: Send request
  console.log(`Sending ${orderData.type} ${orderData.value} DA to ${orderData.number}`);
  const result = await sendInternetTopup(orderData);

  return {
    topupId: result.topupId,
    topupRef: result.topupRef,
    cost: product.cost,
    type: orderData.type,
    number: orderData.number,
    value: orderData.value
  };
}

async function getBalance() {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/account/balance",
    { headers: { "X-Access-Token": process.env.API_KEY } }
  );
  const result = await response.json();
  return result.data.balance;
}

// Usage
try {
  const result = await validateAndSend({
    type: 'ADSL',
    number: '036362608',
    value: 1000,
    ref: `order-${Date.now()}`
  });
  console.log('✅ Order placed successfully');
  console.log(`  Top-up ID: ${result.topupId}`);
  console.log(`  Cost: ${result.cost} DA`);
} catch (error) {
  console.error('❌ Order failed:', error.message);
}

تتبع المعاملات

احفظ تفاصيل الطلب في قاعدة البيانات:
async function createOrderTransaction(userId, orderDetails) {
  const transaction = {
    userId,
    topupId: orderDetails.topupId,
    ref: orderDetails.topupRef,
    type: orderDetails.type,
    number: orderDetails.number,
    value: orderDetails.value,
    cost: orderDetails.cost,
    status: 'HANDLING',
    createdAt: new Date(),
    updatedAt: new Date()
  };
  
  await db.internetOrders.insertOne(transaction);
  
  console.log('Transaction saved:', transaction.topupId);
  return transaction;
}

// Usage
const orderResult = await validateAndSend(orderData);
await createOrderTransaction(userId, orderResult);

توليد مراجع فريدة

تأكد من أن كل طلب له مرجع فريد:
function generateOrderReference(userId, type) {
  const timestamp = Date.now();
  const random = Math.random().toString(36).substring(2, 8);
  return `${type.toLowerCase()}-${userId}-${timestamp}-${random}`;
}

// Usage
const ref = generateOrderReference(123, 'ADSL');
// Example: 'adsl-123-1730448000000-x7k2m9'

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

async function sendTopupSafely(orderData) {
  try {
    const result = await sendInternetTopup(orderData);
    return { success: true, data: result };
  } catch (error) {
    const message = error.message.toLowerCase();

    if (message.includes('err_phone')) {
      return {
        success: false,
        error: 'INVALID_PHONE',
        message: 'Invalid phone number for this service type'
      };
    }

    if (message.includes('err_stock')) {
      return {
        success: false,
        error: 'OUT_OF_STOCK',
        message: 'This card value is currently out of stock'
      };
    }

    if (message.includes('insufficient_balance')) {
      return {
        success: false,
        error: 'LOW_BALANCE',
        message: 'Insufficient account balance'
      };
    }

    if (message.includes('duplicated_ref')) {
      return {
        success: false,
        error: 'DUPLICATE_REF',
        message: 'This reference has already been used'
      };
    }

    return {
      success: false,
      error: 'UNKNOWN',
      message: 'Failed to process order. Please try again.'
    };
  }
}

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

التحقق أولاً

استخدم دائماً /check-number قبل الإرسال

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

تحقق من توفر المنتج قبل الطلب

مرجعيات فريدة

أنشئ ref فريداً لكل طلب

تخزين topupId فوراً

احفظ topupId في قاعدة البيانات فور نجاح الإرسال

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

1

تخزين معرف الشحنة

احفظ topupId في قاعدة البيانات فوراً
2

بدء الاستعلام

ابدأ التحقق من الحالة كل 5-10 ثوانٍ
3

تحديث الواجهة

أظهر رسالة “جاري معالجة الطلب…” للمستخدم
4

انتظار الحالة النهائية

استمر في الاستعلام حتى FULFILLED أو REFUNDED أو QUEUED

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

تتبع الحالة

استعلام حالة الطلب حتى الاكتمال

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

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

مرجع API

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

التحقق من الأرقام

التحقق من أرقام الهاتف أولاً

نظرة عامة

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

فحص الرصيد

الحصول على رصيد الحساب