تنزيل إشعار AADL
curl --request GET \
--url https://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis \
--header 'X-Access-Token: <api-key>'import requests
url = "https://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis"
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://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis', 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/transactions/{transactionId}/avis",
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://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis"
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))
}HttpResponse<String> response = Unirest.get("https://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis")
.header("X-Access-Token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis")
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دفع الفواتير
تنزيل إشعار AADL
نزّل إشعار الدفع الرسمي من AADL لإحدى معاملاتك أنت
GET
/
v3
/
bills
/
transactions
/
{transactionId}
/
avis
تنزيل إشعار AADL
curl --request GET \
--url https://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis \
--header 'X-Access-Token: <api-key>'import requests
url = "https://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis"
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://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis', 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/transactions/{transactionId}/avis",
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://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis"
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))
}HttpResponse<String> response = Unirest.get("https://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis")
.header("X-Access-Token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.oneclickdz.com/v3/bills/transactions/{transactionId}/avis")
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نظرة عامة
يبثّ إشعار الدفع الذي تنشرهAADL لملف سكني — وهو ملف PDF نفسه الذي كان المستأجر سينزّله من مُصدِر الفاتورة — لمعاملة تملكها أنت. وكما في تنزيل الإيصال، لا يُعيد هذا endpoint غلاف JSON عند النجاح: الجسم هو البايتات نفسها، فيمكنك تمريرها مباشرةً إلى عميلك.وهو ليس الإيصال. فالإيصال يثبت أن دفعتك أنت قد تمت؛ أما الإشعار فهو بيان AADL بما يستحق على الملف السكني. ولا ينشره سوى AADL.الإشعار يُطلب بالمعاملة، لا برقم الملف السكني أبدًا. لا يوجد في هذا الطلب أي
codeloc، ولا يُقبل إرسال واحد. فنحن نحمّل المعاملة، ونتأكد أنها لك في هذه البيئة، ونرفضها إذا لم يكن partner فيها AADL، ثم نقرأ الملف السكني من الفاتورة المخزَّنة عليها أصلًا.وهذا مقصود. فصفحة التصدير لدى AADL لا تطلب أي جلسة وتُعيد ملف PDF لأي رمز، موجودًا كان أو غير موجود؛ ولو مرّرنا رمزًا يرسله المتصل لتحوّل هذا endpoint إلى أداة لتعداد ملفات الآخرين. أما استخراجه من معاملتك أنت فيجعل ذلك مستحيلًا.معاملات المسار
string
مطلوب
معرّف المعاملة. سلسلة ست عشرية صغيرة الأحرف من 24 حرفًا، من الحصول على معاملة بالمعرّف أو من أي قائمة، وتخص إحدى معاملات
AADL التي تملكها.وخلافًا للإيصال، لا يلزم أن تكون المعاملة في SUCCESS: فأي معاملة AADL لك جرى فيها تحديد فاتورة يمكن أن تُنتج إشعارًا.الاستجابة
عند النجاح يكون الجسم هو ملف PDF نفسه. اقرأ الترويسات لتعرف ما استلمته.header
مطلوب
application/pdf.header
مطلوب
attachment; filename="avis_<transactionId>.pdf". والاسم مبنيّ من معرّف المعاملة وحده، فلا يحمل أي هوية للمستأجر.header
مطلوب
حجم الملف بالبايت.
header
مطلوب
private, no-store. تُعيد AADL توليد الإشعار عند الطلب وتستبدله كل فترة، فلا شيء ثابت يستحق التخزين المؤقت — وهو وثيقة عميل واحد، لا وثيقة مشتركة.أمثلة
# -J -O تكتب الملف بالاسم الذي يقترحه الخادم
curl https://api.oneclickdz.com/v3/bills/transactions/68b2f4c1a7d3e9f204c81a55/avis \
-H "X-Access-Token: YOUR_API_KEY" \
--fail \
--remote-header-name --remote-name
import { writeFile } from "node:fs/promises";
const transactionId = "68b2f4c1a7d3e9f204c81a55";
const response = await fetch(
`https://api.oneclickdz.com/v3/bills/transactions/${transactionId}/avis`,
{ headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY } },
);
if (!response.ok) {
const error = await response.json();
throw new Error(`${error.error.code}: ${error.error.message}`);
}
const bytes = Buffer.from(await response.arrayBuffer());
await writeFile(`avis-${transactionId}.pdf`, bytes);
console.log(bytes.length);
import os
import requests
transaction_id = '68b2f4c1a7d3e9f204c81a55'
response = requests.get(
f'https://api.oneclickdz.com/v3/bills/transactions/{transaction_id}/avis',
headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
)
if response.status_code != 200:
error = response.json()
raise RuntimeError(f"{error['error']['code']}: {error['error']['message']}")
with open(f'avis-{transaction_id}.pdf', 'wb') as handle:
handle.write(response.content)
print(len(response.content))
<?php
$transactionId = '68b2f4c1a7d3e9f204c81a55';
$ch = curl_init("https://api.oneclickdz.com/v3/bills/transactions/$transactionId/avis");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
]);
$bytes = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
$error = json_decode($bytes, true);
throw new Exception($error['error']['code'] . ': ' . $error['error']['message']);
}
file_put_contents("avis-$transactionId.pdf", $bytes);
echo strlen($bytes);
?>
استجابة النجاح
الجسم ثنائي. وتبدو الترويسات هكذا:HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 71204
Content-Disposition: attachment; filename="avis_68b2f4c1a7d3e9f204c81a55.pdf"
Cache-Control: private, no-store
استجابات الخطأ
تُعاد الأخطاء بصيغة JSON، في الغلاف نفسه المستخدَم في كل endpoint آخر.401 — رمز وصول مفقود أو غير صالح
401 — رمز وصول مفقود أو غير صالح
المفتاح غائب أو مرفوض.ما العمل: تحقق من المفتاح عبر دليل المصادقة.
{
"success": false,
"error": {
"code": "INVALID_ACCESS_TOKEN",
"message": "The provided access token is invalid."
},
"requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}
404 — المعاملة غير موجودة
404 — المعاملة غير موجودة
المعرّف غير معروف، أو المعاملة ليست لك في هذه البيئة.مفتاح sandbox لا يرى معاملة إنتاج أبدًا، ولا يرى أي منهما معاملة مفتاح آخر. والجواب واحد في كل الحالات، فلا يؤكد هذا endpoint أبدًا وجود معاملة تخص شخصًا آخر.ما العمل: تحقق من المعرّف، وتحقق من أنك تستخدم المفتاح الذي أُنشئت به المعاملة.
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Transaction not found."
},
"requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}
404 — ليست معاملة AADL
404 — ليست معاملة AADL
المعاملة لك فعلًا، لكن شريكها لا ينشر إشعارًا.ما العمل: اقرأ
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "This partner does not publish a downloadable avis."
},
"requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}
partner على المعاملة أولًا، ولا تعرض التنزيل إلا حين تكون قيمته AADL. أما بقية مُصدِري الفواتير فالوثيقة المطلوبة لديهم هي الإيصال.404 — لا يتوفر إشعار بعد
404 — لا يتوفر إشعار بعد
لم يُحدَّد بعد أي ملف سكني على هذه المعاملة، أو رفضت AADL إصدار الوثيقة.فالاستكشاف الذي لم يبلغ
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "No avis is available for this transaction yet."
},
"requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}
READY بعد لا يحمل أي فاتورة، ومن ثمّ لا يوجد ما يُستخرج منه ملف سكني.ما العمل: انتظر حتى تحمل المعاملة فاتورة، ثم أعد المحاولة. ورفض مُصدِر الفاتورة يستحق محاولة إضافية واحدة، لا حلقة متكررة.فيمَ يُستخدم الإشعار
إظهار ما على العميل
يحمل الإشعار تفصيل AADL نفسها للملف السكني. وهو الوثيقة التي يعرفها المستأجر.
ليس بديلاً عن الإيصال
وحده الإيصال يثبت أن الدفع قد تم. وهو ما ينبغي حفظه مع طلبك.
تذكّر أن لملف السكن في AADL إشعارًا مفتوحًا واحدًا فقط، بما فيه من متأخرات مُدرَجة في مبلغه — فهذا الـPDF يمثل كل ما يستحق على الملف، لا فترة واحدة من بين عدة فترات. انظر الشركاء والحسابات.
أفضل الممارسات
تحقق من الشريك أولاً
لا تعرض التنزيل إلا لمعاملات
AADL. فكل شريك آخر يُجيب بـ 404 NOT_FOUND.لا تكشف الرابط أبداً
هذا الرابط يتطلب مفتاح API الخاص بك. قدّم البايتات من نظامك أنت، خلف مصادقتك أنت.
نزّله عند الحاجة
no-store ليست زينة: فـAADL تستبدل الإشعار كل فترة. نزّله حين تحتاج إليه.لا ترسل codeloc أبداً
لا يوجد أي معامِل معرّف يمكن تخمينه. وإن كان كودك يبني واحداً فهو ينادي شيئاً آخر.
Endpoints ذات صلة
تنزيل الإيصال
إثبات دفع ناجح
الحصول على معاملة بالمعرّف
حيث يظهر
partner والفواتيراستكشاف الفواتير
كيف يُستعلَم عن ملف سكني لدى AADL
الشركاء والحسابات
قواعد معرّف AADL