الشركاء والحسابات - OneClickDz Flexy API

نظرة عامة

قبل أن تتمكن من استكشاف أي شيء، يجب أن يكون أمران صحيحين: أن يكون مُصدِر الفاتورة متاحاً، وأن يكون معرّف الحساب هو المعرّف الذي يفهمه ذلك المُصدِر. تغطي هذه الخطوة الأمرين معاً، إضافة إلى الفرق بين الخطأين اللذين ستراهما حين يكون الأمر الثاني غير صحيح.

كل ما في هذه الصفحة يستخدم https://billapi.oneclickdz.com وترويسة X-Access-Token. إن لم تكن قد تأكدت بعد من البيئة التي ينتمي إليها مفتاحك، فابدأ بـ التحقق من مفتاح API.

التحقق من التوفر

يُعيد GET /v3/partners مدخلاً واحداً لكل مُصدِر فاتورة، ولكل منها حقل status واحد.

curl https://billapi.oneclickdz.com/v3/partners \
  -H "X-Access-Token: YOUR_API_KEY"

const response = await fetch("https://billapi.oneclickdz.com/v3/partners", {
  headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

const available = Object.entries(body.data)
  .filter(([, partner]) => partner.status === "ACTIVE")
  .map(([name]) => name);

console.log(available);

import os
import requests

response = requests.get(
    'https://billapi.oneclickdz.com/v3/partners',
    headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
)

body = response.json()
if not body['success']:
    raise RuntimeError(body['error']['code'])

available = [
    name for name, partner in body['data'].items()
    if partner['status'] == 'ACTIVE'
]

print(available)

<?php
$ch = curl_init('https://billapi.oneclickdz.com/v3/partners');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!$body['success']) {
    throw new Exception($body['error']['code']);
}

$available = array_keys(array_filter(
    $body['data'],
    fn($partner) => $partner['status'] === 'ACTIVE'
));

print_r($available);
?>

{
  "success": true,
  "data": {
    "ADE": { "status": "ACTIVE" },
    "SONELGAZ": { "status": "ACTIVE" },
    "SEAAL": { "status": "UNAVAILABLE" },
    "AADL": { "status": "UNAVAILABLE" },
    "Algérie Télécom": { "status": "ACTIVE" }
  },
  "meta": { "timestamp": "2026-08-31T10:15:32.194Z" },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

مُصدِر الفاتورة المُعلَّم بـ UNAVAILABLE يُجيب بـ 503 PARTNER_UNAVAILABLE عند الاستكشاف وعند الدفع. وSEAAL وAADL حالياً UNAVAILABLE في كل من sandbox والإنتاج — وهذا هو الإعداد الحالي للمشغّل، لا قيد دائم، لذا أبقِهما في الكود ودع الخريطة تقرر ما يُعرض.

مفتاح PRODUCTION يرى التوفر الفعلي؛ أما مفتاح SANDBOX فيرى خريطة ثابتة، لأن طلب sandbox لا يصل أبداً إلى مُصدِر فاتورة. لا تستخدم sandbox لاختبار كيفية تفاعل تطبيقك مع تعطّل مُصدِر فاتورة — استخدم سيناريوهات sandbox المخصصة لذلك.

المعرّف الخاص بكل مُصدِر فاتورة

أرسل معرّفاً واحداً بالضبط، وأرسل الحقل الذي يخص مُصدِر الفاتورة الذي تستعلم عنه. تُعيد API الحقل نفسه إليك في account في كل معاملة تخص ذلك المُصدِر.

الشريك	الحقل	الصيغة	مثال صالح
`ADE`	`reference`	حتى 50 حرفاً	`"0123456789012345678901234"`
`SEAAL`	`reference`	حتى 50 حرفاً	`"0123456789012340000000000"`
`SONELGAZ`	`contractNumber`	حتى 50 حرفاً	`"9876543210"`
`AADL`	`aadlNumber`	حتى 50 حرفاً	`"1112223334"`
`Algérie Télécom`	`phoneNumber`	`0` أو `+213`، ثم رقم من 2 إلى 4، ثم 7 أرقام	`"023456789"`

{
  "partner": "ADE",
  "account": { "reference": "0123456789012345678901234" },
  "ref": "disc-inv-2026-0042"
}

أرسل Algérie Télécom بعلامات التشكيل الفرنسية كما هي. تُقارَن القيمة حرفاً بحرف، وهي أيضاً المفتاح الذي تقرأه من خريطة الشركاء.

أرقام الهاتف الثابت

phoneNumber هو رقم هاتف ثابت جزائري، لا رقم هاتف محمول.صالح:

"023456789" — صفر في البداية، ثم رقم في المجال 2–4
"+213023456789" غير صالح؛ استخدم "+21323456789" أو الصيغة المحلية "023456789"

غير صالح:

"0778037340" — رقم هاتف محمول، لا رقم هاتف ثابت
"23456789" — ينقصه الصفر في البداية
"023 45 67 89" — يحتوي على مسافات
23456789 — رقم بدلاً من سلسلة نصية

صيغ المعرّف الأكثر تفصيلاً

يقبل مُصدِرا فاتورة كائناً أكمل عندما لا يكفي رقم واحد لتحديد فاتورة بعينها. وكل حقل داخل هذه الكائنات مطلوب.

SONELGAZ — صيغة الفاتورة

{
  "partner": "SONELGAZ",
  "account": {
    "sonelgaz": {
      "invoice_number": "9876543210",
      "amount_without_stamp": "15000",
      "ebb_key": "ABC123"
    }
  },
  "ref": "disc-inv-2026-0042"
}

invoice_number حتى 20 حرفاً، وamount_without_stamp حتى 20، وebb_key حتى 30.

ADE — صيغة الفاتورة

{
  "partner": "ADE",
  "account": {
    "ade": {
      "sub_id": "000123456789",
      "period": "07/2026",
      "amount": "12000",
      "pay_key": "1234567"
    }
  },
  "ref": "disc-inv-2026-0043"
}

sub_id بطول 12 حرفاً بالضبط، وperiod بصيغة MM/YYYY، وamount حتى 20 حرفاً، وpay_key بطول 7 أحرف بالضبط.

ADE وSEAAL — مفتاح من 25 حرفاً

يُقبل electronic_payment_key كبديل عن reference، ويجب أن يكون بطول 25 حرفاً بالضبط.

{
  "partner": "ADE",
  "account": { "electronic_payment_key": "0123456789012345678901234" },
  "ref": "disc-inv-2026-0044"
}

معرّف واحد بالضبط

يجب أن يحمل كائن account معرّفاً واحداً لا أكثر. وتنقسم الحقول إلى أربع خانات:

الخانة	الحقول
مفتاح من نمط المرجع	`reference`، `contractNumber`، `aadlNumber`، `electronic_payment_key`
الهاتف الثابت	`phoneNumber`، `phone_number`
فاتورة SONELGAZ	`sonelgaz`
فاتورة ADE	`ade`

يجب ملء خانة واحدة بالضبط. أما صفر أو اثنتان فيُرفض الطلب قبل أن يحدث أي شيء آخر.

{
  "partner": "ADE",
  "account": {
    "reference": "0123456789012345678901234",
    "phoneNumber": "023456789"
  },
  "ref": "disc-inv-2026-0045"
}

{
  "success": false,
  "error": {
    "code": "ERR_VALIDATION",
    "message": "account must contain exactly one identifier (electronic_payment_key, phone_number, sonelgaz, or ade)",
    "details": [
      "account must contain exactly one identifier (electronic_payment_key, phone_number, sonelgaz, or ade)"
    ]
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

التحقق من ذلك في جانبك يكون بسطر واحد، وهو يحوّل رحلة ذهاب وإياب إلى خطأ فوري في النموذج:

const SLOTS = [
  ["reference", "contractNumber", "aadlNumber", "electronic_payment_key"],
  ["phoneNumber", "phone_number"],
  ["sonelgaz"],
  ["ade"],
];

function hasExactlyOneIdentifier(account) {
  const filled = SLOTS.filter((slot) =>
    slot.some((field) => {
      const value = account[field];
      return value !== undefined && value !== null && value !== "";
    }),
  );

  return filled.length === 1;
}

`ERR_VALIDATION` أم `INVALID_ACCOUNT`؟

كلاهما 400، لكن معنييهما مختلفان جداً.

	`ERR_VALIDATION`	`INVALID_ACCOUNT`
السبب	الطلب لا يطابق المخطط	المعرّف سليم الصيغة لكنه غير قابل للاستخدام
أمثلة	غياب `ref`؛ وجود معرّفين؛ `electronic_payment_key` بطول 24 حرفاً؛ رقم هاتف محمول في `phoneNumber`	رقم حساب لا يتعرف عليه مُصدِر الفاتورة
خطأ من	خطأ تكاملك أنت	خطأ في كتابة عميلك
إظهاره للعميل	لا — سجّله فقط	نعم — “تحقق من الرقم المدوَّن على فاتورتك”
إعادة المحاولة دون تغيير	أبداً	فقط بعد أن يصحح العميل الرقم

لا تعرض رسائل ERR_VALIDATION على العملاء النهائيين. فهي تذكر أسماء حقول داخلية مثل electronic_payment_key، وهو ما لا يعني شيئاً لشخص يمسك بفاتورة ورقية.

تخزين خريطة الشركاء في الكاش

يتغير التوفر نادراً، لذا حدّثه على فترات زمنية بدلاً من تحديثه قبل كل استكشاف — واستمر في تقديم آخر نسخة صالحة إذا فشل التحديث. فقائمة مُصدِري فواتير فارغة أسوأ لعملائك من قائمة قديمة قليلاً.

let cache = { map: null, fetchedAt: 0 };
const TTL_MS = 5 * 60 * 1000;

async function getPartners() {
  if (cache.map && Date.now() - cache.fetchedAt < TTL_MS) return cache.map;

  try {
    const response = await fetch("https://billapi.oneclickdz.com/v3/partners", {
      headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
    });

    const body = await response.json();
    if (body.success) cache = { map: body.data, fetchedAt: Date.now() };
  } catch {
    // Serve the previous map rather than blocking the customer.
  }

  return cache.map ?? {};
}

التخزين في الكاش لا يُغني عن معالجة 503 PARTNER_UNAVAILABLE عند الاستكشاف. فقد يتعطل مُصدِر فاتورة بين آخر تحديث لك وضغط العميل على الزر.

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

تحقق قبل أن ترسل

تحقق من قاعدة الخانة الواحدة ومن صيغة الهاتف الثابت في جانب العميل. فذلك يوفّر رحلة ذهاب وإياب ويعطي رسالة خطأ أفضل.

خزّن الخريطة في الكاش لدقائق، لا لساعات

خمس دقائق كافية تماماً. حدّثها في الخلفية، لا على المسار الحرج للعميل أبداً.

أبقِ مُصدِري الفواتير غير المتاحين في كودك

سيعود SEAAL وAADL. اجعل واجهتك تُقاد من الخريطة، لا من قائمة مرمّزة بشكل ثابت.

فرّق بين خطأي 400

INVALID_ACCOUNT رسالة موجهة لعميلك. أما ERR_VALIDATION فرسالة موجهة لسجلاتك.

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

الخطوة 2: استكشاف الفواتير

أرسل استكشافاً، وتابعه حتى READY، واقرأ ما هو قابل للدفع

صفحات ذات صلة

سرد الشركاء

مرجع الـ endpoint

استكشاف الفواتير

حيث يُرسَل كائن الحساب

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

خريطة الخطوات الخمس

اختبار Sandbox

معرّفات تُنتج نتيجة تختارها

​نظرة عامة

​التحقق من التوفر

​المعرّف الخاص بكل مُصدِر فاتورة

​أرقام الهاتف الثابت

​صيغ المعرّف الأكثر تفصيلاً

​معرّف واحد بالضبط

​ERR_VALIDATION أم INVALID_ACCOUNT؟

​تخزين خريطة الشركاء في الكاش

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

تحقق قبل أن ترسل

خزّن الخريطة في الكاش لدقائق، لا لساعات

أبقِ مُصدِري الفواتير غير المتاحين في كودك

فرّق بين خطأي 400

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

الخطوة 2: استكشاف الفواتير

​صفحات ذات صلة

سرد الشركاء

استكشاف الفواتير

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

اختبار Sandbox

نظرة عامة

التحقق من التوفر

المعرّف الخاص بكل مُصدِر فاتورة

أرقام الهاتف الثابت

صيغ المعرّف الأكثر تفصيلاً

معرّف واحد بالضبط

`ERR_VALIDATION` أم `INVALID_ACCOUNT`؟

تخزين خريطة الشركاء في الكاش

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

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

صفحات ذات صلة