تكامل API في مستند: اربط أنظمتك برمجياً بمفاتيح آمنة

صفحة «تكامل API» في مستند هي المكان الذي تحصل منه على مفاتيح ربط أنظمتك الخارجية بمستند برمجياً: المفتاح العام والمفتاح السري، والرابط الأساسي، وتوثيق الواجهة. وتتحكم منها في أمان الربط عبر إلغاء المفتاح وتقييد الوصول بقائمة عناوين IP، وتتابع حجم الاستخدام بإحصائيات يومية وشهرية. تخدم فرق التقنية التي تريد أن ترسل أنظمة المنشأة ملفاتها إلى مستند تلقائياً.

نظرة سريعة

شاهد الشرح بالفيديو

يعرض الفيديو في 42 ثانية تقريباً أقسام صفحة تكامل API بالترتيب: معلومات المفتاح، ومكان المحتوى، والحد وإلغاء المفتاح، وقائمة عناوين IP، ثم إحصائيات الاستخدام.

لماذا هذه الميزة؟

في كثير من المنشآت تُنشأ المستندات خارج نظام إدارة المستندات. نظام المحاسبة يصدر الفواتير، ونظام الموارد البشرية يصدر العقود والخطابات، ونظام المبيعات يصدر عروض الأسعار. بدون ربط برمجي، ينزّل أحد الموظفين هذه الملفات ثم يرفعها يدوياً، فيتأخر الحفظ وتضيع ملفات ويتكرر بعضها.

الربط عبر API يجعل هذا النقل آلياً. يرسل النظام الخارجي ملفاته إلى مستند مباشرة، فتصل إلى مجلد محدد وتستفيد من البحث والتحليل والصلاحيات. وتمنحك الصفحة في الوقت نفسه أدوات الحوكمة: من يستطيع الاتصال، ومن أين، وبأي حجم.

أين تجدها

1. افتح «الإعدادات».
2. اختر «تكامل API».

الرابط المباشر: https://app.mstnd.sa/settings-api-integration

مفاهيم ومصطلحات

الخطوات بالتفصيل

الخطوة 1: تعرّف على «معلومات المفتاح»

يبدأ القسم الأول ببطاقة «معلومات المفتاح» وتحتها اسم المفتاح. ويضم حقلين أساسيين:

• المفتاح العام: يعرّف نظامك عند الاتصال.
• المفتاح السري: يثبت أن الطلب صادر فعلاً من نظامك.

يحتاج المطور إلى المفتاحين معاً لإعداد الربط في النظام الخارجي. فكّر فيهما كاسم مستخدم وكلمة مرور مخصصين للأنظمة لا للبشر.

الخطوة 2: اعرض المفاتيح أو انسخها، وافتح التوثيق

تظهر المفاتيح مخفية افتراضياً حمايةً لها من الأعين القريبة. وتستطيع بضغطة:

• عرض المفتاح للتحقق من قيمته.
• نسخ المفتاح للصقه مباشرة في إعدادات النظام الخارجي.

وتحت المفتاحين يظهر رابط API الأساسي، وهو العنوان الذي تبدأ منه الطلبات، وزر «عرض توثيق API» الذي يفتح مرجع المطورين.

الخطوة 3: اعرف أين سيذهب المحتوى في «مكان المحتوى»

يجيب قسم «مكان المحتوى» عن سؤال مهم قبل بدء الربط: أين ستذهب الملفات؟ المجلدات والمستندات التي تُنشأ عبر الواجهة البرمجية تظهر داخل مجلد «التكاملات» المشترك مع المنشأة، وتُنظّم الملفات فيه في مجلدات فرعية تلقائياً.

هذا يمنحك نقطة تجميع واحدة لكل ما يصل من الأنظمة الأخرى. ومن هناك يمكنك مراجعة الملفات، ونقلها إلى مجلداتها النهائية، أو بدء سير عمل عليها.

الخطوة 4: راجع حد الطلبات، وقيّد الوصول بعناوين IP

في أسفل بطاقة المفتاح تجد:

• تاريخ الإنشاء: متى أُنشئ المفتاح.
• حد الطلبات: عدد الطلبات المسموح بها في الدقيقة لهذا المفتاح. يحمي النظام من الضغط الزائد، ويساعد المطور على ضبط وتيرة الإرسال.
• «إلغاء المفتاح»: يوقف صلاحية المفتاح. استخدمه فوراً إذا شككت في تسريبه، أو عند إيقاف التكامل.

وتحتها بطاقة «قائمة عناوين IP المسموح بها». أضف فيها عناوين الخوادم التي ستتصل بمستند، عنواناً مفرداً أو نطاقاً من العناوين، ثم اضغط «إضافة عنوان IP». وإذا تركت القائمة فارغة فسيُسمح بالطلبات من جميع العناوين.

الخطوة 5: تابع «إحصائيات الاستخدام»

يعرض آخر قسم صورة استخدام المفتاح خلال آخر 7 أيام:

• طلبات اليوم: عدد الطلبات منذ بداية اليوم.
• طلبات الشهر: إجمالي الطلبات خلال الشهر.
• آخر طلب: متى استُخدم المفتاح آخر مرة، أو «لم يستخدم بعد» إذا لم يُستخدم.
• رسم بياني للاستخدام: عدد الطلبات لكل يوم من أيام الأسبوع.

اقرأ هذه الأرقام كمؤشر صحة للربط. انخفاض مفاجئ إلى الصفر قد يعني توقف النظام الخارجي عن الإرسال. وارتفاع غير مبرر قد يعني خطأ في برمجة الربط، أو استخداماً غير مصرح به.

الخيارات وتأثيرها

سيناريوهات استخدام عملية

سيناريو: شركة تجارية تؤرشف فواتير نظام المحاسبة تلقائياً

الموقف: يصدر نظام المحاسبة مئات الفواتير شهرياً، وتريد الإدارة المالية أرشفتها في مستند دون تدخل يدوي.

ما تفعله في مستند:

1. افتح «تكامل API» وانسخ المفتاحين العام والسري.
2. سلّم المطور رابط API الأساسي وزر «عرض توثيق API».
3. أضف عنوان خادم نظام المحاسبة في قائمة عناوين IP.
4. تابع «طلبات اليوم» بعد التشغيل للتأكد من وصول الفواتير.

النتيجة: تصل الفواتير إلى مجلد «التكاملات» تلقائياً، ويتولى الفريق المالي تنظيمها ومراجعتها.

سيناريو: مستشفى يربط نظام المعلومات الصحية

الموقف: يريد المستشفى حفظ التقارير الإدارية الصادرة من نظامه الداخلي في مستند، مع ضوابط أمان صارمة.

ما تفعله في مستند:

1. أضف نطاق عناوين الشبكة الداخلية للمستشفى في قائمة عناوين IP.
2. سلّم المفاتيح لفريق التقنية عبر قناة آمنة.
3. راجع «آخر طلب» يومياً خلال الأسبوع الأول.

النتيجة: ربط فعال لا يقبل الطلبات إلا من شبكة المستشفى.

سيناريو: جهة حكومية تتعامل مع مفتاح مشتبه بتسريبه

الموقف: لاحظ مسؤول أمن المعلومات ارتفاعاً غير معتاد في الرسم البياني لا يتوافق مع نشاط الأنظمة المعروفة.

ما تفعله في مستند:

1. قارن «طلبات اليوم» بالمعدل المعتاد في الرسم البياني.
2. اضغط «إلغاء المفتاح» فوراً لإيقافه.
3. راجع قائمة عناوين IP وأضف العناوين المعتمدة فقط قبل إعادة تشغيل الربط.

النتيجة: يتوقف الوصول المشبوه فوراً، ويُستأنف الربط لاحقاً بضوابط أشد.

سيناريو: شركة مقاولات تختبر الربط قبل الإطلاق

الموقف: فريق تطوير خارجي يبني ربطاً بين نظام إدارة المشاريع ومستند.

ما تفعله في مستند:

1. شارك التوثيق مع الفريق، وابدأ بقائمة عناوين تضم خادم الاختبار فقط.
2. راقب ظهور الملفات في مجلد «التكاملات».
3. عند الانتقال للتشغيل الفعلي، استبدل عنوان خادم الاختبار بعناوين خوادم الإنتاج.

النتيجة: اختبار منضبط دون فتح الوصول لكل العناوين.

علاقتها بالميزات الأخرى

• التكاملات: تعرض التكاملات الجاهزة عبر REST API وWebhooks، وتوصلك بفريق مستند إن فضّلت التفعيل المُدار.
• المجلدات: يظهر فيها مجلد «التكاملات» الذي يتجمع فيه محتوى الواجهة البرمجية.
• محتوى المجلد: من داخل مجلد «التكاملات» تراجع الملفات الواردة وتنقلها إلى أماكنها.
• وكيل المستندات الذكي: يحلل الملفات الواردة ويستخرج نصها وبياناتها مثل أي ملف آخر.
• الصلاحيات: احصر الوصول إلى صفحة تكامل API في الأدوار التقنية المعنية فقط.
• النشاط: سجل الحركات في النظام يكمّل إحصائيات الاستخدام في المراقبة.

نصائح وأفضل الممارسات

1. عامل المفتاح السري ككلمة مرور: لا تشاركه في البريد أو المحادثات أو المستندات.
2. أضف عناوين IP لخوادمك دائماً في بيئة الإنتاج، ولا تترك القائمة فارغة.
3. اقرأ «توثيق API» كاملاً قبل البدء، والتزم بحد الطلبات في تصميم الربط.
4. راجع «إحصائيات الاستخدام» أسبوعياً على الأقل، وانتبه للتغيرات المفاجئة.
5. خطط لتنظيم مجلد «التكاملات»: حدد من يراجعه ومتى تُنقل الملفات منه.
6. ألغِ المفتاح فوراً عند مغادرة مطور كان يملك قيمته، أو عند الشك في تسريبه.
7. احصر صلاحية الوصول إلى هذه الصفحة في عدد محدود من المسؤولين.

تنبيهات وأخطاء شائعة

الأسئلة الشائعة

كيف أحصل على مفتاح API في مستند؟

افتح «الإعدادات» ← «تكامل API». تجد في «معلومات المفتاح» المفتاح العام والمفتاح السري، ويمكنك عرضهما أو نسخهما بضغطة.

ما الفرق بين المفتاح العام والمفتاح السري؟

المفتاح العام يعرّف النظام المتصل، والمفتاح السري يثبت هويته. يُستخدمان معاً، ويجب حماية السري كما تُحمى كلمة المرور.

أين تُحفظ الملفات المرفوعة عبر API؟

تظهر المجلدات والمستندات المنشأة عبر الواجهة داخل مجلد «التكاملات» المشترك مع المنشأة، وتُنظم في مجلدات فرعية تلقائياً.

كيف أقيّد الوصول إلى API بعناوين محددة؟

أضف عناوين خوادمك أو نطاقاتها في «قائمة عناوين IP المسموح بها» بزر «إضافة عنوان IP». القائمة الفارغة تسمح بكل العناوين.

ماذا أفعل إذا تسرب المفتاح السري؟

اضغط «إلغاء المفتاح» فوراً لإيقافه، ثم راجع قائمة عناوين IP وإحصائيات الاستخدام قبل استئناف الربط.

هل يوجد حد لعدد الطلبات؟

نعم، يظهر «حد الطلبات» في بطاقة المفتاح بعدد الطلبات المسموح بها في الدقيقة.

كيف أعرف أن الربط يعمل؟

من «إحصائيات الاستخدام»: طلبات اليوم والشهر، ووقت آخر طلب، والرسم البياني لآخر 7 أيام.

أين أجد توثيق API لمستند؟

من زر «عرض توثيق API» في قسم معلومات المفتاح بصفحة تكامل API.

الخلاصة

• صفحة «تكامل API» توفر المفتاحين العام والسري والرابط الأساسي والتوثيق لربط أنظمتك بمستند.
• المفاتيح مخفية افتراضياً، وتُعرض أو تُنسخ بضغطة.
• المحتوى الوارد عبر الواجهة يتجمع في مجلد «التكاملات» بمجلدات فرعية منظمة.
• «إلغاء المفتاح» وقائمة عناوين IP أداتا الأمان الأساسيتان للربط.
• «إحصائيات الاستخدام» تكشف توقف الربط أو الاستخدام غير المعتاد مبكراً.

جرّب الآن مجاناً: أنشئ حساب منشأتك في مستند