تنسيق الاستجابة

البنية الموحدة

تتبع جميع endpoints في OneClickDz Flexy API v3 بنية استجابة متسقة، مما يسهّل التعامل مع الاستجابات في تطبيقك.

استجابة النجاح

عند نجاح الطلب، تتبع الاستجابة هذه البنية:

{
  "success": true,
  "data": {
    // endpoint-specific data
  },
  "meta": {
    "timestamp": "2025-10-29T00:00:00.000Z"
    // additional metadata (pagination, etc.)
  },
  "requestId": "req_1234567890_abc123"
}

الحقول

boolean

مطلوب

دائمًا true للاستجابات الناجحة

object

مطلوب

يحتوي على محتوى الاستجابة. تختلف البنية حسب كل endpoint.

object

بيانات وصفية إضافية حول الاستجابة

إظهار properties

string

طابع زمني بتنسيق ISO 8601 يشير إلى وقت إنشاء الاستجابة

object

تفاصيل التصفح بالصفحات (لـ endpoints القوائم)

string

معرّف فريد لهذا الطلب. استخدمه عند التواصل مع الدعم الفني.

استجابة الخطأ

عند فشل الطلب، تتبع الاستجابة هذه البنية:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // additional error context
    }
  },
  "requestId": "req_1234567890_abc123"
}

الحقول

boolean

مطلوب

دائمًا false لاستجابات الخطأ

object

مطلوب

يحتوي على معلومات الخطأ

إظهار properties

string

رمز الخطأ القابل للقراءة آليًا (مثل: NO_BALANCE، INVALID_PHONE)

string

وصف الخطأ القابل للقراءة البشرية

object

سياق إضافي حول الخطأ (اختياري)

string

معرّف فريد لهذا الطلب. أدرجه عند الإبلاغ عن المشكلات.

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

رصيد الحساب

{
  "success": true,
  "data": {
    "balance": 1326.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.710Z"
  }
}

إرسال شحن الهاتف المحمول

{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "my-order-123",
    "newBalance": 826.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:59.454Z"
  }
}

قائمة المعاملات (مع التصفح بالصفحات)

{
  "success": true,
  "data": {
    "items": [
      {
        "type": "FLEXY",
        "amount": 500,
        "time": "2025-10-29T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 10,
      "totalResults": 195
    }
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.852Z"
  }
}

التصفح بالصفحات

تتضمن endpoints القوائم بيانات التصفح بالصفحات في الاستجابة:

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 10,
      "totalResults": 195
    }
  }
}

حقول التصفح بالصفحات

integer

رقم الصفحة الحالية (مفهرسة من 1)

integer

عدد العناصر في كل صفحة

integer

العدد الإجمالي للصفحات المتاحة

integer

العدد الإجمالي للعناصر في جميع الصفحات

معلمات الاستعلام للتصفح بالصفحات

تحكّم في التصفح بالصفحات باستخدام هذه المعلمات:

المعلمة	النوع	الافتراضي	الوصف
`page`	integer	1	رقم الصفحة (الحد الأدنى: 1)
`pageSize`	integer	20	العناصر في الصفحة (الأدنى: 1، الأقصى: 100)

تحقق دائمًا من totalPages لمعرفة متى تتوقف عن التصفح.

رموز حالة HTTP

تستخدم API رموز حالة HTTP المعيارية:

رمز الحالة	المعنى
`200`	نجاح - اكتمل الطلب بنجاح
`400`	طلب غير صحيح - معلمات غير صالحة أو خطأ في التحقق
`401`	غير مصرح - مفتاح API غير صالح أو مفقود
`403`	محظور - رصيد أو صلاحيات غير كافية
`404`	غير موجود - المورد غير موجود
`429`	طلبات كثيرة جدًا - تجاوز حد المعدل
`500`	خطأ داخلي في الخادم - حدث خطأ من جانبنا
`503`	الخدمة غير متاحة - انقطاع مؤقت في الخدمة

حتى لرموز الحالة غير 200، تتبع الاستجابة تنسيق الخطأ القياسي.

معرّف الطلب (Request ID)

تتضمن كل استجابة requestId فريدًا:

{
  "success": true,
  "data": {...},
  "requestId": "req_1761698159_abc123xyz"
}

استخدامات Request ID

التصحيح

تتبع الطلبات عبر السجلات وتحديد المشكلات

الدعم الفني

إدراجه في تذاكر الدعم للحصول على حل أسرع

التدقيق

ربط الطلبات بالمعاملات

المراقبة

تتبع تدفق الطلبات عبر الأنظمة

سجّل دائمًا requestId لكل استدعاء API تجريه. إنه لا يُقدّر بثمن للتصحيح.

نوع المحتوى

تستخدم جميع الطلبات والاستجابات JSON:

ترويسات الطلب

Content-Type: application/json
X-Access-Token: YOUR_API_KEY

ترويسات الاستجابة

Content-Type: application/json; charset=utf-8
X-Request-ID: req_1761698159_abc123xyz
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1761698219

التعامل مع الاستجابات

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

تحقق دائماً من حقل success

const response = await fetch(url, options);
const data = await response.json();

if (data.success) {
  // Handle success
  console.log(data.data);
} else {
  // Handle error
  console.error(data.error.code, data.error.message);
}

سجّل Request IDs

console.log(`Request ${data.requestId}: ${data.success ? 'Success' : 'Failed'}`);

if (!data.success) {
  console.error(`Error ${data.error.code}: ${data.error.message}`);
}

معالجة Pagination

let page = 1;
let allItems = [];

while (true) {
  const response = await fetch(`${url}?page=${page}&pageSize=100`);
  const data = await response.json();
  
  if (!data.success) break;
  
  allItems.push(...data.data.items);
  
  if (page >= data.data.pagination.totalPages) break;
  page++;
}

تحليل الطوابع الزمنية

const timestamp = new Date(data.meta.timestamp);
console.log(`Response generated at: ${timestamp.toLocaleString()}`);

دفع الفواتير

تستخدم واجهة دفع الفواتير (Bill Payment API) على https://api.oneclickdz.com نفس المغلّف الموصوف أعلاه: success وdata وmeta وrequestId عند النجاح، وsuccess وerror وrequestId عند الفشل.ثلاث تفاصيل خاصة بها:

التصفح بالصفحات موجود في meta. يُرجع GET /v3/bills/transactions حقل data كمصفوفة بسيطة، مع total وlimit وoffset في meta إلى جانب timestamp.
requestId موجود دائمًا — في جسم كل استجابة، وفي ترويسة X-Request-Id لكل استجابة. سجّله مقابل طلبك الخاص؛ فهو الشيء الوحيد الذي يحتاجه الدعم الفني.
أحد الـ endpoints يُرجع بيانات ثنائية. تنزيل الإيصال يُرسل ملف الإيصال نفسه، لذا لا يوجد مغلّف JSON عند النجاح ويكون X-Request-Id هو المكان الوحيد الذي يظهر فيه معرّف الربط. أما حالات الفشل فيه فتستخدم مغلّف JSON المعتاد.

جلب المعاملة بالمعرّف

كائن المعاملة، حقلًا حقلًا

نظرة عامة على دفع الفواتير

كيف يتكامل المسار بأكمله

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

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

تعلّم كيفية التعامل مع الأخطاء بفعالية

Endpoints الأساسية

استكشف جميع الـ endpoints المتاحة

مرجع API

Core

الحساب

شحن الهاتف

شحن الإنترنت

بطاقات الهدايا

Navio

دفع الفواتير

البنية الموحدة

استجابة النجاح

الحقول

استجابة الخطأ

الحقول

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

رصيد الحساب

إرسال شحن الهاتف المحمول

قائمة المعاملات (مع التصفح بالصفحات)

التصفح بالصفحات

حقول التصفح بالصفحات

معلمات الاستعلام للتصفح بالصفحات

رموز حالة HTTP

معرّف الطلب (Request ID)

استخدامات Request ID

التصحيح

الدعم الفني

التدقيق

المراقبة

نوع المحتوى

ترويسات الطلب

ترويسات الاستجابة

التعامل مع الاستجابات

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

دفع الفواتير

جلب المعاملة بالمعرّف

نظرة عامة على دفع الفواتير

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

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

Endpoints الأساسية

​البنية الموحدة

​استجابة النجاح

​الحقول

​استجابة الخطأ

​الحقول

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

​رصيد الحساب

​إرسال شحن الهاتف المحمول

​قائمة المعاملات (مع التصفح بالصفحات)

​التصفح بالصفحات

​حقول التصفح بالصفحات

​معلمات الاستعلام للتصفح بالصفحات

​رموز حالة HTTP

​معرّف الطلب (Request ID)

​استخدامات Request ID

التصحيح

الدعم الفني

التدقيق

المراقبة

​نوع المحتوى

​ترويسات الطلب

​ترويسات الاستجابة

​التعامل مع الاستجابات

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

​دفع الفواتير

جلب المعاملة بالمعرّف

نظرة عامة على دفع الفواتير

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

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

Endpoints الأساسية

البنية الموحدة

استجابة النجاح

الحقول

استجابة الخطأ

الحقول

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

رصيد الحساب

إرسال شحن الهاتف المحمول

قائمة المعاملات (مع التصفح بالصفحات)

التصفح بالصفحات

حقول التصفح بالصفحات

معلمات الاستعلام للتصفح بالصفحات

رموز حالة HTTP

معرّف الطلب (Request ID)

استخدامات Request ID

نوع المحتوى

ترويسات الطلب

ترويسات الاستجابة

التعامل مع الاستجابات

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

دفع الفواتير

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