مفاتيح API — الإنشاء والإرسال والحدود
المفتاح هو الاعتماد الوحيد لطرف خارجي: 40 خانة تظهر مرة واحدة وتُخزَّن هاشًا. له اسم وتاريخ انتهاء اختياري وحدّ طلبات في الدقيقة. يُرسل في الترويسة، ويُدوَّر بإنشاء جديد وحذف القديم.
آخر تحديث: 2026-10-09
في الصفحة دي
لا توكنات جلسة
الطرف الخارجي يملك وسيلة واحدة: مفتاح API. لا توكنات Sanctum ولا OAuth — وما يحتاج جلسة موظف (خطوتا الطباعة في Dynamics) لا يُنادى من سيرفر.
الإنشاء
الإعدادات ← التكامل ← تبويب مفاتيح API ← إضافة مفتاح:
| الحقل | اللابل | القاعدة |
|---|---|---|
name |
اسم العميل | مطلوب — «نظام SAP — قسم المالية» |
company_id |
الشركة | مطلوب — الشركة التي يكتب فيها هذا المفتاح؛ نظام يخدم شركتين يأخذ مفتاحين |
expires_at |
تاريخ الانتهاء (اختياري) | فارغ = لا ينتهي؛ تاريخ ماضٍ يُرفض |
rate_limit_per_minute |
حد الطلبات / الدقيقة | 1–100000، الافتراضي 60 |
بعد الحفظ يظهر المفتاح مرة واحدة: «انسخ المفتاح الآن — لن يُعرض مرة أخرى.» يُخزَّن هاشه (SHA-256) فقط؛ لا استرجاع أبدًا. المفتاح 40 خانة سداسية عشرية (160 بت عشوائية).
المفتاح بلا شركة أو شركته معطَّلة أو محذوفة يظهر «متوقّف» والسبب في شارة عمود الشركة — والسيرفر يرفض نداءاته حتى تختار له شركة من عمود الإجراءات:
الجدول: المعرّف · الاسم · الشركة · الحالة · تاريخ الانتهاء · حد الطلبات / الدقيقة · تاريخ الإنشاء · إجراءات.
عمود «الحالة» يقول الحالة الفعلية لا علم المفتاح وحده:
| الشارة | متى |
|---|---|
| فعّال | المفتاح مفعَّل وشركته نشطة وغير محذوفة — وهو وحده الذي يعمل |
| متوقّف | المفتاح مفعَّل لكن شركته لا تقبل الكتابة: بلا شركة · شركته معطَّلة · شركته في سلة المحذوفات |
| غير فعّال | المفتاح نفسه مُعطَّل |
| منتهٍ | تجاوز تاريخ انتهائه |
وعمود «الشركة» يقول السبب: المفتاح بلا شركة يحمل شارة بلا شركة — متوقّف ولافتة بعددها؛ والمفتاح الذي توقّف بسبب شركته يحمل اسمها ومعه شركته معطَّلة أو محذوفة — متوقّف، والشركة التي في السلة يظهر اسمها موسومًا (في سلة المحذوفات).
تعيين شركة المفتاح أو نقله من المنتقي في صفه: حين تكون شركته الحالية ليست خيارًا (بلا شركة · معطَّلة · في السلة) يبدأ المنتقي على «— اختر شركة —» غير القابل للاختيار، وزرّ ✓ يبقى معطَّلًا حتى يختلف الاختيار عن الحالي. والتأكيد يسمّي الشركة الجديدة: «نقل المفتاح إلى «‹الاسم›»؟» ويقول إن الشيكات المختومة سابقًا تبقى بشركتها وسجل التدقيق القديم يبقى بشركته، والتغيير يسري على القادم فقط.
المفتاح يتبع حالة شركته
المفتاح يتوقّف من نفسه متى عُطِّلت شركته أو حُذفت، ويعود تلقائيًا عند إعادة التفعيل أو الاسترجاع — لا شيء يُكتب على المفتاح نفسه:
- نداءات المسار الخارجي وDynamics تُرَدّ بـ422 «شركة المفتاح معطَّلة أو محذوفة»، وإكمال مسودة Dynamics يُرفض كذلك.
- المفتاح بلا شركة يُرَدّ بـ422 «مفتاح الـAPI غير منسوب لشركة» حتى تُعيَّن من هذه الشاشة.
- وإسناد المفتاح لشركة معطَّلة أو محذوفة يُرفض برسالة «اختر شركة نشطة» — والقائمة لا تعرض إلا الشركات النشطة غير المحذوفة.
والحذف النهائي لشركة عليها مفاتيح يُرفض برسالة تقول المخرج: انقل مفاتيحها لشركة أخرى أو احذفها أولًا. (سلة المحذوفات ← الشركات ← حذف نهائي.)
الإرسال
ثلاث صيغ بترتيب الأسبقية — والأولى هي المعتمدة:
| # | الصيغة | ملاحظة |
|---|---|---|
| 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 معلَن حتى يعيّنها المسؤول. راجع الأمان.
صفحات ذات صلة
هل أجابت هذه الصفحة عن سؤالك؟
شكرًا — رأيك يصلنا ويساعدنا نحسّن الدليل.
تعذّر الإرسال — حاول مرة أخرى بعد قليل.