مفاتيح API — الإنشاء والإرسال والحدود
المفتاح هو الاعتماد الوحيد لطرف خارجي: 40 خانة تظهر مرة واحدة وتُخزَّن هاشًا. له اسم وتاريخ انتهاء اختياري وحدّ طلبات في الدقيقة. يُرسل في الترويسة، ويُدوَّر بإنشاء جديد وحذف القديم.
آخر تحديث: 2026-09-21
في الصفحة دي
لا توكنات جلسة
الطرف الخارجي يملك وسيلة واحدة: مفتاح API. لا توكنات Sanctum ولا OAuth — وما يحتاج جلسة موظف (خطوتا الطباعة في Dynamics) لا يُنادى من سيرفر.
الإنشاء
الإعدادات ← التكامل ← تبويب مفاتيح API ← إضافة مفتاح:
| الحقل | اللابل | القاعدة |
|---|---|---|
name |
اسم العميل | مطلوب — «نظام SAP — قسم المالية» |
company_id |
الشركة | مطلوب — الشركة التي يكتب فيها هذا المفتاح؛ نظام يخدم شركتين يأخذ مفتاحين |
expires_at |
تاريخ الانتهاء (اختياري) | فارغ = لا ينتهي؛ تاريخ ماضٍ يُرفض |
rate_limit_per_minute |
حد الطلبات / الدقيقة | 1–100000، الافتراضي 60 |
بعد الحفظ يظهر المفتاح مرة واحدة: «انسخ المفتاح الآن — لن يُعرض مرة أخرى.» يُخزَّن هاشه (SHA-256) فقط؛ لا استرجاع أبدًا. المفتاح 40 خانة سداسية عشرية (160 بت عشوائية).
الجدول: المعرّف · الاسم · الشركة · الحالة · تاريخ الانتهاء · حد الطلبات / الدقيقة · تاريخ الإنشاء · إجراءات. المفتاح القديم بلا شركة يحمل شارة بلا شركة — معطَّل ولافتة بعددها؛ محرّر الشركة في صفه يعيّنها (بتأكيد يذكر أن الشيكات المختومة سابقًا تبقى بشركتها).
الإرسال
ثلاث صيغ بترتيب الأسبقية — والأولى هي المعتمدة:
| # | الصيغة | ملاحظة |
|---|---|---|
| 1 | ترويسة X-API-KEY: <key> |
استعملها |
| 2 | ?api_key=<key> في الرابط |
يتسرّب إلى سجلات الخادم وإلى Referer — تجنّبها |
| 3 | حقل secret في جسم الطلب |
يُجرَّد من سجل التدقيق لكنه يُرسل فعلًا |
سلّم الرفض
أول شرط يتحقق ينهي الطلب:
| # | الشرط | الرد | الجسم |
|---|---|---|---|
| 1 | التكاملات معطَّلة | 503 | {"error":"Integrations are currently disabled"} |
| 2 | لا مفتاح | 401 | {"error":"Unauthorized"} |
| 3 | مفتاح لا يطابق أو غير نشط | 401 | نفس النصّ — بلا تمييز عمدًا |
| 4 | مفتاح منتهٍ | 403 | {"error":"API key expired"} |
| 5 | تجاوز الحدّ | 429 | {"error":"Too many requests","retry_after_seconds":N} |
حدّ المعدل
نافذة 60 ثانية ثابتة لكل مفتاح (لا لكل IP). بحدّ 60: الطلبات 1–60 تمرّ و61 أول مرفوض؛ retry_after_seconds يقول متى تعيد. الحدّ يُطبَّق بعد المصادقة — فالمفتاح الخاطئ لا يُحدّ (راجع الأمان).
التدوير والحذف
لا زرّ «إبطال»: حذف المفتاح نهائي («لن تتمكّن الأنظمة التي تستخدمه من الاتصال بعد الحذف»). التدوير = أنشئ مفتاحًا جديدًا ← بدّله في النظام الخارجي ← احذف القديم. الانتهاء التلقائي بـexpires_at. حذف المفتاح يُبقي صفوف تدقيقه بلا نسبة.
نطاق المفتاح
المفتاح يفتح كل نقاط النهاية (لا نطاقات جزئية) داخل شركته: كل شيك يُنشأ به يُختم بشركة المفتاح، وcompany_id في الحمولة اختياري — إن أُرسل وخالف ⟹ 422 برسالة تسمّي الشركتين. ومرجع من شركة أخرى (bank_account_id · cheque_book_id · cheque_leaf_id · partner_id) ⟹ 422. مفتاح بلا شركة ⟹ 422 معلَن حتى يعيّنها المسؤول. راجع الأمان.
صفحات ذات صلة
هل أجابت هذه الصفحة عن سؤالك؟
شكرًا — رأيك يصلنا ويساعدنا نحسّن الدليل.
تعذّر الإرسال — حاول مرة أخرى بعد قليل.