واجهة برمجة التطبيقات و الويب هوكس
تتوفر إمكانية تحميل وقراءة المستندات عبر واجهة برمجة التطبيقات 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 مقيد بعشر استفسارات في الثانية.