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 في قاعدة البيانات فور نجاح الإرسال
بعد تقديم الطلب
تخزين معرف الشحنة
احفظ topupId في قاعدة البيانات فوراً
بدء الاستعلام
ابدأ التحقق من الحالة كل 5-10 ثوانٍ
تحديث الواجهة
أظهر رسالة “جاري معالجة الطلب…” للمستخدم
انتظار الحالة النهائية
استمر في الاستعلام حتى FULFILLED أو REFUNDED أو QUEUED
الخطوات التالية
تتبع الحالة
استعلام حالة الطلب حتى الاكتمال
تسليم البطاقات
تسليم رموز البطاقات للعملاء
مرجع API
التوثيق الكامل للـ endpoint
التحقق من الأرقام
التحقق من أرقام الهاتف أولاً
نظرة عامة
العودة إلى نظرة عامة على التكامل
فحص الرصيد
الحصول على رصيد الحساب