واجهة برمجة التطبيقات والويب هوك
تحميل وقراءة الوثائق متاحة عبر واجهة برمجة التطبيقات REST. إدارة الحساب، الملفات، العلامات والاتصالات تبقى في التطبيق.
مفتاح
يتم إنشاؤه في الإعدادات → للمطورين. سيظهر المفتاح مرة واحدة عند الإنشاء — ثم لا يظهر مرة أخرى لأن بصمة الإصبع فقط هي ما يتم حفظه. المفتاح المفقود لا يتم استعادته، يتم إنشاء مفتاح جديد ويتم حذف القديم. يمكن أن يكون لديك خمسة مفاتيح، كل منها مع فترة صلاحية اختيارية تصل إلى عامين.
يتم إرسال المفتاح في رأس X-API-Key.
ماذا تستطيع واجهة برمجة التطبيقات تفعل
| العملية | الوصف |
|---|---|
POST /api/upload | تحميل ملف مع الاختيارات: التنسيق، الاتجاه، النوع، العملة، المخطط، الملف، ويب هوك |
POST /api/upload/url | نفس الشيء من عنوان عام؛ سنقوم بتحميل الملف بأنفسنا |
GET /api/jobs | قائمة الوثائق مع الفلاتر والترتيب |
GET /api/jobs/{id} | الحالة، البيانات المقروءة، النتائج والنتيجة بالتنسيق المستهدف |
GET /api/jobs/{id}/original | الملف المحمل |
DELETE /api/jobs/{id} | حذف إلى سلة المهملات |
Excel و PDF يتم إعادتهما في النتيجة كـ Base64. من لا يحتاج النتيجة،
يمكنه إرسال includeResult=false، مما يوفر التحويل على الخادم.
يوجد وصف الواجهة بتنسيق OpenAPI على العنوان /api/docs؛ الرابط موجود في
الإعدادات بجوار المفاتيح. يتم توليد الوصف من الشيفرة التي تعمل، لذا فهو يتوافق
مع ما تقوم به واجهة برمجة التطبيقات.
التحقق من الوثائق من واجهة برمجة التطبيقات
يتم التحقق قبل الإرسال بشكل افتراضي حتى للوثائق المحملة بالمفتاح: الوثيقة تنتظر التأكيد في التطبيق وسيرسل ويب هوك فقط بعد ذلك. من يقوم ببناء تكامل لا يوجد أحد يجلس أمام الشاشة، يمكنه في الإعدادات → التحقق قبل الإرسال إزالة قناة واجهة برمجة التطبيقات، أو إيقاف التحقق.
MCP
للوكلاء الذكاء الاصطناعي، يوجد على العنوان /api/mcp خادم MCP بنفس المفتاح.
يمكنه قراءة الوثائق والبحث عنها، لكن لا يمكنه تحميلها؛ سيعيد التحميل كأمر
جاهز يقوم الوكيل بتشغيله بنفسه.
ويب هوك
بدلاً من الاستعلام عن الحالة، اجعل النتيجة تُرسل إليك عندما تكون جاهزة.
يتم إعداد العنوان لحساب كامل في الإعدادات → للمطورين، أو عند التحميل الفردي
من خلال المعامل targetWebhookUrl. زر في الإعدادات سيرسل رسالة اختبار.
سيتم إرسال POST مع JSON: معرف الوثيقة، اسم الملف، التنسيق والنتيجة بالتنسيق المستهدف.
عند اجتياز الوثيقة للتحقق أو إعادة معالجتها، ستأتي ويب هوك مرة أخرى مع علامة التصحيح
(IsCorrection).
لا يتم توقيع الرسالة. تحقق من المرسل من خلال إضافة توكن سري خاص بك إلى العنوان. يتم رفض العناوين إلى الشبكات الخاصة.
يتم تكرار التسليم غير الناجح مع زيادة التأخير، أحد عشر محاولة خلال حوالي أربع ساعات ونصف. كل محاولة موجودة في النشاط مع الرد من جانبك؛ لدى الوثيقة في القائمة أيقونة مع نتيجة التسليم.
الحدود
لا توجد حدود خاصة بواجهة برمجة التطبيقات على عدد الاستدعاءات في الدقيقة؛ تقيد التحميلات عبر الاعتمادات، حجم الملف حسب التعرفة وعشرون صفحة لكل وثيقة. يأتي الرفض كخطأ 400 مع كود يوضح السبب. يتم حصر خادم MCP بعشر استعلامات في الثانية.