مكان وجود المواصفات
يتم إنشاء مواصفات نقاط النهاية (Endpoints) بشكل حي من كتالوج API. يرجى استخدام هذه الملفات بدلاً من نسخ قوائم نقاط النهاية من المقالات:
- فهرس مضغوط لعملاء الذكاء الاصطناعي:
https://api.paperoffice.ai/latest/docs/llms.txt - المرجع الكامل:
https://api.paperoffice.ai/latest/docs/llms-full.txt - OpenAPI 3.1:
https://api.paperoffice.ai/latest/docs/openapi.json - مهارة الوكيل (Agent skill):
https://api.paperoffice.ai/latest/docs/skill.md - مجموعة Postman:
https://api.paperoffice.ai/latest/docs/postman
مسارات التوثيق عامة ولا تتطلب أي رمز (Token). قم باستيراد عنوان URL الخاص بـ Postman في Postman أو VS Code أو Bruno، وقم بتنزيله مرة أخرى عند تغيير إصدار التوثيق. عنوان الأساس للإنتاج هو https://api.paperoffice.ai/latest؛ استخدم /dev لأغراض التطوير فقط.
بداية سريعة مع مساعد برمجة بالذكاء الاصطناعي: قدم له عنوان ملف llms-full.txt ووصف الوظيفة التي تحتاجها، على سبيل المثال، وظيفة ترسل صورة وتعيد النص المعترف به.
المصادقة وأنواع الرموز
تتطلب معظم نقاط نهاية المنتج رمز حامل (Bearer token) في رأس المصادقة (Authorization header). يمكنك إنشاء الرموز في تطبيق PaperOffice تحت حساب → API.
- المفتاح النظامي (po_sk_): تكامل من خادم إلى خادم مع وصول كامل إلى API. لا تستخدمه أبداً في المتصفح.
- رمز المستخدم (po_ut_): نطاق مستخدم واحد، على سبيل المثال لاستخدام MCP. تتبع الصلاحيات المستخدم والترخيص.
- رمز المجموعة (po_gt_): يرث صلاحيات وقائمة السماح (Whitelist) لمجموعة المستخدمين.
- المفتاح القابل للنشر (po_pk_): للاستخدام في المتصفح. كل طلب يحتاج إلى مصدر (Origin) أدخله مالك المفتاح، وميزانية إجمالية للمفتاح تحد من الاستهلاك، وتظل عمليات الحذف وإدارة الحساب وإدارة المفاتيح وتغييرات الدفع محظورة. لا يُسمح باستخدامه مع MCP.
بدون رمز، يمكن الوصول فقط إلى نقاط نهاية البنية التحتية مثل المواصفات، وفحص الصحة (Health check)، واختبار الاتصال. يتم الرد على طلب المنتج بدون رمز بـ HTTP 403 والرمز TIER_RESTRICTED، وليس بـ HTTP 401.
المهام: الانتظار، الاستعلام (Polling) والنتائج
تتم المعالجة على شكل مهام. تستخدم مسارات المهام النمط handler___command بثلاثة شرطات سفلية، على سبيل المثال POST /job/add/paperoffice_aiocr___generate للاعتراف بالنص. يتم رفض التدوين النقطي (Dot notation) بالخطأ JOB_CONFIG_INVALID.
- بشكل افتراضي، يحتفظ الطلب بالاتصال لفترة من الوقت. إذا انتهت المهمة في الوقت المحدد، تحصل على النتيجة مباشرة. وإلا، تحصل على HTTP 202 مع معرف المهمة وعنوان الاستعلام (Poll address)، وتظل المهمة قيد التشغيل.
- HTTP 202 هو نجاح وليس خطأ. قم بالاستعلام عن
GET /job/get/{job_id}كل 5 إلى 10 ثوانٍ حتى تصبح الحالة مكتملة. تكون النتيجة بعد ذلك في job_result. - مع client_wait=false، تحصل على معرف المهمة فوراً وتبدأ الاستعلام من البداية.
- جميع الردود بصيغة JSON. يجب على العملاء قراءة حقل الرمز المستقر (stable code) وليس نص الرسالة المحلي.
يمكنك رؤية مهام API المجدولة، والجارية، والمكتملة في التطبيق تحت حساب → API → قائمة انتظار المهام. القائمة الكاملة لأكواد الأخطاء موجودة في المواصفات؛ الحالات الشائعة هي المعاملات المفقودة أو غير الصالحة (400)، أو رمز مفقود أو غير صالح (401)، أو عدم كفاية Credits (402)، أو إجراء محظور (403) وعدد كبير جداً من الطلبات (429، مع مراعاة Retry-After).
SLA للبدء: متى تبدأ المهمة
الحقل الاختياري processing_lane يتحكم في متى تبدأ المهمة في قائمة الانتظار، وليس متى تنتهي. يتحكم client_wait فيما إذا كان الاتصال سينتظر النتيجة؛ الحقلان مستقلان عن بعضهما البعض.
بدون processing_lane، ينطبق الافتراضي الخاص بمساحة العمل، وإلا يكون الجهد الأفضل (best effort). تتضمن كل خطة الجهد الأفضل بدون رسوم إضافية. مسارات البدء الأسرع اختيارية وتكلف أكثر. المسارات الحالية وأسعارها متاحة بشكل حي من خلال قائمة أسعار API؛ التفاصيل موجودة في توثيق API.
الويب هوك (Webhooks)
تستقبل نقاط نهاية الويب هوك أحداث المهام والحسابات، على سبيل المثال job.completed، job.failed، job.progress وأحداث المستندات ومساحات العمل والمهام. إشعارات الحساب مثل المحفظة الفارغة أو المفتاح الملغى ليست أحداث رسائل تلقائية.
- يتم توقيع حمولات البيانات باستخدام HMAC-SHA256 في رأس X-Paperoffice-Signature. احسب التوقيع على جسم الطلب الخام باستخدام سر الويب هوك الخاص بك، وارفض الطلب إذا لم يتطابق.
- يمكن تسجيل وعرض وتحديث واختبار وحذف إشعارات الويب هوك عبر API.
الفوترة والاستخدام
تستهلك استدعاءات API Credits من الحصة المشتركة للمنظمة، وهي نفس الحصة الخاصة بالتطبيق. بعض استعلامات الحالة والصحة غير مشمولة بالرسوم؛ وتفاصيل ذلك موجودة في وثائق API. يتم فرض الرسوم على الاستدعاءات المرفوضة بسبب إدخال غير صالح؛ أما الاستدعاءات التي تم فرض حد معدل عليها فلا تُحسب.
ترى الاستدعاءات مع Credits الخاصة بها تحت واجهة برمجة التطبيقات والمطورون → استخدام API: يعرض السجل المباشر كل طلب، ويعرض السجل التاريخي الاستخدام حسب التاريخ والمعالج والإجراء. عندما تنفد Credits، يتم رفض الاستدعاءات حتى يتم شحن الرصيد أو تفعيل إعادة الشحن التلقائي. تعتمد حدود المعدل على خطتك؛ وتُوصف الحدود الحالية ورؤوس الاستجابة في وثائق API. المزيد حول Credits: الفوترة وCredits في PaperOffice AI.
بروتوكول سياق النموذج (MCP): ربط مساعدي الذكاء الاصطناعي
يربط بروتوكول سياق النموذج (MCP) بين مساعدي الذكاء الاصطناعي مثل Claude وChatGPT وGrok وCursor مباشرة مع PaperOffice. المصادقة تتم عبر OAuth 2.1 أو رمز مستخدم أو مجموعة؛ ومفاتيح النظام والمفاتيح القابلة للنشر محظورة لبروتوكول سياق النموذج (MCP). مضيف الإنتاج هو https://mcp.paperoffice.ai، مع ملفات تعريف مثل /claude و/chatgpt و/grok و/cursor و/dms. الإعدادات والأذونات وتدفق البيانات: استخدام PaperOffice مع Claude وChatGPT وGrok وCursor.
الأسئلة المتكررة
- أين أجد جميع نقاط النهاية؟ في ملفات llms.txt وllms-full.txt وملف OpenAPI. يتم إنشاؤها مباشرة.
- أي رمز يجب أن يستخدمه خادومي؟ مفتاح نظام، ولا يُستخدم أبداً في المتصفح. للمتصفح، استخدم مفتاحاً قابلاً للنشر مع مصدر وميزانية.
- هل HTTP 202 خطأ؟ لا. المهمة لا تزال قيد التشغيل؛ قم بالاستفسار عن النتيجة.
- هل المسارات الأسرع تكلفة أعلى؟ نعم. الجهد الأفضل (best effort) لا يفرض رسوماً إضافية؛ والأسعار الحالية موجودة في قائمة أسعار API.
- هل يتم فرض رسوم على الاستدعاءات المرفوضة؟ تُفرض الرسوم على الاستدعاءات المرفوضة بسبب إدخال غير صالح؛ أما الاستدعاءات التي تم فرض حد معدل عليها فلا تُحسب.