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

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

curl --request POST \
  --url https://billapi.oneclickdz.com/v3/bills/discover \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'POST', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://billapi.oneclickdz.com/v3/bills/discover', 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/discover",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  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/discover"

	req, _ := http.NewRequest("POST", 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/discover")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

POST

bills

discover

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

curl --request POST \
  --url https://billapi.oneclickdz.com/v3/bills/discover \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'POST', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://billapi.oneclickdz.com/v3/bills/discover', 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/discover",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  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/discover"

	req, _ := http.NewRequest("POST", 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/discover")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

نظرة عامة

يسأل مُصدِر الفواتير عن المبالغ المستحقة حاليًا على حساب معيّن. الاستجابة هي transactionId تستعلم عنه دوريًا بعد ذلك؛ وعندما تبلغ المعاملة الحالة READY، تحتوي مصفوفة bills[] الخاصة بها على كل ما هو قابل للدفع.

200 إقرار بالاستلام، وليس نتيجة. فهو يعني أن الطلب قُبِل وأن معاملة أُنشئت. الفواتير تصل لاحقًا، داخل المعاملة. لا تعتبر هذه الاستجابة أبدًا بمعنى «لا يترتب على الحساب أي مبلغ».

الاكتشاف لا يحرّك أي أموال ولا يُلزمك بشيء. من الآمن تشغيله قبل أن تعرض على العميل ما هو مستحق عليه.

متن الطلب

string

مطلوب

مُصدِر الفواتير المطلوب الاستعلام عنه. قيمة واحدة بالضبط من ADE، SONELGAZ، SEAAL، AADL، Algérie Télécom — مع الحفاظ على العلامات (accents) كما هي.راجع قائمة الشركاء أولًا؛ الشريك الذي حالته UNAVAILABLE يُجيب بـ 503 PARTNER_UNAVAILABLE.

object

مطلوب

الحساب المطلوب البحث عنه. يجب أن يحمل معرّفًا واحدًا بالضبط — راجع معرّفات الحساب أدناه. عدم إرسال أي معرّف، أو إرسال معرّفين، مرفوض.

string

مطلوب

مرجعك الخاص لعملية الاكتشاف هذه. 100 حرف كحد أقصى، وفريد بين معاملاتك النشطة لدى هذا الشريك.إعادة استخدام ref تُجيب بـ 403 DUPLICATED_REF. وهو أيضًا الطريقة التي تستعيد بها استجابة ضائعة — راجع الحصول على المعاملة بالمرجع.

معرّفات الحساب

أرسل الحقل الذي يخص الشريك الذي تستعلم عنه. وهو أيضًا الحقل الذي تُرجعه واجهة API في account في كل معاملة لهذا الشريك.

الشريك	الحقل	ملاحظات
`ADE`	`reference`	مرجع العميل، حتى 50 حرفًا
`SEAAL`	`reference`	مرجع العميل، حتى 50 حرفًا
`SONELGAZ`	`contractNumber`	رقم العقد، حتى 50 حرفًا
`AADL`	`aadlNumber`	رقم الملف السكني، حتى 50 حرفًا
`Algérie Télécom`	`phoneNumber`	خط هاتف ثابت جزائري، `0` أو `+213` متبوعًا برقم من 2 إلى 4 ثم 7 أرقام أخرى

تُقبَل أيضًا صيغتان أكثر تفصيلًا حين يحتاج مُصدِر الفواتير إلى أكثر من رقم واحد لتحديد الفاتورة:

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 أحرف بالضبط.

electronic_payment_key — مفتاح من 25 حرفًا

مقبول لدى ADE وSEAAL كبديل عن reference. يجب أن يكون من 25 حرفًا بالضبط.

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

معرّف واحد بالضبط. تُحسب reference وcontractNumber وaadlNumber وelectronic_payment_key ضمن الخانة نفسها، وكذلك phoneNumber وphone_number؛ أما sonelgaz وade فلكل منهما خانته الخاصة. عدم إرسال أي منها، أو إرسال اثنين، مرفوض بـ 400.

الاستجابة

boolean

مطلوب

true عندما يُقبَل الاكتشاف.

object

مطلوب

إظهار properties

string

مطلوب

المعاملة المطلوب الاستعلام عنها دوريًا. سلسلة سداسية عشرية من 24 حرفًا بأحرف صغيرة.

string

مطلوب

قيمة ref التي أرسلتها، مُعادة إليك.

string

مطلوب

دائمًا PENDING عند هذه النقطة.

object

مطلوب

إظهار properties

string

مطلوب

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

string

مطلوب

معرّف الربط، يُرسل أيضًا في ترويسة الاستجابة X-Request-Id.

الأمثلة

curl https://billapi.oneclickdz.com/v3/bills/discover \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: YOUR_API_KEY" \
  -d '{
    "partner": "ADE",
    "account": { "reference": "0123456789012345678901234" },
    "ref": "disc-inv-2026-0042"
  }'

const response = await fetch(
  "https://billapi.oneclickdz.com/v3/bills/discover",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
    },
    body: JSON.stringify({
      partner: "ADE",
      account: { reference: "0123456789012345678901234" },
      ref: "disc-inv-2026-0042",
    }),
  },
);

const body = await response.json();

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

// Accepted — the bills are not here yet. Poll this id until READY.
console.log(body.data.transactionId);

import os
import requests

response = requests.post(
    'https://billapi.oneclickdz.com/v3/bills/discover',
    headers={
        'Content-Type': 'application/json',
        'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')
    },
    json={
        'partner': 'ADE',
        'account': {'reference': '0123456789012345678901234'},
        'ref': 'disc-inv-2026-0042'
    }
)

body = response.json()

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

# Accepted — the bills are not here yet. Poll this id until READY.
print(body['data']['transactionId'])

<?php
$payload = [
    'partner' => 'ADE',
    'account' => ['reference' => '0123456789012345678901234'],
    'ref'     => 'disc-inv-2026-0042'
];

$ch = curl_init('https://billapi.oneclickdz.com/v3/bills/discover');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

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

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

// Accepted — the bills are not here yet. Poll this id until READY.
echo $body['data']['transactionId'];
?>

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

{
  "success": true,
  "data": {
    "transactionId": "68b2f4c1a7d3e9f204c81a55",
    "ref": "disc-inv-2026-0042",
    "status": "PENDING"
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:32.194Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

استعلم دوريًا عن الحصول على المعاملة بالمعرّف حتى تصبح status هي READY، ثم اقرأ bills[]:

{
  "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"
}

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

400 — خطأ في التحقق

متن الطلب لم يطابق المخطط.

{
  "success": false,
  "error": {
    "code": "ERR_VALIDATION",
    "message": "ref is required",
    "details": ["ref is required"]
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

يسرد details كل حقل فشل، وليس الأول فقط. الأسباب الشائعة: غياب ref، أو partner ليست إحدى القيم الخمس، أو account بلا معرّف أو بمعرّفين، أو electronic_payment_key ليس من 25 حرفًا بالضبط، أو phoneNumber ليس خط هاتف ثابت جزائري صالح.ما العمل: صحّح الطلب. إعادة إرساله دون تغيير تُرجع الخطأ نفسه.

400 — حساب غير صالح

المعرّف مقبول من حيث البنية لكنه غير قابل للاستخدام مع هذا الشريك.

{
  "success": false,
  "error": {
    "code": "INVALID_ACCOUNT",
    "message": "The provided account identifier is invalid."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: اطلب من العميل التحقق من الرقم المدوّن على فاتورته. هذا هو الخطأ الذي تعرضه له؛ أما ERR_VALIDATION فهو لسجلاتك.

401 — رمز وصول مفقود أو غير صالح

المفتاح غائب أو مرفوض.

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

غياب الترويسة يُرجع MISSING_ACCESS_TOKEN بدلًا من ذلك، بنفس حالة HTTP.ما العمل: تحقق من المفتاح عبر التحقق من مفتاح API.

403 — مرجع مكرر

سبق أن استخدمت هذا ref مع هذا الشريك.

{
  "success": false,
  "error": {
    "code": "DUPLICATED_REF",
    "message": "A transaction with this ref already exists for this partner."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: لا تعد المحاولة بمرجع ref جديد بشكل أعمى — فستبدأ عملية اكتشاف ثانية للحساب نفسه. ابحث عن العملية الموجودة عبر الحصول على المعاملة بالمرجع وتابع من حالتها.

409 — الفاتورة مدفوعة مسبقًا

هذا الحساب سُدِّد مؤخرًا بالفعل، لذا رُفض اكتشاف جديد.

{
  "success": false,
  "error": {
    "code": "BILL_ALREADY_PAID",
    "message": "This bill has already been paid."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: هذا حارس ضد الدفع المزدوج، وليس فشلًا. ابحث عن المعاملة الناجحة في قائمة المعاملات واعرض على العميل ذلك الإيصال.

409 — دفعة قيد التنفيذ

دفعة أخرى لهذا الحساب لم تنتهِ بعد.

{
  "success": false,
  "error": {
    "code": "PAYMENT_IN_PROGRESS",
    "message": "A payment for this account is currently in progress."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: انتظر حتى تبلغ تلك الدفعة حالة نهائية، ثم ابدأ من جديد. لا تُشغّل الاثنتين بالتوازي.

503 — الشريك غير متاح

تعذّر الوصول إلى مُصدِر الفواتير، أو أنه موقوف حاليًا.

{
  "success": false,
  "error": {
    "code": "PARTNER_UNAVAILABLE",
    "message": "Partner temporarily unavailable — please try again later."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: حدّث قائمة الشركاء وأعد المحاولة لاحقًا. لم تُنشأ أي معاملة ولم يُخصم أي مبلغ. هذه الاستجابة لا تحمل Retry-After؛ طبّق التراجع التدريجي من جانبك.

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

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

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

ما العمل: انتظر مدة Retry-After (5 ثوانٍ) وأعد إرسال الطلب نفسه بالمرجع ref نفسه.

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

واجهة Bill Payment API في صيانة مُخطط لها.

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

ما العمل: التزم بـ Retry-After وأعد المحاولة بالمرجع ref نفسه.

500 — خطأ داخلي

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

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

ما العمل: تحقق مما إذا كان الاكتشاف قد أُنشئ عبر الحصول على المعاملة بالمرجع قبل إعادة المحاولة، وأرسل requestId إلى الدعم إذا استمرت المشكلة.

حدّ الـ 200 دينار جزائري في الاكتشاف

تُستبعَد الفواتير التي تقل عن 200 دينار جزائري أثناء الاكتشاف ولا تظهر أبدًا في bills[].لذلك فإن معاملة بحالة READY مع bills[] فارغة تعني أحد أمرين، وواجهة API لا تفرّق بينهما:

لا يترتب على الحساب أي مبلغ، أو
كل ما يترتب عليه يقل عن حدّ الـ 200 دينار جزائري.

صُغ هذا بعناية لعملائك. عبارة «لا توجد فواتير قابلة للدفع حاليًا» دقيقة؛ أما «لا يترتب عليك أي مبلغ» فليست كذلك.

منع الطلبات المكررة

يجعل ref عملية الاكتشاف آمنة لإعادة المحاولة. إذا حجب خطأ في الشبكة الاستجابة، فابحث عن ref بدلًا من إرسال اكتشاف ثانٍ.

async function discoverSafely(partner, account, ref) {
  try {
    const response = await fetch(
      "https://billapi.oneclickdz.com/v3/bills/discover",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
        },
        body: JSON.stringify({ partner, account, ref }),
      },
    );

    const body = await response.json();

    if (body.success) {
      return body.data.transactionId;
    }

    // Already started earlier — recover it instead of starting a second one.
    if (body.error.code === "DUPLICATED_REF") {
      return await findByRef(ref, partner);
    }

    throw new Error(`${body.error.code}: ${body.error.message}`);
  } catch (networkError) {
    // The request may still have been accepted. Check before retrying.
    const existing = await findByRef(ref, partner).catch(() => null);
    if (existing) return existing;
    throw networkError;
  }
}

async function findByRef(ref, partner) {
  const url = new URL(
    "https://billapi.oneclickdz.com/v3/bills/transactions/by-ref",
  );
  url.searchParams.set("ref", ref);
  url.searchParams.set("partner", partner);

  const response = await fetch(url, {
    headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
  });

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

المرجع ref الجيد مُشتق من شيء تخزّنه أصلًا — معرّف فاتورتك أو طلبك — حتى تتمكن دائمًا من إعادة بنائه. راجع اكتشاف الفواتير للاطلاع على طريقة للتسمية.

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

PENDING

الاستجابة التي تلقيتها للتو. الاكتشاف في قائمة الانتظار وقيد التنفيذ.

READY

انتهى الاكتشاف. bills[] موجودة — وقد تكون فارغة. اختر billId واستدعِ دفع فاتورة.

FAILED

لم يتمكن الاكتشاف من الاكتمال. يوضّح error.code السبب: INVALID_ACCOUNT أو PARTNER_UNAVAILABLE أو BILL_ALREADY_PAID أو PAYMENT_DECLINED.

مرجع الحالات الكامل →

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

تحقق من الشريك أولًا

خريطة شركاء مخزّنة مؤقتًا تتيح لك إخفاء مُصدِر فواتير غير متاح قبل أن يُدخل العميل رقم حسابه.

اشتقّ المرجع، لا تخترعه

ابنِ ref من معرّف طلبك الخاص حتى تتمكن دائمًا من البحث عن المعاملة مجددًا.

لا تفترض أبدًا أن 200 تعني فارغًا

الفواتير تصل في المعاملة، لا في هذه الاستجابة. استعلم دوريًا قبل أن تخبر العميل بأي شيء.

اقرأ fee من الاستجابة

كل فاتورة تحمل fee الخاص بها. لا تُعِد حسابه في كودك.

Endpoints ذات الصلة

قائمة الشركاء

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

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

استعلم دوريًا عن الفواتير

دفع فاتورة

ادفع إحداها

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

استعد استجابة ضائعة

الشرح الكامل

الشركاء والحسابات

قواعد المعرّفات لكل شريك

مرجع API

Core

الحساب

شحن الهاتف

شحن الإنترنت

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

Navio

دفع الفواتير

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

نظرة عامة

متن الطلب

معرّفات الحساب

الاستجابة

الأمثلة

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

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

حدّ الـ 200 دينار جزائري في الاكتشاف

منع الطلبات المكررة

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

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

تحقق من الشريك أولًا

اشتقّ المرجع، لا تخترعه

لا تفترض أبدًا أن 200 تعني فارغًا

اقرأ fee من الاستجابة

Endpoints ذات الصلة

قائمة الشركاء

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

دفع فاتورة

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