المصادقة والوصول
صادق باستخدام مفتاح API ثابت في ترويسة X-API-Key. صيغة المفتاح، وما يمكنه الوصول إليه، ومعنى كل رمز 401 و403.
أرسل مفتاح API في ترويسة X-API-Key مع كل طلب. هذا هو نموذج المصادقة كله: لا تسجيل دخول ولا رموز مؤقتة ولا تجديد. يُقبل الطلب فقط عندما يكون المفتاح نشطًا، وتكامل الواجهة مفعّلًا على حسابك، ولحسابك ملف تسعير نشط، ويأتي الطلب من عنوان IP مسموح به.
مفتاح API
يحمل كل طلب إلى واجهة التكامل مفتاح API ثابتًا في ترويسة X-API-Key:
GET /api/v1/integration/transactions?from=...&to=... HTTP/1.1
Host: prod-app.octanetech-api.com
X-API-Key: oct_live_a1b2c3d4_Gk7fP2xQ9vLm3nRt8wYb5cHj6sDz1eAu4iFo0pNq| الخاصية | التفصيل |
|---|---|
| الصيغة | oct_live_<prefix>_<secret> في الإنتاج، وoct_test_<prefix>_<secret> في بيئة الاختبار |
| مدة الصلاحية | لا تنتهي صلاحية المفتاح من تلقاء نفسه. يتوقف عن العمل فقط عندما تعطّله أوكتين أو يفقد حسابك الوصول (انظر أدناه). |
| التدوير | قيمة المفتاح لا تتغير أبدًا. إذا تسرّب المفتاح، تعطّله أوكتين وتصدر مفتاحًا جديدًا ببادئة جديدة. |
| التخزين لدى أوكتين | يُخزَّن تجزئة SHA-256 للمفتاح فقط. لا تستطيع أوكتين استعادة مفتاح مفقود؛ يُصدر مفتاح جديد بدلًا منه. |
| النطاق | حساب عميل واحد، بما فيه كل مجموعات الشركات والشركات التابعة له. |
احتفظ بالمفتاح على الخادم
لا تضمّن المفتاح أبدًا في تطبيق جوال أو كود متصفح أو مستودع عام. أرسله عبر HTTPS فقط، ومن عناوين IP الموجودة في قائمتك المسموح بها فقط.
بادئة المفتاح
المقطع <prefix> (مثل a1b2c3d4) ليس سريًا. تستخدمه أوكتين للإشارة إلى مفتاحك في السجلات ومحادثات الدعم. اذكره عند التواصل مع أوكتين بشأن مفتاح؛ ولا ترسل المفتاح الكامل أبدًا.
ما يمكن للمفتاح الوصول إليه
يُستنتج حساب العميل دائمًا من المفتاح، وليس من معاملات الطلب أبدًا. لا يستطيع المفتاح قراءة سوى معاملات عميله. إذا صفّيت بـ corporate_id أو corporate_group_id، فيجب أن تنتمي القيم إلى حسابك؛ وأي قيمة أخرى تعيد 404.
إذا كان لمؤسستك عدة حسابات عملاء لدى أوكتين، فيحتاج كل حساب إلى مفتاحه الخاص.
متى يُقبل الطلب؟
ينجح الطلب فقط عندما تتحقق كل الشروط التالية، بهذا الترتيب:
- يأتي الطلب من عنوان IP مسموح به. وإلا
403 IP_NOT_ALLOWED. راجع الشبكة وحدود المعدل. - المفتاح ضمن حد المعدل. وإلا
429 RATE_LIMITED. - المفتاح صالح ونشط. وإلا
401 INVALID_API_KEY. يُعاد الرمز نفسه سواء كان المفتاح غير معروف أو معطّلًا. - تكامل الواجهة مفعّل على حسابك. وإلا
403 API_INTEGRATION_NOT_ENABLED. - لحسابك ملف تسعير نشط وغير منتهٍ. وإلا
403 NO_ACTIVE_CHARGING_PROFILE.
يحدد الشرطان 4 و5 أيضًا ما إذا كانت الويب هوك تُرسل: إذا فشل أحدهما تتوقف التسليمات حتى يعود الوصول.
انتهاء الوصول
عندما يكون لملف التسعير تاريخ انتهاء، تتضمن الاستجابات الناجحة ترويسة X-Access-Expires-At بذلك التاريخ بصيغة ISO 8601. ينتهي الوصول في تلك اللحظة بالضبط ما لم يُجدَّد الملف. راقب هذه الترويسة وجدّد مبكرًا لتجنب الانقطاع.
HTTP/1.1 200 OK
Content-Type: application/json
X-Access-Expires-At: 2026-12-31T21:59:59Zماذا تعني رموز 401 و403؟
| الحالة | الرمز | ما ينبغي فعله |
|---|---|---|
401 | INVALID_API_KEY | تحقق من اسم الترويسة وقيمتها. إذا عُطّل المفتاح، اطلب من أوكتين مفتاحًا جديدًا. |
403 | API_INTEGRATION_NOT_ENABLED | اطلب من مدير حسابك في أوكتين تفعيل تكامل الواجهة على حسابك. |
403 | NO_ACTIVE_CHARGING_PROFILE | ليس لحسابك ملف تسعير نشط، أو انتهى. تواصل مع أوكتين. |
403 | IP_NOT_ALLOWED | جاء الطلب من عنوان IP غير موجود في قائمتك. أرسل العنوان الجديد إلى أوكتين. |
403 | EDGE_NOT_ENFORCED | مشكلة إعداد من جانب أوكتين. تواصل مع دعم أوكتين مع بادئة مفتاحك وrequest_id. |
تشترك كل الأخطاء في الشكل نفسه.
المفاتيح والبيئات
تعمل مفاتيح الإنتاج (oct_live_) فقط على مضيف الإنتاج، ومفاتيح الاختبار (oct_test_) فقط على بيئة الاختبار. راجع البيئات.
أسئلة شائعة
- كيف أصادق مع واجهة تكامل أوكتين؟
- أرسل مفتاح API في ترويسة X-API-Key مع كل طلب عبر HTTPS. لا يوجد تسجيل دخول أو رمز مؤقت أو تجديد. تُصدر أوكتين المفاتيح وتبدو بالشكل oct_live_<prefix>_<secret>.
- هل تنتهي صلاحية مفتاح API؟
- لا. يعمل المفتاح حتى تعطّله أوكتين أو يفقد حسابك الوصول، مثلًا عند تعطيل التكامل أو انتهاء ملف التسعير. قيمة المفتاح لا تتغير أبدًا.
- لماذا أحصل على 401 INVALID_API_KEY؟
- ترويسة X-API-Key مفقودة، أو المفتاح غير معروف، أو تم تعطيله. يُعاد الرمز نفسه في الحالات الثلاث. تحقق من الترويسة ثم اسأل أوكتين عمّا إذا كان المفتاح نشطًا.
- لماذا أحصل على 403 NO_ACTIVE_CHARGING_PROFILE؟
- ليس لحسابك ملف تسعير نشط وغير منتهٍ لدى أوكتين. تواصل مع مدير حسابك لتجديده. يعود الوصول فورًا بمجرد تفعيل ملف.
- هل يمكن لمفتاح واحد الوصول إلى عدة شركات؟
- نعم. يغطي المفتاح حساب العميل بالكامل بما فيه كل مجموعات الشركات والشركات. استخدم corporate_id أو corporate_group_id للتصفية إذا أردت جزءًا منه فقط.