## نظرة عامة يتحقق من مفتاح API الخاص بدفع الفواتير ويعيد إليك من أنت والبيئة التي يرتبط بها المفتاح. وهو أول استدعاء يجب إجراؤه في أي تكامل جديد، وأأمن وسيلة لإثبات أنك موجَّه إلى sandbox لا إلى الإنتاج، قبل أن تحرّك أي أموال. كل مفتاح مرتبط ببيئة واحدة فقط لا غير — `SANDBOX` أو `PRODUCTION`. البيئة خاصية للمفتاح الذي نُصدره لك. **لا تستنتجها أبدًا من نص المفتاح أو من بادئته**؛ اقرأ `key.type` من هذا endpoint. يوجد دفع الفواتير على `https://billapi.oneclickdz.com`، لا على عنوان URL الأساسي الذي تستخدمه بقية المنصة. أما الترويسة فهي نفسها التي تستخدمها بالفعل: `X-Access-Token`. ## الاستجابة `true` عند التحقق من المفتاح بنجاح. معرّف حساب الشريك الخاص بك. `ACTIVE` لمفتاح اجتاز التحقق. دائمًا `DZD`. `SANDBOX` أو `PRODUCTION`. البيان الموثوق الوحيد للبيئة التي يعمل فيها هذا المفتاح. وقت الاستجابة، بتنسيق ISO 8601 UTC. معرّف الربط، يُرسَل أيضًا في ترويسة الاستجابة `X-Request-Id`. ## الأمثلة ```bash cURL theme={null} curl https://billapi.oneclickdz.com/v3/validate \ -H "X-Access-Token: YOUR_API_KEY" ``` ```javascript Node.js theme={null} const response = await fetch("https://billapi.oneclickdz.com/v3/validate", { 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(`Account ${body.data.account.id} — ${body.data.key.type}`); ``` ```python Python theme={null} import os import requests response = requests.get( 'https://billapi.oneclickdz.com/v3/validate', 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(f"Account {body['data']['account']['id']} — {body['data']['key']['type']}") ``` ```php PHP theme={null} ``` ### استجابة النجاح ```json theme={null} { "success": true, "data": { "account": { "id": "partner_7f21", "status": "ACTIVE", "currency": "DZD" }, "key": { "type": "SANDBOX" } }, "meta": { "timestamp": "2026-08-31T10:15:32.194Z" }, "requestId": "req_9f3a1c72e0b84d51aB3xZq07" } ``` ## استجابات الخطأ **لم تُرسَل ترويسة `X-Access-Token`.** ```json theme={null} { "success": false, "error": { "code": "MISSING_ACCESS_TOKEN", "message": "X-Access-Token header is required." }, "requestId": "req_9f3a1c72e0b84d51aB3xZq07" } ``` **ما العمل:** أضف الترويسة. لا يقبل دفع الفواتير المفتاح إلا في تلك الترويسة — لا في سلسلة استعلام ولا في متن الطلب. **رُفض المفتاح.** ```json theme={null} { "success": false, "error": { "code": "INVALID_ACCESS_TOKEN", "message": "The provided access token is invalid." }, "requestId": "req_9f3a1c72e0b84d51aB3xZq07" } ``` **ما العمل:** تحقّق من وجود خطأ في النسخ واللصق، ثم تواصل مع الدعم. إعادة المحاولة بالمفتاح نفسه لن تغيّر الإجابة. **لم نتمكن من التحقق من مفتاحك في الوقت المناسب. مفتاحك ليس هو المشكلة.** ```json theme={null} { "success": false, "error": { "code": "AUTH_UNAVAILABLE", "message": "Authentication is temporarily unavailable. Please retry shortly." }, "requestId": "req_9f3a1c72e0b84d51aB3xZq07" } ``` **ما العمل:** انتظر المدة المحددة في ترويسة `Retry-After` (5 ثوانٍ) ثم أعد المحاولة. لا تُظهر هذا لعميلك أبدًا على أنه خطأ في بيانات الاعتماد، ولا تعطّل المفتاح بسببه. **واجهة دفع الفواتير في صيانة مُخطّط لها.** ```json theme={null} { "success": false, "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Please retry shortly." }, "requestId": "req_9f3a1c72e0b84d51aB3xZq07" } ``` **ما العمل:** التزم بـ `Retry-After` وأعد المحاولة. ## تأكيد بيئتك قبل الإطلاق نفّذ هذا الفحص عند بدء التشغيل، ثم مرة أخرى في خط النشر لديك. سطر واحد من المخرجات يخبرك ما إذا كان المفتاح الموجود في إعدادات تلك البيئة هو المفتاح الذي قصدت إطلاقه. ```javascript theme={null} async function assertEnvironment(expected) { const response = await fetch("https://billapi.oneclickdz.com/v3/validate", { headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY }, }); const body = await response.json(); if (!body.success) { throw new Error(`Key check failed: ${body.error.code}`); } if (body.data.key.type !== expected) { throw new Error( `Wrong key: expected ${expected}, got ${body.data.key.type}`, ); } return body.data.account.id; } // In your sandbox deployment await assertEnvironment("SANDBOX"); ``` مفتاح sandbox ومفتاح الإنتاج متبادلان في الشكل لا في الأثر. مفتاح الإنتاج يحرّك أموالًا حقيقية عند أول عملية دفع ناجحة. تحقّق من `key.type` قبل تفعيل مسار الدفع. ## ما لا يُرجعه هذا endpoint مفاتيح دفع الفواتير ليس لها نطاقات صلاحية، ولا حقل انتهاء صلاحية، ولا رصيد لكل مفتاح، لذلك لا يظهر أي منها هنا. `account` و`key.type` و`meta` و`requestId` هي الاستجابة كاملةً. ## أفضل الممارسات استدعاء واحد عند الإقلاع يثبت أن المفتاح يعمل ويحدّد اسم البيئة، قبل أن تصل أي حركة عملاء إلى مسار الدفع. سجّل `account.id` و`key.type` بدلًا منه. مكان المفتاح نفسه هو مخزن أسرار، لا سجلات التطبيق. احتفظ بمفتاح sandbox ومفتاح الإنتاج في مخازن إعدادات مختلفة كي لا يمكن الوصول إلى أيٍّ منهما من البيئة الأخرى. يعني `AUTH_UNAVAILABLE` أننا لم نتمكن من الإجابة في الوقت المناسب. أعد المحاولة بعد `Retry-After`؛ ولا تُدوّر المفتاح. ## Endpoints ذات الصلة تحقّق من الشركاء المتاحين ابدأ استكشاف فاتورة كيف يتكامل التدفق بأكمله اختبر كل نتيجة ممكنة قبل الإطلاق