التحقق من الحالة بالمرجع
curl --request GET \
--url https://api.oneclickdz.com/v3/mobile/check-ref/{ref} \
--header 'X-Access-Token: <api-key>'import requests
url = "https://api.oneclickdz.com/v3/mobile/check-ref/{ref}"
headers = {"X-Access-Token": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};
fetch('https://api.oneclickdz.com/v3/mobile/check-ref/{ref}', 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/check-ref/{ref}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
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/check-ref/{ref}"
req, _ := http.NewRequest("GET", 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.get("https://api.oneclickdz.com/v3/mobile/check-ref/{ref}")
.header("X-Access-Token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.oneclickdz.com/v3/mobile/check-ref/{ref}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'
response = http.request(request)
puts response.read_bodyشحن الهاتف
التحقق من الحالة بالمرجع
التحقق من حالة شحن الهاتف المحمول باستخدام مرجعك المخصص
GET
/
v3
/
mobile
/
check-ref
/
{ref}
التحقق من الحالة بالمرجع
curl --request GET \
--url https://api.oneclickdz.com/v3/mobile/check-ref/{ref} \
--header 'X-Access-Token: <api-key>'import requests
url = "https://api.oneclickdz.com/v3/mobile/check-ref/{ref}"
headers = {"X-Access-Token": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};
fetch('https://api.oneclickdz.com/v3/mobile/check-ref/{ref}', 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/check-ref/{ref}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
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/check-ref/{ref}"
req, _ := http.NewRequest("GET", 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.get("https://api.oneclickdz.com/v3/mobile/check-ref/{ref}")
.header("X-Access-Token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.oneclickdz.com/v3/mobile/check-ref/{ref}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'
response = http.request(request)
puts response.read_bodyنظرة عامة
يُرجع حالة شحن هاتف محمول باستخدام قيمةref التي حددتها عند إرسال الشحن.إذا أرسلت طلبًا بدون
ref، استخدم check-by-id مع topupId المُرجع.المعلمات
string
مطلوب
مرجعك الداخلي كما وفّرته في طلب الشحن
الاستجابة
boolean
مطلوب
true إذا تم العثور على الشحن وإرجاع حالتهobject
مطلوب
إظهار properties
إظهار properties
string
معرّف الشحن الداخلي
string
مرجعك الداخلي
string
الحالة الحالية للشحن. القيم المحتملة:
PENDING: قيد المعالجةSUCCESS: اكتمل الشحنFAILED: فشل بشكل نهائي (الرصيد مُسترد)UNKNOWN_ERROR: حالة غير محددة - انتظر، لا تسترد الأموال
string
رقم الهاتف الذي تم شحنه
string
مشغّل الشبكة:
Mobilis، Djezzy، أو Ooredoostring
رمز الخطة المستخدمة
string
الاسم المقروء للخطة
number
مبلغ الشحن بالدينار الجزائري
number
التكلفة الفعلية من رصيدك
string
طابع زمني للإنشاء (ISO 8601)
string
طابع زمني لآخر تحديث للحالة (ISO 8601)
قيم الحالة
| الحالة | المعنى | الإجراء |
|---|---|---|
PENDING | الشحن قيد المعالجة | تحقق مجددًا بعد 5-10 ثوانٍ |
SUCCESS | الشحن اكتمل بنجاح | أبلغ المستخدم بالنجاح |
FAILED | الشحن فشل نهائيًا | الرصيد مُسترد - يمكن المحاولة مجددًا |
UNKNOWN_ERROR | حالة غير محددة | انتظر 24 ساعة - لا تسترد الأموال |
الأمثلة
curl https://api.oneclickdz.com/v3/mobile/topup/ref/order-001 \
-H "X-Access-Token: YOUR_API_KEY"
const ref = "order-001";
const response = await fetch(
`https://api.oneclickdz.com/v3/mobile/topup/ref/${encodeURIComponent(ref)}`,
{
headers: { "X-Access-Token": "YOUR_API_KEY" },
}
);
const data = await response.json();
console.log("Status:", data.data.status);
import requests
ref = 'order-001'
response = requests.get(
f'https://api.oneclickdz.com/v3/mobile/topup/ref/{ref}',
headers={'X-Access-Token': 'YOUR_API_KEY'}
)
data = response.json()
print('Status:', data['data']['status'])
<?php
$ref = 'order-001';
$ch = curl_init("https://api.oneclickdz.com/v3/mobile/topup/ref/{$ref}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Access-Token: YOUR_API_KEY']);
$data = json_decode(curl_exec($ch), true);
echo 'Status: ' . $data['data']['status'];
?>
مثال على الاستجابة
{
"success": true,
"data": {
"_id": "6901616fe9e88196b4eb64b0",
"ref": "order-001",
"status": "SUCCESS",
"MSSIDN": "0776543210",
"operator": "Djezzy",
"planCode": "PREPAID_DJEZZY",
"planName": "📱 PREPAID | عادي",
"amount": 500,
"cost": 496.25,
"createdAt": "2025-10-29T00:35:59.454Z",
"updatedAt": "2025-10-29T00:36:05.123Z"
}
}
استراتيجية الاستطلاع (Polling)
async function pollTopUpStatus(ref, maxAttempts = 12, intervalMs = 5000) {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const response = await fetch(
`https://api.oneclickdz.com/v3/mobile/topup/ref/${encodeURIComponent(ref)}`,
{
headers: { "X-Access-Token": API_KEY },
}
);
const data = await response.json();
if (!data.success) {
throw new Error(`Failed to check status: ${data.error.message}`);
}
const { status } = data.data;
if (status === "SUCCESS") {
return { success: true, data: data.data };
}
if (status === "FAILED") {
return { success: false, data: data.data };
}
if (status === "UNKNOWN_ERROR") {
// Stop polling - schedule a check after 24h, do NOT refund
return { success: null, data: data.data, requiresManualReview: true };
}
// Still PENDING - wait and retry
if (attempt < maxAttempts) {
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}
}
// Timeout - treat as UNKNOWN_ERROR
return { success: null, timedOut: true, requiresManualReview: true };
}
متى تستخدم هذا الـ Endpoint
استعلامات المستخدمين
عندما يسأل المستخدمون عن طلباتهم باستخدام معرّف الطلب الخاص بك
إدارة الطلبات
التكامل مع نظام تتبع الطلبات الحالي لديك
صفحات الحالة
عرض حالة الطلب باستخدام مراجع مواجهة العملاء
دعم العملاء
البحث عن الطلبات عبر أرقام المراجع الخاصة بالعملاء
استجابة الخطأ
404 - غير موجود:{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Top-up with reference 'order-12345' not found"
},
"requestId": "req_1730160975_abc123"
}
- لم يُرسَل المرجع أبداً
- خطأ إملائي في المرجع
- المرجع ينتمي إلى حساب مختلف
أفضل الممارسات
استخدم مراجع ذات معنى
استخدم مراجع ذات معنى
أنشئ مراجع تكون:
- فريدة في نظامك
- سهلة التعرف عليها (مثل
order-{timestamp}-{userId}) - آمنة في عناوين URL (بدون أحرف خاصة)
- قابلة للبحث في قاعدة بياناتك
احفظ المعرّفَين
احفظ المعرّفَين
احفظ كلاً من مرجعك ومعرّف topupId الخاص بـ API:يتيح لك ذلك التتبع باستخدام أي من المعرّفين.
await db.orders.update({
orderId: 'order-12345',
apiTopupId: response.data.topupId,
apiTopupRef: response.data.topupRef
});
تعامل مع المراجع المفقودة
تعامل مع المراجع المفقودة
إذا نسيت تقديم
ref، ينشئ الـ API مرجعاً تلقائياً. احفظه:const response = await sendTopup({
plan_code: 'PREPAID_DJEZZY',
MSSIDN: '0778037340',
amount: 500
// No ref provided
});
// API returns: { topupRef: "auto-gen-1730160975" }
await db.orders.update({
orderId: order.id,
apiRef: response.data.topupRef
});
Endpoints ذات الصلة
التحقق من الحالة بالمعرّف
البحث بـ topupId
إرسال الشحن
إرسال شحن جديد
قائمة الشحنات
عرض الشحنات السابقة

