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

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

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

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

fetch('https://api.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://api.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://api.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://api.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://api.oneclickdz.com/v3/bills/discover \
  --header 'X-Access-Token: <api-key>'

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

fetch('https://api.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://api.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://api.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://api.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 فورًا. تصل الفواتير إلى المعاملة بعد بضع ثوانٍ: استطلع حالة الحصول على المعاملة بالمعرّف إلى أن تصبح قيمة status هي READY.

جسم الطلب

string

مطلوب

أحد الأسماء ADE أو SONELGAZ أو SEAAL أو AADL أو SEOR أو Algérie Télécom (بالكتابة الدقيقة، مع علامات النبر).

object

مطلوب

معرّف واحد بالضبط، بالصيغة التي يتوقّعها الشريك:

الشريك	`account`
`ADE`	`{ "electronic_payment_key": string }` — 25 حرفًا
`SONELGAZ`	`{ "sonelgaz": { "invoice_number": string, "amount_without_stamp": string, "ebb_key": string } }`
`SEAAL`	`{ "seaal": { "code_client": string, "code_contrat": string } }` — من 2 إلى 6 أحرف أبجدية رقمية، ومن 2 إلى 10 أرقام
`AADL`	`{ "aadl": { "codeloc": string } }` — من 6 إلى 20 رقمًا
`SEOR`	`{ "seor": { "contrat": string, "facture": string } }` — من 1 إلى 6 أرقام (تُتجاهل المسافات)، و18 حرفًا أو رقمًا
`Algérie Télécom`	`{ "phone_number": string }` — هاتف ثابت، `0[2-4]` ثم 7 أرقام

القواعد الكاملة والأمثلة: الشركاء والحسابات.

string

مطلوب

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

الاستجابة

object

مطلوب

إظهار الخصائص

string

مطلوب

معرّف المعاملة الجديدة. استخدمه لاستطلاع الحالة وللدفع.

string

مطلوب

قيمة ref التي أرسلتها.

string

مطلوب

دائمًا PENDING هنا.

مثال

curl -X POST https://api.oneclickdz.com/v3/bills/discover \
  -H "X-Access-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partner": "SEAAL",
    "account": { "seaal": { "code_client": "100001", "code_contrat": "446563" } },
    "ref": "disc-20260920-0003"
  }'

const response = await fetch("https://api.oneclickdz.com/v3/bills/discover", {
  method: "POST",
  headers: {
    "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    partner: "SEAAL",
    account: { seaal: { code_client: "100001", code_contrat: "446563" } },
    ref: "disc-20260920-0003",
  }),
});
const body = await response.json();
if (!body.success) throw new Error(`${body.error.code}: ${body.error.message}`);

const { transactionId } = body.data;

import os, requests

response = requests.post(
    "https://api.oneclickdz.com/v3/bills/discover",
    headers={"X-Access-Token": os.environ["ONECLICKDZ_API_KEY"]},
    json={
        "partner": "SEAAL",
        "account": {"seaal": {"code_client": "100001", "code_contrat": "446563"}},
        "ref": "disc-20260920-0003",
    },
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]}')

transaction_id = body["data"]["transactionId"]

<?php
$ch = curl_init("https://api.oneclickdz.com/v3/bills/discover");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-Access-Token: " . getenv("ONECLICKDZ_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "partner" => "SEAAL",
        "account" => ["seaal" => ["code_client" => "100001", "code_contrat" => "446563"]],
        "ref" => "disc-20260920-0003",
    ]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
if (!$body["success"]) {
    throw new Exception($body["error"]["code"] . ": " . $body["error"]["message"]);
}

$transactionId = $body["data"]["transactionId"];
?>

Response

{
  "success": true,
  "data": {
    "transactionId": "68cdf0a2b7c1e4d5f6a7b8c9",
    "ref": "disc-20260920-0003",
    "status": "PENDING"
  },
  "meta": { "timestamp": "2026-09-20T10:15:32.194Z" },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

الأخطاء

تُعاد فورًا؛ ولا تُنشأ أي معاملة.

HTTP	الرمز	المعنى
400	`ERR_VALIDATION`	قيمة غير صالحة في `partner` أو `account` أو `ref`؛ يسرد `details` كل مشكلة
400	`INVALID_ACCOUNT`	في Sandbox فقط: حسابات الاختبار غير الصالحة تُجيب فورًا. في الإنتاج يظهر المعرّف المرفوض على المعاملة
401	`MISSING_ACCESS_TOKEN` / `INVALID_ACCESS_TOKEN`	المفتاح مفقود أو مرفوض
403	`DUPLICATED_REF`	قيمة `ref` مستخدمة مسبقًا لهذا الشريك
409	`BILL_ALREADY_PAID`	نجحت مسبقًا دفعة لهذا الحساب أو لهذه الفاتورة عبر هذه الواجهة
409	`PAYMENT_IN_PROGRESS`	دفعة لهذا الحساب قيد التنفيذ حاليًا
503	`PARTNER_UNAVAILABLE`	مُصدِر الفاتورة غير متاح أو معطّل
503	`AUTH_UNAVAILABLE`	تعذّر التحقّق من المفتاح في الوقت المحدّد؛ أعد المحاولة بعد `Retry-After`

نتيجة الاكتشاف

اقرأها من المعاملة:

`status`	المعنى
`READY`	تسرد `bills[]` الفواتير غير المدفوعة؛ وتعني المصفوفة الفارغة أنه لا يوجد شيء مستحق
`FAILED`	قيمة `error.code` هي `INVALID_ACCOUNT` أو `BILL_ALREADY_PAID` أو `PARTNER_UNAVAILABLE`، أو `PAYMENT_DECLINED` لأي رفض آخر من بوابة مُصدِر الفاتورة

مرجع API

Core

الحساب

شحن الهاتف

شحن الإنترنت

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

Navio

دفع الفواتير

جسم الطلب

الاستجابة

مثال

الأخطاء

نتيجة الاكتشاف

ذو صلة

​جسم الطلب

​الاستجابة

​مثال

​الأخطاء

​نتيجة الاكتشاف

​ذو صلة

جسم الطلب

الاستجابة

مثال

الأخطاء

نتيجة الاكتشاف

ذو صلة