AuraDoc
تسجيل الدخولحساب

المدونة

خطافات الويب وواجهة REST في AuraDoc

اربط AuraDoc بأنظمتك بمفاتيح API محددة النطاق وخطافات ويب موقّعة وسجل للتسليم وإعادة محاولة تلقائية.


يريد كل فريق عاجلًا أو آجلًا أن تتحدث مستنداته مع بقية برمجياته: رفع ملف من سكربت، أو بدء سير عمل من مجدوِل، أو معرفة اللحظة التي ينتهي فيها معالجة مستند. يقدم AuraDoc طريقتين متكاملتين. تتيح واجهة REST لأنظمتك أن تطلب من AuraDoc فعل شيء، وتتيح خطافات الويب لـ AuraDoc أن يُعلم أنظمتك بأن شيئًا حدث. يستعرض هذا المقال الطريقتين وتفاصيل الأمان المهمة في الإنتاج.

مفاتيح API والنطاقات

يبدأ كل شيء بمفتاح API. أنشئ واحدًا من Dashboard › Settings › API keys وسمِّه واختر نطاقاته. تحدّ النطاقات مما يستطيع المفتاح فعله، فالمفتاح المستخدم لرفع الملفات فقط لا يحتاج إلى صلاحية إدارة أي شيء آخر. ولا يستطيع المفتاح إنشاء مفتاح آخر بنطاقات أوسع من نطاقاته، والصلاحيات الفعلية هي دائمًا المشتركة بين المفتاح ودور الشخص كما في أدوار الفريق وصلاحياته. وتحمل الطلبات المفتاح في ترويسة Authorization بوصفه رمز Bearer.

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

ما تستطيع الواجهة فعله

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

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

خطافات الويب الصادرة

للحصول على إشعارات فورية افتح Dashboard › Webhooks وأضف نقطة نهاية. تختار الأحداث التي تهمك من قائمة تشمل إنشاء المستند وتصنيفه وحذفه، واكتمال OCR والترجمة أو فشلهما، وأحداث سير العمل، وتحذيرات حصة التخزين، وأحداث التوقيع. وعند الحفظ يعرض AuraDoc سر التوقيع مرة واحدة فقط. انسخه فورًا إلى الخدمة المستقبِلة؛ وإن فقدته فبدّل السر ليُنشأ سر جديد، ويُسجَّل التبديل في سجل التدقيق.

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

التحقق من التوقيعات ومعالجة الأعطال

كل عملية تسليم موقّعة. يحسب AuraDoc قيمة HMAC-SHA256 على الطابع الزمني والمحتوى الخام باستخدام سرك، ويرسل النتيجة في ترويسة التوقيع، مع ترويسات لاسم الحدث ومعرّف الخطاف ومعرّف التسليم والطابع الزمني وعدد المحاولات. ينبغي أن يعيد المستقبِل حساب التوقيع من المحتوى الخام، ويقارنه في زمن ثابت، ويرفض الطلبات ذات الطابع الزمني القديم جدًا. وبذلك لا يستطيع أحد تزوير حدث إلى نقطة نهايتك حتى لو عرف عنوانها.

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

العودة إلى المدونة