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

نظرة عامة

أرسل طلبات شحن الإنترنت بعد التحقق من أرقام الهاتف والتأكد من توفر المنتجات. تُعالَج الطلبات مع المشغل وتكتمل عادةً في 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);

import requests
import os
import time

def send_internet_topup(order_data):
    response = requests.post(
        'https://api.oneclickdz.com/v3/internet/send',
        headers={
            'Content-Type': 'application/json',
            'X-Access-Token': os.getenv('API_KEY')
        },
        json={
            'type': order_data['type'],
            'number': order_data['number'],
            'value': order_data['value'],
            'ref': order_data['ref']
        }
    )

    if not response.ok:
        error = response.json()
        raise Exception(error.get('error', {}).get('message', f'HTTP {response.status_code}'))

    return response.json()['data']

# Usage
order = send_internet_topup({
    'type': 'ADSL',
    'number': '036362608',
    'value': 1000,
    'ref': f'order-{int(time.time() * 1000)}'
})

print(f'Top-up sent: {order["topupId"]}')

<?php

function sendInternetTopup($orderData) {
    $data = [
        'type' => $orderData['type'],
        'number' => $orderData['number'],
        'value' => $orderData['value'],
        'ref' => $orderData['ref']
    ];

    $ch = curl_init('https://api.oneclickdz.com/v3/internet/send');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-Access-Token: ' . getenv('API_KEY')
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

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

    if ($httpCode >= 400) {
        $error = json_decode($response, true);
        throw new Exception($error['error']['message'] ?? "HTTP {$httpCode}");
    }

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

// Usage
$order = sendInternetTopup([
    'type' => 'ADSL',
    'number' => '036362608',
    'value' => 1000,
    'ref' => 'order-' . (int)(microtime(true) * 1000)
]);

echo "Top-up sent: {$order['topupId']}\n";
?>

curl https://api.oneclickdz.com/v3/internet/send \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: YOUR_API_KEY" \
  -d '{
    "type": "ADSL",
    "number": "036362608",
    "value": 1000,
    "ref": "order-123456"
  }'

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

{
  "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);
}

def validate_and_send(order_data):
    # Step 1: Validate phone number
    try:
        validate_internet_number(order_data['type'], order_data['number'])
    except Exception as e:
        raise ValueError(f"Invalid phone number: {e}")

    # Step 2: Check product availability
    products = load_internet_products(order_data['type'])
    product = next(
        (p for p in products if p['value'] == order_data['value'] and p['available']),
        None
    )

    if not product:
        raise ValueError(
            f"Product {order_data['value']} DA not available for {order_data['type']}"
        )

    # Step 3: Check balance
    balance = get_balance()
    if balance < product['cost']:
        raise ValueError(
            f"Insufficient balance. Required: {product['cost']} DA, Available: {balance} DA"
        )

    # Step 4: Send request
    result = send_internet_topup(order_data)

    return {
        'topupId': result['topupId'],
        'topupRef': result['topupRef'],
        'cost': product['cost'],
        'type': order_data['type'],
        'number': order_data['number'],
        'value': order_data['value']
    }

def get_balance():
    response = requests.get(
        'https://api.oneclickdz.com/v3/account/balance',
        headers={'X-Access-Token': os.getenv('API_KEY')}
    )
    response.raise_for_status()
    return response.json()['data']['balance']

# Usage
try:
    result = validate_and_send({
        'type': 'ADSL',
        'number': '036362608',
        'value': 1000,
        'ref': f'order-{int(time.time() * 1000)}'
    })
    print('✅ Order placed successfully')
    print(f"  Top-up ID: {result['topupId']}")
    print(f"  Cost: {result['cost']} DA")
except ValueError as e:
    print(f'❌ Order failed: {e}')

<?php

function validateAndSend($orderData) {
    // Step 1: Validate phone number
    try {
        validateInternetNumber($orderData['type'], $orderData['number']);
    } catch (Exception $e) {
        throw new Exception("Invalid phone number: " . $e->getMessage());
    }

    // Step 2: Check product availability
    $products = loadInternetProducts($orderData['type']);
    $product = null;
    foreach ($products as $p) {
        if ($p['value'] === $orderData['value'] && $p['available']) {
            $product = $p;
            break;
        }
    }

    if ($product === null) {
        throw new Exception(
            "Product {$orderData['value']} DA not available for {$orderData['type']}"
        );
    }

    // Step 3: Check balance
    $balance = getBalance();
    if ($balance < $product['cost']) {
        throw new Exception(
            "Insufficient balance. Required: {$product['cost']} DA, Available: {$balance} DA"
        );
    }

    // Step 4: Send request
    $result = sendInternetTopup($orderData);

    return [
        'topupId' => $result['topupId'],
        'topupRef' => $result['topupRef'],
        'cost' => $product['cost'],
        'type' => $orderData['type'],
        'number' => $orderData['number'],
        'value' => $orderData['value']
    ];
}

function getBalance() {
    $ch = curl_init('https://api.oneclickdz.com/v3/account/balance');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Access-Token: ' . getenv('API_KEY')
    ]);
    $response = curl_exec($ch);
    curl_close($ch);

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

// Usage
try {
    $result = validateAndSend([
        'type' => 'ADSL',
        'number' => '036362608',
        'value' => 1000,
        'ref' => 'order-' . (int)(microtime(true) * 1000)
    ]);
    echo "✅ Order placed successfully\n";
    echo "  Top-up ID: {$result['topupId']}\n";
    echo "  Cost: {$result['cost']} DA\n";
} catch (Exception $e) {
    echo "❌ Order failed: " . $e->getMessage() . "\n";
}
?>

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

احفظ تفاصيل الطلب في قاعدة البيانات:

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

def send_topup_safely(order_data):
    try:
        result = send_internet_topup(order_data)
        return {'success': True, 'data': result}
    except Exception as error:
        message = str(error).lower()
        
        if 'err_phone' in message:
            return {
                'success': False,
                'error': 'INVALID_PHONE',
                'message': 'Invalid phone number for this service type'
            }
        
        if 'err_stock' in message:
            return {
                'success': False,
                'error': 'OUT_OF_STOCK',
                'message': 'This card value is currently out of stock'
            }
        
        if 'insufficient_balance' in message:
            return {
                'success': False,
                'error': 'LOW_BALANCE',
                'message': 'Insufficient account balance'
            }
        
        if 'duplicated_ref' in message:
            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.'
        }

<?php

function sendTopupSafely($orderData) {
    try {
        $result = sendInternetTopup($orderData);
        return ['success' => true, 'data' => $result];
    } catch (Exception $error) {
        $message = strtolower($error->getMessage());
        
        if (strpos($message, 'err_phone') !== false) {
            return [
                'success' => false,
                'error' => 'INVALID_PHONE',
                'message' => 'Invalid phone number for this service type'
            ];
        }
        
        if (strpos($message, 'err_stock') !== false) {
            return [
                'success' => false,
                'error' => 'OUT_OF_STOCK',
                'message' => 'This card value is currently out of stock'
            ];
        }
        
        if (strpos($message, 'insufficient_balance') !== false) {
            return [
                'success' => false,
                'error' => 'LOW_BALANCE',
                'message' => 'Insufficient account balance'
            ];
        }
        
        if (strpos($message, 'duplicated_ref') !== false) {
            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 في قاعدة البيانات فور نجاح الإرسال

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

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

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

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

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

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

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

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

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

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

تتبع الحالة

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

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

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

مرجع API

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

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

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

نظرة عامة

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

فحص الرصيد

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

​نظرة عامة

​مرجع API

POST /v3/internet/send

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

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

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

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

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

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

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

التحقق أولاً

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

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

تخزين topupId فوراً

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

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

تتبع الحالة

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

مرجع API

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

نظرة عامة

فحص الرصيد

نظرة عامة

مرجع API

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

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

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

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

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

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

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

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

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