الحصول على المعاملة بالمعرّف

curl --request GET \
  --url https://billapi.oneclickdz.com/v3/bills/transactions/{transactionId} \
  --header 'X-Access-Token: <api-key>'

import requests

url = "https://billapi.oneclickdz.com/v3/bills/transactions/{transactionId}"

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://billapi.oneclickdz.com/v3/bills/transactions/{transactionId}', 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://billapi.oneclickdz.com/v3/bills/transactions/{transactionId}",
  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://billapi.oneclickdz.com/v3/bills/transactions/{transactionId}"

	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))

}

require 'uri'
require 'net/http'

url = URI("https://billapi.oneclickdz.com/v3/bills/transactions/{transactionId}")

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

bills

transactions

{transactionId}

الحصول على المعاملة بالمعرّف

curl --request GET \
  --url https://billapi.oneclickdz.com/v3/bills/transactions/{transactionId} \
  --header 'X-Access-Token: <api-key>'

import requests

url = "https://billapi.oneclickdz.com/v3/bills/transactions/{transactionId}"

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://billapi.oneclickdz.com/v3/bills/transactions/{transactionId}', 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://billapi.oneclickdz.com/v3/bills/transactions/{transactionId}",
  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://billapi.oneclickdz.com/v3/bills/transactions/{transactionId}"

	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))

}

require 'uri'
require 'net/http'

url = URI("https://billapi.oneclickdz.com/v3/bills/transactions/{transactionId}")

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

نظرة عامة

يُرجع كائن المعاملة الكامل — العرض المرجعي لعملية اكتشاف أو دفع في خدمة دفع الفواتير. كل endpoint أخرى في خدمة دفع الفواتير إما تُرجع هذا الكائن نفسه أو تُرجع معرّفًا يشير إليه.ولأن الاكتشاف والدفع غير متزامنين، فإن هذه الـ endpoint هي المكان الذي تظهر فيه النتيجة الحقيقية. أما الاستجابة 200 التي تلقيتها من discover أو pay فقد أكّدت فقط أن الطلب قُبِل.

المعاملة التي تعود إلى شريك آخر تُرجع 404، لا 403. لا تؤكد واجهة API أبدًا وجود معاملة تخص غيرك. وينطبق الأمر نفسه عبر البيئات: مفتاح Sandbox لا يمكنه قراءة معاملة إنتاج، والعكس صحيح.

معاملات المسار

string

مطلوب

معرّف المعاملة الذي أرجعه اكتشاف الفواتير أو دفع فاتورة.سلسلة سداسية عشرية من 24 حرفًا بأحرف صغيرة، مثلًا 68b2f4c1a7d3e9f204c81a55.

الاستجابة

boolean

مطلوب

true عند العثور على المعاملة وإرجاعها.

object

مطلوب

كائن المعاملة.

إظهار properties

string

مطلوب

معرّف المعاملة. موجود دائمًا.

string

مطلوب

مرجع الإتقانية (idempotency) الذي قدّمته عند بدء عملية الاكتشاف. وهذه هي القيمة التي يبحث عنها الحصول على المعاملة بالمرجع.

string

مطلوب

discovery ما دامت المعاملة قد بحثت عن الفواتير فقط، وpayment بمجرد أن تقدّم دفعة مقابلها.

string

مطلوب

إحدى القيم PENDING، READY، PROCESSING، SUCCESS، FAILED، REFUNDED، UNKNOWN. راجع دورة حياة الحالة.

string

مطلوب

إحدى القيم ADE، SONELGAZ، SEAAL، AADL، Algérie Télécom.

object

مطلوب

الحساب الذي تخصه المعاملة، مُفهرَسًا بحقل المعرّف الخاص بذلك الشريك: reference لـ ADE وSEAAL، وcontractNumber لـ SONELGAZ، وaadlNumber لـ AADL، وphoneNumber لـ Algérie Télécom.

string

مطلوب

دائمًا DZD.

string

مطلوب

وقت إنشاء المعاملة، ISO 8601 بتوقيت UTC.

string

مطلوب

وقت آخر تغيير على المعاملة، ISO 8601 بتوقيت UTC.

string | null

مطلوب

وقت توقف المعاملة عن العمل. null ما دامت قيد التنفيذ. تفرّع بناءً على status، لا على هذا الحقل أبدًا.

array

موجود فقط عندما تكون status هي READY. الفواتير المستحقة والقابلة للدفع. المصفوفة الفارغة تعني أنه لا يوجد ما يُدفع.

إظهار bill properties

string

مطلوب

المعرّف الذي تُرسله إلى دفع فاتورة.

number

مطلوب

المبلغ المستحق للشريك، بالدينار الجزائري، بمنزلتين عشريتين.

number

مطلوب

رسوم خدمة OneClickDz مقابل دفع هذه الفاتورة، بالدينار الجزائري، بمنزلتين عشريتين. اقرأها من الاستجابة — ولا تُعِد حسابها أبدًا.

string

وصف مقروء للبشر، حين يقدّمه الشريك.

string

فترة الفوترة، حين يقدّمها الشريك.

object

موجود بمجرد اختيار فاتورة للدفع. له بنية عنصر bills[] نفسها، وهو الفاتورة التي خُصم مبلغها فعليًا.

number

موجود مع selectedBill. amount + fee — المبلغ الذي يُخصم من رصيدك.

string

موجود فقط عندما تكون status هي SUCCESS. الرابط المطلق لـتنزيل الإيصال.

string

موجود فقط عندما تكون status هي SUCCESS. مرجع إثبات الدفع لدى الشريك. احفظه — فهو ما يُحسم به نزاع العميل.

object

موجود فقط عندما تكون status هي FAILED أو REFUNDED.

إظهار properties

string

مطلوب

إحدى القيم PAYMENT_DECLINED، PARTNER_UNAVAILABLE، INVALID_ACCOUNT، BILL_ALREADY_PAID.

string

مطلوب

شرح موجز، آمن للتسجيل في السجلات. لا تحلّله نصيًا — تفرّع بناءً على code.

object

مطلوب

إظهار properties

string

مطلوب

وقت الاستجابة، ISO 8601 بتوقيت UTC.

string

مطلوب

معرّف الربط، يُرسل أيضًا في ترويسة الاستجابة X-Request-Id. سجّله — فهو الشيء الوحيد الذي يحتاجه الدعم لتتبع طلب.

الأمثلة

curl https://billapi.oneclickdz.com/v3/bills/transactions/68b2f4c1a7d3e9f204c81a55 \
  -H "X-Access-Token: YOUR_API_KEY"

const transactionId = "68b2f4c1a7d3e9f204c81a55";

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

const body = await response.json();

if (!body.success) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

console.log(body.data.status);

import os
import requests

transaction_id = '68b2f4c1a7d3e9f204c81a55'

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

body = response.json()

if not body['success']:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

print(body['data']['status'])

<?php
$transactionId = '68b2f4c1a7d3e9f204c81a55';

$ch = curl_init("https://billapi.oneclickdz.com/v3/bills/transactions/$transactionId");
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'] . ': ' . $body['error']['message']);
}

echo $body['data']['status'];
?>

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

دفعة مكتملة:

{
  "success": true,
  "data": {
    "transactionId": "68b2f4c1a7d3e9f204c81a55",
    "ref": "disc-inv-2026-0042",
    "type": "payment",
    "status": "SUCCESS",
    "partner": "ADE",
    "account": {
      "reference": "0123456789012345678901234"
    },
    "selectedBill": {
      "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
      "amount": 443.39,
      "fee": 30.00,
      "label": "Facture ADE"
    },
    "total": 473.39,
    "currency": "DZD",
    "receiptUrl": "https://billapi.oneclickdz.com/v3/bills/transactions/68b2f4c1a7d3e9f204c81a55/receipt",
    "operationId": "op_7726351904",
    "createdAt": "2026-08-31T10:15:32.194Z",
    "updatedAt": "2026-08-31T10:15:41.902Z",
    "completedAt": "2026-08-31T10:15:41.902Z"
  },
  "meta": {
    "timestamp": "2026-08-31T10:16:03.771Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

عملية اكتشاف انتهت وعثرت على فاتورة واحدة قابلة للدفع:

{
  "success": true,
  "data": {
    "transactionId": "68b2f4c1a7d3e9f204c81a55",
    "ref": "disc-inv-2026-0042",
    "type": "discovery",
    "status": "READY",
    "partner": "ADE",
    "account": {
      "reference": "0123456789012345678901234"
    },
    "bills": [
      {
        "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
        "amount": 443.39,
        "fee": 30.00,
        "label": "Facture ADE"
      }
    ],
    "currency": "DZD",
    "createdAt": "2026-08-31T10:15:32.194Z",
    "updatedAt": "2026-08-31T10:15:33.008Z",
    "completedAt": "2026-08-31T10:15:33.008Z"
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:34.120Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

دفعة رُفضت واستُردّت بالكامل:

{
  "success": true,
  "data": {
    "transactionId": "68b2f4c1a7d3e9f204c81a55",
    "ref": "disc-inv-2026-0042",
    "type": "payment",
    "status": "REFUNDED",
    "partner": "ADE",
    "account": {
      "reference": "0123456789012340000000005"
    },
    "selectedBill": {
      "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
      "amount": 550.00,
      "fee": 30.00,
      "label": "Facture ADE"
    },
    "total": 580.00,
    "currency": "DZD",
    "error": {
      "code": "PAYMENT_DECLINED",
      "message": "The payment was declined by the bank or partner portal."
    },
    "createdAt": "2026-08-31T10:15:32.194Z",
    "updatedAt": "2026-08-31T10:15:44.310Z",
    "completedAt": "2026-08-31T10:15:44.310Z"
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:46.002Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

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

401 — رمز الوصول مفقود

لم تُرسَل ترويسة X-Access-Token.

{
  "success": false,
  "error": {
    "code": "MISSING_ACCESS_TOKEN",
    "message": "X-Access-Token header is required."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: أرسل مفتاح API الخاص بك في ترويسة X-Access-Token مع كل طلب.

401 — رمز وصول غير صالح

المفتاح مرفوض.

{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: تحقق من المفتاح. لا تعد المحاولة بالقيمة نفسها — فهذا لن يُحل من تلقاء نفسه.

404 — المعاملة غير موجودة

لا توجد معاملة بهذا المعرّف تعود إلى حسابك في هذه البيئة.

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Transaction not found."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: تأكّد من المعرّف، وتأكّد من أنك تستخدم مفتاح البيئة التي أُنشئت فيها المعاملة. المعرّف المشوّه يُجيب أيضًا بـ 404.

503 — المصادقة غير متاحة

لم نتمكن من التحقق من مفتاحك في الوقت المحدد. هذا ليس حكمًا على مفتاحك.

{
  "success": false,
  "error": {
    "code": "AUTH_UNAVAILABLE",
    "message": "Authentication is temporarily unavailable. Please retry shortly."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: انتظر عدد الثواني المذكور في ترويسة الاستجابة Retry-After، ثم أعد إرسال الطلب نفسه. لا تعرض هذا على عميلك أبدًا على أنه مشكلة في بيانات الاعتماد.

503 — الخدمة غير متاحة

واجهة Bill Payment API في صيانة مُخطط لها. كل مسار /v3 يُجيب بهذا.

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is temporarily unavailable. Please retry shortly."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: التزم بـ Retry-After وأعد المحاولة. عمليات القراءة آمنة للتكرار.

500 — خطأ داخلي

حدث خلل من جانبنا.

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: أعد محاولة القراءة. إذا استمرت المشكلة، تواصل مع الدعم مع ذكر requestId.

دورة حياة الحالة

تُنشأ المعاملة عبر discover، ثم تصبح قابلة للدفع، ثم تتابع الدفعة حتى تبلغ حالة نهائية.

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

UNKNOWN ليست فشلًا. لا تسترد المال لعميلك ولا تعد إرسال الدفعة أبدًا ما دامت المعاملة UNKNOWN — تابع الاستعلام الدوري. فهي تُحسم إلى SUCCESS أو REFUNDED.

استراتيجية الاستعلام الدوري الكاملة →

الحقول حسب الحالة

الحقول المؤشَّر عليها أدناه هي وحدها الموجودة. لا تفترض وجود حقل لمجرد أنك رأيته في حالة أخرى.

الحقل	`PENDING`	`READY`	`PROCESSING`	`SUCCESS`	`FAILED`	`REFUNDED`	`UNKNOWN`
`transactionId`، `ref`، `type`، `status`، `partner`، `account`، `currency`، `createdAt`، `updatedAt`	نعم	نعم	نعم	نعم	نعم	نعم	نعم
`completedAt`	`null`	مُعيَّن	`null`	مُعيَّن	مُعيَّن	مُعيَّن	مُعيَّن
`bills`	—	نعم	—	—	—	—	—
`selectedBill`، `total`	—	—	نعم	نعم	نعم	نعم	نعم
`receiptUrl`، `operationId`	—	—	—	نعم	—	—	—
`error`	—	—	—	—	نعم	نعم	—

يظهر selectedBill وtotal منذ لحظة اختيار فاتورة للدفع، ولذلك فهما غائبان عن عملية اكتشاف لم يُدفع مقابلها قط.

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

تفرّع بناءً على status

تعامل مع status بوصفها المصدر الوحيد للحقيقة بشأن النتيجة. لا تستنتجها أبدًا من completedAt ولا من حالة HTTP للطلب الأصلي.

احفظ operationId

عند SUCCESS، احفظ operationId ونزّل الإيصال. فهما معًا الإثبات الذي يحتاجه نزاع العميل.

سجّل كل requestId

احتفظ بـ requestId بجانب معرّف طلبك الخاص. فهو أسرع طريق للحصول على إجابة من الدعم.

استعلم دوريًا، لا تعد الإرسال

المعاملة البطيئة ليست معاملة ضائعة. استعلم دوريًا عن هذه الـ endpoint بدلًا من إعادة إرسال الاكتشاف أو الدفعة.

Endpoints ذات الصلة

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

ابدأ عملية اكتشاف

دفع فاتورة

ادفع فاتورة مكتشَفة

الحصول على المعاملة بالمرجع

ابحث بمرجعك ref الخاص

قائمة المعاملات

صفِّ السجل وتصفّحه

تنزيل الإيصال

احصل على إثبات الدفع

دليل الاستعلام الدوري عن الحالة

مُستعلِم دوري بجودة الإنتاج

مرجع API

Core

الحساب

شحن الهاتف

شحن الإنترنت

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

Navio

دفع الفواتير

الحصول على المعاملة بالمعرّف

نظرة عامة

معاملات المسار

الاستجابة

الأمثلة

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

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

دورة حياة الحالة

الحقول حسب الحالة

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

تفرّع بناءً على status

احفظ operationId

سجّل كل requestId

استعلم دوريًا، لا تعد الإرسال

Endpoints ذات الصلة

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

دفع فاتورة

الحصول على المعاملة بالمرجع

قائمة المعاملات

تنزيل الإيصال

دليل الاستعلام الدوري عن الحالة

​نظرة عامة

​معاملات المسار

​الاستجابة

​الأمثلة

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

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

​دورة حياة الحالة

​الحقول حسب الحالة

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

تفرّع بناءً على status

احفظ operationId

سجّل كل requestId

استعلم دوريًا، لا تعد الإرسال

​Endpoints ذات الصلة

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

دفع فاتورة

الحصول على المعاملة بالمرجع

قائمة المعاملات

تنزيل الإيصال

دليل الاستعلام الدوري عن الحالة

نظرة عامة

معاملات المسار

الاستجابة

الأمثلة

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

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

دورة حياة الحالة

الحقول حسب الحالة

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

Endpoints ذات الصلة