إرسال شحن الهاتف المحمول
curl --request POST \
--url https://api.oneclickdz.com/v3/mobile/send \
--header 'X-Access-Token: <api-key>'import requests
url = "https://api.oneclickdz.com/v3/mobile/send"
headers = {"X-Access-Token": "<api-key>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {'X-Access-Token': '<api-key>'}};
fetch('https://api.oneclickdz.com/v3/mobile/send', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.oneclickdz.com/v3/mobile/send",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"X-Access-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.oneclickdz.com/v3/mobile/send"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("X-Access-Token", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.oneclickdz.com/v3/mobile/send")
.header("X-Access-Token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.oneclickdz.com/v3/mobile/send")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'
response = http.request(request)
puts response.read_bodyشحن الهاتف
إرسال شحن الهاتف المحمول
إنشاء وإرسال طلب شحن هاتف محمول
POST
/
v3
/
mobile
/
send
إرسال شحن الهاتف المحمول
curl --request POST \
--url https://api.oneclickdz.com/v3/mobile/send \
--header 'X-Access-Token: <api-key>'import requests
url = "https://api.oneclickdz.com/v3/mobile/send"
headers = {"X-Access-Token": "<api-key>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {'X-Access-Token': '<api-key>'}};
fetch('https://api.oneclickdz.com/v3/mobile/send', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.oneclickdz.com/v3/mobile/send",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"X-Access-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.oneclickdz.com/v3/mobile/send"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("X-Access-Token", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.oneclickdz.com/v3/mobile/send")
.header("X-Access-Token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.oneclickdz.com/v3/mobile/send")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'
response = http.request(request)
puts response.read_bodyنظرة عامة
إرسال شحن هاتف محمول فوري إلى جميع شبكات الهاتف الجزائرية (Mobilis وDjezzy وOoredoo وPixx) مع تتبع الحالة في الوقت الفعلي.لا تعيد محاولة الطلبات الفاشلة دون التحقق من الحالة أولًا باستخدام
check-by-ref أو
check-by-id. يمكن أن تتسبب طلبات
الإرسال المكررة في خصم مزدوج.
متن الطلب
string
مطلوب
رمز الخطة من list-plans (مثلًا:
PREPAID_DJEZZY، MIX1000_OOREDOO)string
مطلوب
رقم الهاتف المحمول الجزائري بصيغة
0XXXXXXXXX (10 أرقام تبدأ بـ 05، 06، أو 07)number
مبلغ الشحن بالدينار الجزائري. مطلوب فقط للخطط الديناميكية (حيث
min_amount وmax_amount محددان). غير مطلوب للخطط الثابتة.string
مرجع داخلي فريد (معرّف طلبك). يُستخدم لمنع الطلبات المكررة والتحقق من الحالة لاحقًا.
استخدم
ref دائمًا إذا كنت ترسل طلبات من جانب الخادم. يمنع الخصم المزدوج إذا فشل طلب الشبكة.الاستجابة
boolean
مطلوب
يشير إلى نجاح الطلب
object
مطلوب
إظهار properties
إظهار properties
string
معرّف الشحن الداخلي. استخدمه مع check-by-id للتتبع.
string
مرجعك الداخلي (من حقل
ref في الطلب). يُرجع null إذا لم تُحدد ref.number
رصيد حسابك بعد إرسال الشحن
الأمثلة
خطة ديناميكية (يحدد المبلغ)
curl -X POST https://api.oneclickdz.com/v3/mobile/send \
-H "X-Access-Token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"plan_code": "PREPAID_DJEZZY",
"MSSIDN": "0776543210",
"amount": 500,
"ref": "order-001"
}'
const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", {
method: "POST",
headers: {
"X-Access-Token": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
plan_code: "PREPAID_DJEZZY",
MSSIDN: "0776543210",
amount: 500,
ref: "order-001",
}),
});
const data = await response.json();
import requests
response = requests.post(
'https://api.oneclickdz.com/v3/mobile/send',
headers={'X-Access-Token': 'YOUR_API_KEY', 'Content-Type': 'application/json'},
json={
'plan_code': 'PREPAID_DJEZZY',
'MSSIDN': '0776543210',
'amount': 500,
'ref': 'order-001'
}
)
data = response.json()
خطة ثابتة (لا مبلغ)
curl -X POST https://api.oneclickdz.com/v3/mobile/send \
-H "X-Access-Token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"plan_code": "MIX1000_OOREDOO",
"MSSIDN": "0554926570",
"ref": "order-002"
}'
const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", {
method: "POST",
headers: {
"X-Access-Token": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
plan_code: "MIX1000_OOREDOO",
MSSIDN: "0554926570",
ref: "order-002",
}),
});
const data = await response.json();
import requests
response = requests.post(
'https://api.oneclickdz.com/v3/mobile/send',
headers={'X-Access-Token': 'YOUR_API_KEY'},
json={
'plan_code': 'MIX1000_OOREDOO',
'MSSIDN': '0554926570',
'ref': 'order-002'
}
)
data = response.json()
مثال على الاستجابة
{
"success": true,
"data": {
"topupId": "6901616fe9e88196b4eb64b0",
"topupRef": "order-001",
"newBalance": 826.13
},
"meta": {
"timestamp": "2025-10-29T00:35:59.454Z"
}
}
استجابات الخطأ
400 - خطأ في التحقق
400 - خطأ في التحقق
{
"success": false,
"error": {
"code": "ERR_VALIDATION",
"message": "Validation error",
"details": {
"amount": "Amount must be between 100 and 10000 for this plan"
}
}
}
400 - رقم هاتف غير صالح
400 - رقم هاتف غير صالح
{
"success": false,
"error": {
"code": "ERR_PHONE",
"message": "Invalid phone number"
}
}
403 - رصيد غير كافٍ
403 - رصيد غير كافٍ
{
"success": false,
"error": {
"code": "NO_BALANCE",
"message": "Insufficient balance"
}
}
403 - مرجع مكرر
403 - مرجع مكرر
{
"success": false,
"error": {
"code": "DUPLICATED_REF",
"message": "This reference ID is already in use"
}
}
إذا تلقيت هذا الخطأ، لا ترسل طلبًا جديدًا. بدلًا من ذلك، تحقق من حالة الطلب الموجود باستخدام
ref.500 - خطأ داخلي
500 - خطأ داخلي
{
"success": false,
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "Developer was notified and will check shortly"
}
}
لا تسترد الأموال فورًا. ابقَ على تتبع الطلب لمدة 24 ساعة. نظام الشحن غالبًا ما يُكمل العملية رغم هذا الخطأ.
منع الطلبات المكررة
يضمن حقل
ref معالجة الشحن مرة واحدة فقط حتى في حالات مشكلات الشبكة.async function sendTopUpSafe(planCode, phone, amount, orderId) {
// Use orderId as the ref for idempotency
const ref = `topup-${orderId}`;
try {
const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", {
method: "POST",
headers: {
"X-Access-Token": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
plan_code: planCode,
MSSIDN: phone,
amount,
ref,
}),
});
const data = await response.json();
if (data.success) {
return { success: true, topupId: data.data.topupId };
}
// Handle duplicate ref - order already exists
if (data.error.code === "DUPLICATED_REF") {
const status = await checkTopUpByRef(ref);
return { success: true, topupId: status.data._id, fromExisting: true };
}
throw new Error(`${data.error.code}: ${data.error.message}`);
} catch (networkError) {
// Network error - check if order was created
const status = await checkTopUpByRef(ref);
if (status.success) {
return { success: true, topupId: status.data._id, fromExisting: true };
}
throw networkError;
}
}
نموذج تدفق كامل
async function processTopUp(userId, planCode, phone, amount) {
// 1. Validate inputs
if (!/^0[567]\d{8}$/.test(phone)) {
throw new Error('Invalid Algerian phone number format');
}
// 2. Check balance
const balance = await getBalance();
if (balance < amount * 1.05) { // Add buffer for safety
throw new Error('Insufficient balance');
}
// 3. Generate unique ref
const ref = `topup-${userId}-${Date.now()}`;
// 4. Send topup
const result = await sendTopUp({
plan_code: planCode,
MSSIDN: phone,
amount,
ref
});
// 5. Store result
await saveTransaction({
ref,
topupId: result.topupId,
status: 'PENDING',
createdAt: new Date()
});
// 6. Return success
return result;
}
تنسيق رقم الهاتف
يجب أن يكون رقم الهاتف نصاً (string)، وليس رقماً. الصفر البادئ مطلوب.
- ✅
"0778037340"(نص مع صفر بادئ) - ✅
"0665983439" - ✅
"0556121212"
- ❌
778037340(الصفر البادئ مفقود) - ❌
0778037340(رقم بدل نص) - ❌
"+213778037340"(تنسيق دولي) - ❌
"0778 037 340"(يحتوي على مسافات)
دورة حياة الحالة
بعد إرسال الشحن، يمر بالحالات التالية:1
PENDING
تم إنشاء الطلب وإضافته للمعالجة المدة: 2-15 ثانية (عادةً)
2
HANDLING
جارٍ المعالجة من قِبَل المشغّل المدة: 3-8 ثوانٍ (عادةً)
3
الحالة النهائية
FULFILLED: اكتمل بنجاح ✅ REFUNDED: فشل واسترداد المبلغ ❌ UNKNOWN_ERROR: حالة غير محددة (تُحسم خلال 24 ساعة) ⚠️
اختبار Sandbox
فعّل وضع Sandbox للاختبار دون معاملات حقيقية:التدفق الطبيعي
استخدم أي رقم عادي (مثل
0778037340) التدفق: PENDING (5ث) → HANDLING (15ث) → FULFILLEDاسترداد مع رسالة
استخدم:
0600000001 النتيجة: REFUNDED مع refund_messageعدم تطابق الخطة
استخدم:
0600000002 النتيجة: REFUNDED مع suggested_offersخطأ غير معروف
استخدم:
0600000003 النتيجة: حالة UNKNOWN_ERRORراجع دليل سير عمل شحن الهاتف للحصول على تعليمات اختبار Sandbox الكاملة.
أفضل الممارسات
استخدم مراجع فريدة
قدّم دائماً
ref فريداً لمنع التكرار وتسهيل التتبعتحقق قبل الإرسال
تحقق من الخطة وتنسيق الهاتف والرصيد من جهة العميل لتقليل الأخطاء
اعمل بشكل غير متزامن
نفّذ طلبات API بشكل غير متزامن لتجنب إيقاف طلبات المستخدمين
نفّذ منطق إعادة المحاولة
أعد المحاولة عند فشل الطلبات مع تأخير أسي لأخطاء الشبكة
Endpoints ذات الصلة
قائمة الخطط
استعرض الخطط المتاحة
التحقق من الحالة بالمرجع
تتبع باستخدام مرجعك
التحقق من الحالة بالمعرّف
تتبع باستخدام topupId

