حالة المعاملة - OneClickDz Flexy API

كائن واحد لدورة الحياة كاملة

الاكتشاف والدفعة المنفّذة انطلاقًا منه هما المعاملة نفسها، بقيمة transactionId نفسها وref نفسه. تكون قيمة type هي discovery إلى أن تُقبل دفعة، ثم تصبح payment.اقرأها باستخدام GET /v3/bills/transactions/{transactionId} أو GET /v3/bills/transactions/by-ref?ref=….

الحالات

الحالة	المرحلة	المعنى	نهائية
`PENDING`	الاكتشاف	الاكتشاف قيد التنفيذ	لا
`READY`	الاكتشاف	`bills[]` متاحة؛ في انتظار `pay`	لا
`FAILED`	الاكتشاف	تعذّر إتمام الاكتشاف؛ راجع `error`	نعم
`PROCESSING`	الدفع	الدفع قيد التنفيذ	لا
`UNKNOWN`	الدفع	لم تُؤكَّد النتيجة بعد	لا
`SUCCESS`	الدفع	تم الدفع؛ `receiptUrl` و`operationId` متاحان	نعم
`FAILED`	الدفع	لم تُدفع؛ لم يُخصم أي مبلغ	نعم
`REFUNDED`	الدفع	خُصم المبلغ ثم استُرد بالكامل؛ راجع `error`	نعم

الحقول

موجودة دائمًا:

الحقل	النوع	الوصف
`transactionId`	string	معرّف المعاملة
`ref`	string	قيمة `ref` الاكتشاف الخاصة بك
`type`	string	`discovery` أو `payment`
`status`	string	إحدى الحالات المذكورة أعلاه
`partner`	string	اسم مُصدِر الفاتورة
`account`	object	المعرّف، مُعادًا ضمن مفتاح خاص بكل شريك
`currency`	string	دائمًا `DZD`
`createdAt`	string	ISO 8601
`updatedAt`	string	ISO 8601، آخر تغيير
`completedAt`	string \| null	`null` ما دامت المعاملة جارية. تُضبط عند انتهاء الاكتشاف، وعند انتقال الدفعة إلى `UNKNOWN` أو `SUCCESS` أو `FAILED`، وعند اكتمال الاسترداد.

موجودة حسب الحالة:

الحقل	موجود عندما	الوصف
`bills[]`	`READY`	الفواتير غير المدفوعة؛ مصفوفة فارغة عندما لا يكون هناك شيء مستحق
`selectedBill`	بعد `pay`	الفاتورة قيد الدفع. في الطلب متعدد الفواتير: `amount` هو المبلغ المجمّع، و`billId` هو المعرّف الأول
`selectedBills[]`	بعد `pay`، للطلب متعدد الفواتير فقط	كل فاتورة من فواتير الطلب
`total`	بعد `pay`	`selectedBill.amount + selectedBill.fee`، وهو المبلغ المخصوم من رصيدك
`receiptUrl`	`SUCCESS`	عنوان URL الكامل لتنزيل الإيصال
`operationId`	`SUCCESS`	مرجع العملية لدى مُصدِر الفاتورة أو بوابة الدفع
`error`	`FAILED`، `REFUNDED`	`{ code, message }`

اعتمد في التفرّع على status، ولا تعتمد أبدًا على وجود حقل ما.

`error.code`

الرمز	المعنى
`PAYMENT_DECLINED`	رفض البنك أو بوابة مُصدِر الفاتورة الدفعة
`PARTNER_UNAVAILABLE`	لم تستجب بوابة مُصدِر الفاتورة
`INVALID_ACCOUNT`	لا يتعرّف مُصدِر الفاتورة على المعرّف
`BILL_ALREADY_PAID`	يُفيد مُصدِر الفاتورة بأن الفاتورة مسدّدة مسبقًا

استطلاع الحالة

المرحلة	الفاصل الزمني	التوقّف عندما	المدة المعتادة
الاكتشاف	2–3 s	`status` ≠ `PENDING`	ثوانٍ؛ بضع دقائق عند ارتفاع الضغط
الدفع	5 s	`status` هي `SUCCESS` أو `FAILED` أو `REFUNDED`	أقل من بضع دقائق
`UNKNOWN`	60 s	`status` هي `SUCCESS` أو `REFUNDED`	دقائق عادةً؛ وأطول عند الحاجة إلى مراجعة يدوية

Node.js

const FINAL = new Set(["SUCCESS", "FAILED", "REFUNDED"]);

async function waitForPayment(transactionId) {
  for (;;) {
    const res = await fetch(`https://api.oneclickdz.com/v3/bills/transactions/${transactionId}`, {
      headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
    });
    const body = await res.json();
    if (!body.success) throw new Error(body.error.code);

    const txn = body.data;
    if (FINAL.has(txn.status)) return txn;

    const delay = txn.status === "UNKNOWN" ? 60_000 : 5_000;
    await new Promise((r) => setTimeout(r, delay));
  }
}

UNKNOWN

تعني UNKNOWN أن الدفعة أُرسلت إلى مُصدِر الفاتورة لكن النتيجة لم تُؤكَّد. قد تكون الأموال قد نُقلت وقد لا تكون. وتنتهي دائمًا إلى SUCCESS أو REFUNDED.ما دامت المعاملة بالحالة UNKNOWN:

لا تبدأ دفعة جديدة للفاتورة نفسها.
لا تردّ المبلغ لعميلك ولا تُضِفه إلى رصيده.
أبلغ العميل بأن الدفعة قيد التأكيد.

الاستدراك بعد انتهاء المهلة

إذا انتهت مهلة discover أو pay من جهتك، فربما يكون الطلب قد عولج رغم ذلك.

GET /v3/bills/transactions/by-ref?ref=<your discovery ref>.
404 NOT_FOUND: لم يُنشأ الاكتشاف قط. أرسله مجددًا بقيمة ref نفسها.
أي نتيجة أخرى: المعاملة موجودة. تابع انطلاقًا من status الخاصة بها.

في حالة انتهاء مهلة pay، اقرأ المعاملة بواسطة المعرّف: تعني PROCESSING أو ما بعدها أن الدفعة قُبلت.

التالي: الإيصالات والمطابقة

تنزيل الإيصالات ومطابقة سجلك

​كائن واحد لدورة الحياة كاملة

​الحالات

​الحقول

​error.code

​استطلاع الحالة

​UNKNOWN

​الاستدراك بعد انتهاء المهلة