تحوّل مفاتيح API الخاصة بـ Fixh IT برنامج مركز الصيانة الخاص بك إلى منصة مفتوحة: من قسم الشركة > مفاتيح API، يمكن لشركتك إنشاء وإلغاء مفاتيح API من نوع REST v1، تُستخدم في ترويسة X-API-Key لمصادقة الطلبات الموجهة إلى نقطة النهاية /api/v1/company/... هذه ليست ميزة للمبرمجين المعزولين فقط: إنها الجسر بين ورشة الإصلاح الخاصة بك وبقية منظومة برامجك، من موقعك الإلكتروني إلى برنامج المحاسبة، ومن نظام إدارة العملاء إلى الروبوت الذي يرد على عملائك. لأسباب أمنية، يُعرض المفتاح الكامل على الشاشة مرة واحدة فقط، مباشرة بعد الإنشاء: بعد ذلك يظهر فقط بصورة مُخفية جزئيًا (key_prefix)، لذا يجب نسخه وحفظه فورًا في مكان آمن.
لماذا هذا مهم لمركز الصيانة
نادرًا ما تعمل ورشة إصلاح الهواتف الذكية وأجهزة الكمبيوتر بأداة واحدة فقط: هناك نظام الإدارة الرئيسي، وربما متجر إلكتروني لقطع الغيار، وروبوت محادثة يرد على العملاء عبر واتساب أو تيليجرام، وبرنامج محاسبة لإصدار الفواتير، وأداة تسويق لحملات البريد الإلكتروني. بدون تكامل حقيقي، تظل كل هذه المعلومات معزولة داخل كل نظام، مما يجبر الموظفين على إدخال البيانات نفسها عدة مرات، مع خطر حقيقي لأخطاء النسخ وتأخر التواصل مع العميل. تحل مفاتيح API من نوع REST v1 هذه المشكلة بالضبط: فهي تتيح لنظام خارجي التواصل تلقائيًا مع بيانات إصلاحات شركتك في Fixh IT، وقراءة حالة تذكرة، وإنشاء إصلاحات جديدة من نموذج عبر الإنترنت، أو تحديث تذكرة عندما يُشير فني إلى اكتمال عملية. بالنسبة لمركز صيانة يتعامل مع عشرات أو مئات الإصلاحات شهريًا، يمكن لهذا التكامل بين إصلاحات الهواتف الذكية وأجهزة الكمبيوتر والبرامج الخارجية أن يُحدث فرقًا بين سير عمل سلس وآخر مليء بالإدخال اليدوي المزدوج.
من الناحية العملية
يرتبط كل مفتاح API يتم إنشاؤه بشركتك (key_type "company")، ويسمح لنظام خارجي بالمصادقة أمام واجهات REST v1 الخاصة بـ Fixh IT من خلال تضمين المفتاح في ترويسة X-API-Key لكل طلب HTTP. باستخدام هذا النوع من المفاتيح، يمكنك عرض قائمة إصلاحات شركتك مع تصفية حسب الفرع أو الحالة أو نص البحث، وقراءة تفاصيل إصلاح واحد، وإنشاء إصلاحات جديدة بتحديد الفرع والعميل والفني والجهاز والعطل المكتشف والملحقات المُسلَّمة والعرض السعري، أو تحديث إصلاح موجود بتغيير حالته أو دفعه أو تسليمه أو ملاحظاته الداخلية. يتم دائمًا تصفية كل طلب تلقائيًا حسب الشركة التي ينتمي إليها المفتاح: لا يمكن لنظام خارجي أبدًا رؤية أو تعديل بيانات شركة أخرى في الشبكة، حتى عن طريق الخطأ، لأن التحقق يتم من جانب الخادم في كل استعلام على حدة.
لأسباب أمنية، يُعرض المفتاح الكامل (السلسلة السرية الفعلية) على الشاشة مرة واحدة فقط، مباشرة بعد الإنشاء: بعد ذلك يحتفظ النظام فقط بتجزئة (hash) للمفتاح ويعرض في القائمة بادئته الأولية فقط (key_prefix)، وهي كافية للتعرّف عليه ولكن ليس لإعادة استخدامه. لذا من الضروري نسخ المفتاح فورًا ولصقه في ملف إعدادات النظام الخارجي الذي سيستخدمه، قبل إغلاق النافذة: إذا نسيت ذلك، فالحل الوحيد هو إلغاء ذلك المفتاح وإنشاء مفتاح جديد. يعرض كل مفتاح أيضًا تاريخ آخر استخدام له، وهو مفيد لمعرفة ما إذا كان التكامل لا يزال نشطًا أو يمكن تعطيله بأمان لأنه لم يعد مستخدمًا. إذا فُقد المفتاح أو تعرّض للاختراق أو لم يعد هناك حاجة إليه، يمكنك إلغاؤه في أي وقت من القائمة: بمجرد الإلغاء يتوقف عن العمل فورًا، ويُسجَّل تاريخ الإلغاء، ويفقد أي نظام كان يستخدمه إمكانية الوصول إلى واجهات API على الفور، دون الحاجة للتدخل في أي مكان آخر.
إلى جانب مفاتيح نوع الشركة، يحتوي النظام التقني نفسه أيضًا على نوع مفتاح مخصص لموزعي شبكة Fixh IT، يُستخدم لإدارة إصدار ومراقبة رموز الترخيص تلقائيًا من برنامج الإدارة الخاص بهم: النوعان من المفاتيح منفصلان تمامًا (حراسات وصلاحيات مختلفة)، ولا يمكن أبدًا استخدام مفتاح الشركة في عمليات مخصصة للموزعين، والعكس صحيح.
دليل سريع
- اذهب إلى الشركة > مفاتيح API.
- أنشئ مفتاح API جديدًا وأعطه اسمًا وصفيًا يحدد بوضوح التكامل (مثل "متجر قطع الغيار الإلكتروني" أو "روبوت دعم واتساب").
- انسخ فورًا المفتاح الكامل المعروض على الشاشة: لن يظهر كاملًا مرة أخرى بعد ذلك، فقط بصورة مُخفية جزئيًا.
- الصق المفتاح في ملف إعدادات النظام الخارجي، في المتغير المخصص لترويسة X-API-Key.
- اضبط النظام الخارجي لإرسال المفتاح في ترويسة X-API-Key مع كل طلب إلى /api/v1/company/repairs ونقاط النهاية الأخرى المتاحة.
- اختبر التكامل بطلب تجريبي، مثل قراءة قائمة الإصلاحات، للتحقق من أن الاستجابة تحتوي على البيانات المتوقعة.
- راجع دوريًا تاريخ آخر استخدام لكل مفتاح لاكتشاف عمليات التكامل التي لم تعد نشطة.
- عند الحاجة، ألغِ المفتاح من القائمة لإيقاف استخدامه فورًا، مثلًا عند تغيير مزود موقعك الإلكتروني أو التوقف عن استخدام أداة خارجية.
حالات استخدام واقعية
نموذج طلب إصلاح على الموقع الإلكتروني. تدمج ورشة إصلاح هواتف ذكية في موقعها نموذج "اطلب صيانة": عندما يملأه العميل، يستدعي سكريبت خارجي نقطة نهاية إنشاء الإصلاح مع ترويسة X-API-Key، فيُنشئ تلقائيًا تذكرة جديدة في النظام، مُسندة بالفعل إلى الفرع الصحيح وجاهزة ليتولاها فني، دون الحاجة لأن ينسخ أحد البيانات يدويًا من الموقع إلى النظام.
المزامنة مع نظام محاسبة خارجي. تستخدم شركة تضم عدة فروع برنامج محاسبة منفصلًا لإصدار الفواتير: يقرأ تكامل مجدول كل ليلة، عبر مفتاح API، الإصلاحات المُعلَّمة كمدفوعة ومُسلَّمة خلال الـ24 ساعة الأخيرة، ويستوردها إلى نظام المحاسبة للتسجيل الضريبي، متجنبًا الإدخال اليدوي المزدوج للبيانات.
إشعارات تلقائية للعميل عبر روبوت. يربط مركز صيانة روبوت مراسلة بنظامه: عندما يُحدّث فني حالة إصلاح من "قيد التنفيذ" إلى "جاهز للاستلام" عبر API، يتحقق الروبوت الخارجي دوريًا من الإصلاحات المُحدَّثة مؤخرًا ويرسل تلقائيًا رسالة للعميل، مما يقلل المكالمات إلى المتجر للاستفسار عن حالة الإصلاح.
نصائح وأفضل الممارسات
أنشئ مفتاح API منفصلًا لكل تكامل بدلًا من إعادة استخدام المفتاح نفسه في كل مكان: بهذه الطريقة، إذا تم إيقاف نظام خارجي أو تعرّض للاختراق، يمكنك إلغاء ذلك المفتاح فقط دون الحاجة لإعادة ضبط جميع عمليات التكامل الأخرى. أعطِ كل مفتاح اسمًا وصفيًا يُذكّرك بلمحة بغرضه، خاصة إذا تراكم لديك عدة مفاتيح بمرور الوقت. راجع دوريًا تاريخ آخر استخدام لاكتشاف المفاتيح "المنسية" المرتبطة بأنظمة لم تعد تستخدمها، وألغها: كلما قلّ عدد المفاتيح النشطة، صغرت مساحة الهجوم المحتملة. احتفظ بالمفتاح الكامل في مدير كلمات مرور أو ملف إعدادات محمي، وليس أبدًا في مستند مشترك أو رسالة دردشة.
أخطاء شائعة يجب تجنبها
لا تشارك أبدًا نفس مفتاح API بين عدة عمليات تكامل مختلفة: إذا احتجت لتعطيل إحداها مستقبلًا، فأنت تخاطر بتعطيل البقية أيضًا. لا تضع المفتاح مباشرة في الكود المصدري العام لموقع أو تطبيق: يجب أن يبقى دائمًا في ملف إعدادات منفصل وغير مُدرج في نظام التحكم بالإصدارات. لا تتوقع استعادة المفتاح الكامل بعد إغلاق النافذة أول مرة: إذا نسيت نسخه، فالحل الوحيد هو إلغاؤه وإنشاء مفتاح جديد. أخيرًا، لا تنسَ إلغاء مفاتيح عمليات التكامل الملغاة: يظل المفتاح النشط وغير المستخدم نقطة وصول محتملة إلى بيانات إصلاحاتك.
اقرأ أيضًا
- Fixh Assistant: روبوت محادثة واتساب مع Fixh AI لمركز الصيانة لديك
- واجهة المتجر: بِع منتجات مخزونك عبر الإنترنت
- تصدير كل بيانات الشركة: الإصلاحات والمستندات والعملاء والإيصالات في أرشيف ZIP
الأسئلة الشائعة
هل يمكنني رؤية المفتاح الكامل مرة أخرى بعد إنشائه؟ لا، لأسباب أمنية يُعرض المفتاح الكامل فقط عند الإنشاء؛ وإذا فقدته يجب إلغاؤه وإنشاء مفتاح جديد.
ماذا يحدث إذا ألغيت مفتاح API؟ يتوقف المفتاح عن العمل فورًا، ويُسجَّل تاريخ الإلغاء، ويرفض النظام أي طلب يستخدمه.
هل يمكنني إنشاء عدة مفاتيح API لنفس الشركة؟ نعم، يمكنك إنشاء عدة مفاتيح، مثلًا مفتاح لكل تكامل أو نظام خارجي متصل، وإلغاؤها بشكل فردي دون التأثير على البقية.
ما البيانات التي يمكنني قراءتها أو كتابتها بمفتاح API الخاص بالشركة؟ إصلاحات شركتك: يمكنك عرضها، وتصفيتها حسب الفرع أو الحالة، وإنشاء إصلاحات جديدة، وتحديث حالة وسداد وتسليم وملاحظات الإصلاحات الموجودة، دائمًا ضمن نطاق شركتك تلقائيًا.
هل تختلف مفاتيح API عن تلك التي يستخدمها الموزعون للتراخيص؟ نعم، هناك نوعان منفصلان تمامًا من المفاتيح: مفاتيح الشركة للإصلاحات ومفاتيح الموزعين لإدارة رموز التراخيص، بصلاحيات ونطاقات مختلفة.
هل تحتاج إلى مهارات تقنية لاستخدام مفاتيح API؟ نعم، يتطلب التكامل أن يكون النظام الخارجي (موقع، روبوت، برنامج تابع لجهة أخرى) مبرمجًا لإرسال طلبات HTTP مع ترويسة X-API-Key: وهي مصممة للمطورين أو موردي البرامج المتعاونين مع مركز الصيانة الخاص بك.
