مفتاح API: ربط نظام آخر باستوديوك
يتيح مفتاح API لنظام آخر (مثل نظام ERP أو جدول بيانات آلي أو موقع أو تطبيق خاص بك) الاطلاع على بيانات استوديوك وتسجيلها من دون الحاجة إلى إدخال أي شيء يدويًا. يعمل كل مفتاح كمستخدم في الاستوديو: إذ يتيح له تنفيذ ما يُسمح لذلك المستخدم به، ولا شيء أكثر.
متى تستخدمه
Section titled “متى تستخدمه”- يحتاج نظام إدارة إلى قراءة مبيعات اليوم لأغراض المحاسبة.
- يحتاج موقع أو تطبيق خاص بك إلى تسجيل العملاء أو الاطلاع على الكتالوج.
- يحتاج إجراء آلي إلى تسجيل المصروفات أو الاطلاع على الحسابات المستحقة القبض.
قبل أن تبدأ
Section titled “قبل أن تبدأ”يمكن لمن يدير الاستوديو فقط (من لديه صلاحية وصول كاملة أو إذن لتعديل الملفات الشخصية والمستخدمين) إنشاء المفاتيح وتعديلها وإلغاءها. إذا لم تتمكن من إنشاء مفتاح، فاطلب من مالك الاستوديو منحك صلاحية الوصول من الوصول → الملفات الشخصية.
يُفضّل إنشاء مستخدم مخصص للتكامل أولًا، مع ملف شخصي يتيح فقط الشاشات التي يحتاج النظام الآخر إلى استخدامها. يرث المفتاح أذونات هذا المستخدم.
خطوة بخطوة
Section titled “خطوة بخطوة”الخطوة 1 — فتح علامة تبويب API Key
Section titled “الخطوة 1 — فتح علامة تبويب API Key”من الإعدادات → الشركة، افتح علامة تبويب مفتاح API. تعرض هذه الصفحة المفاتيح التي أُنشئت بالفعل، ومستخدم كل مفتاح، وعناوين IP المسموح بها والصلاحية وآخر استخدام.
الخطوة 2 — إنشاء المفتاح
Section titled “الخطوة 2 — إنشاء المفتاح”انقر على مفتاح جديد، وأدخل الاسم، ثم اختر المستخدم. في عناوين IP المسموح بها، أضف عنوان IP أو نطاقًا في كل سطر للسماح بالطلبات من تلك العناوين فقط (اترك الحقل فارغًا للسماح بأي عنوان IP). في الصلاحية، اختر لا تنتهي صلاحيته أو تنتهي صلاحيته في لتحديد تاريخ انتهاء الصلاحية: يظل المفتاح صالحًا حتى نهاية ذلك اليوم. انقر على إنشاء مفتاح، ثم انسخ المفتاح باستخدام زر النسخ. لن يظهر المفتاح مرة أخرى.
يرسل النظام الآخر المفتاح مع كل طلب في ترويسة Authorization، على النحو التالي:
Authorization: Bearer hk_... (استبدل hk_... بالمفتاح كاملًا).
لاستخدام المفتاح مع ذكاء اصطناعي (Claude Code أو Gemini CLI أو Cursor)، حدّد أيضًا السماح بالاستخدام كموصل ذكاء اصطناعي ضمن موصل الذكاء الاصطناعي. من دون تفعيل هذا الخيار، يعمل المفتاح مع عمليات التكامل، لكنه لا يعمل مع موصل الذكاء الاصطناعي. راجع مقالة موصل الذكاء الاصطناعي.
الخطوة 3 — إلغاء مفتاح
Section titled “الخطوة 3 — إلغاء مفتاح”في القائمة، انقر على رمز سلة المهملات بجوار المفتاح، ثم أكّد الإجراء بالنقر على إلغاء التفويض. سيفقد النظام الذي يستخدم المفتاح إمكانية الوصول خلال 30 ثانية كحد أقصى. لتغيير الاسم أو عناوين IP أو مدة الصلاحية، استخدم رمز القلم.
ماذا يحدث بعد ذلك
Section titled “ماذا يحدث بعد ذلك”- تظهر كل التغييرات التي يجريها النظام الآخر باستخدام المفتاح في سجل التدقيق، مع الإشارة إلى مصدرها بوصفه مفتاح API، وباسم مستخدم المفتاح.
- يتوقف المفتاح عن العمل تلقائيًا عند انتهاء صلاحيته أو عند إلغاء تنشيط المستخدم المرتبط به في الاستوديو. وسيظهر في القائمة بالحالة منتهي الصلاحية أو مستخدم غير نشط.
- لا يتيح المفتاح أبدًا الوصول إلى شركة أخرى، حتى لو كان مستخدمه يعمل أيضًا في شركة أخرى.
أخطاء شائعة وأسئلة
Section titled “أخطاء شائعة وأسئلة”س: هل يمكن للمفتاح تنفيذ أي إجراء في النظام؟ ج: لا. يتيح المفتاح الأذونات الممنوحة لمستخدمه، وفي هذا الاستوديو فقط. وهناك أقسام لا تسمح باستخدام المفاتيح مطلقًا، حتى لو كان المستخدم لديه صلاحية وصول كاملة: تسجيل الدخول وتغيير الشركة، وشاشة المفاتيح نفسها، وإدارة المستخدمين والدعوات، وHeya، والدعم، ولوحات المعلومات، والإعدادات العامة للشركة (الشعار، وساعات العمل، والعطلات، والنطاق، والبريد الإلكتروني للتقارير)، وشاشات المنصة. إذا كان لديك عدة عمليات تكامل، فأنشئ مستخدمًا لكل منها: سيظهر التغيير في سجل التدقيق باسم مستخدم المفتاح.
س: فقدت المفتاح. هل يمكنني عرضه مرة أخرى؟ ج: لا. يحتفظ النظام ببصمة المفتاح فقط، ولا يخزّن المفتاح نفسه أبدًا. ألغِ المفتاح القديم وأنشئ مفتاحًا جديدًا.
س: تظهر للنظام الآخر الرسالة «عنوان IP هذا غير مصرح له باستخدام مفتاح API هذا». ماذا أفعل؟ ج: عنوان IP الذي يرسل منه النظام الطلب غير مدرج ضمن عناوين IP المسموح بها. عدّل المفتاح وأضف عنوان IP، أو اترك القائمة فارغة للسماح بأي عنوان IP.
س: تظهر للنظام الآخر الرسالة «لا يمكن استخدام هذا المسار مع مفتاح API». ما السبب؟ ج: يحاول النظام الوصول إلى أحد الأقسام التي لا تسمح باستخدام المفاتيح (راجع السؤال الأول). يجب تنفيذ هذه العمليات بواسطة شخص من داخل الشاشة.
س: هل يمكنني تغيير المستخدم المرتبط بالمفتاح؟ ج: لا. ألغِ المفتاح وأنشئ مفتاحًا آخر للمستخدم الجديد.
س: لماذا قائمة المستخدمين عند إنشاء مفتاح جديد فارغة؟ ج: لا يمكن لأعضاء فريق المنصة استخدام مفاتيح API، لذلك لا يظهرون في القائمة. أضف مستخدمًا خاصًا بالاستوديو (ويُفضّل أن يكون مخصصًا للتكامل وحده)، ثم أنشئ له المفتاح.