مرجع واجهة Connect REST API

نظرة سريعة

يعرِض ⁨NextPDF Connect⁩ سجل أدواته عبر ⁨HTTP⁩ من خلال نقل ⁨REST⁩ موصوف بعقد ⁨OpenAPI 3.1.⁩ تمثل هذه الصفحة مرجع هذه الواجهة: عنوان ⁨URL⁩ الأساسي، وطريقة المصادقة، ومجموعات العمليات، ونموذج الأخطاء. تُنشَر المواصفة الكاملة القابلة للقراءة آليًا كي تتمكن من تحميلها في مستكشف تفاعلي، أو مولّد عملاء، أو عميل طلبات، دون نسخ أي شيء يدويًا.

للاطّلاع على فهرس الأدوات المستقل عن النقل (العمليات نفسها عبر ⁨Model Context Protocol⁩ و⁨gRPC⁩، إضافةً إلى ⁨REST⁩)، راجع مرجع ⁨Connect API⁩. وللاطّلاع على مسار ⁨RoadRunner⁩ والنشر وإعداد المصادقة، راجع دليل نقل ⁨REST⁩.

عنوان ⁨URL⁩ الأساسي والمصادقة

يستمع نقل ⁨REST⁩ على المضيف والمنفذ المُهيّأين في نشرك. في التشغيل المحلي يكون ذلك http://localhost:8080؛ وفي الإنتاج يكون العنوان الموضوع أمام تجمّع العمّال لديك.

تستخدم المصادقة رمزًا حاملًا (⁨bearer token⁩). أرسل مفتاح ⁨API⁩ في ترويسة Authorization مع كل طلب إلى مسار مُقيَّد حسب الفئة:

curl --request POST \
  --url http://localhost:8080/api/v1/render \
  --header "Authorization: Bearer $NEXTPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operations":[{"op":"add_text","text":"Hello from NextPDF Connect"}]}'

لا تتطلب فحوص الحيوية والجاهزية، وهي للقراءة فقط، أي رمز.

العمليات

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

الصحة ودورة الحياة

الطريقة	المسار	الغرض
⁨GET⁩	`/healthz`	فحص الحيوية. بدون مصادقة.
⁨GET⁩	`/readyz`	فحص الجاهزية (التبعيات جاهزة وتجمّع العمّال جاهز). بدون مصادقة.
⁨GET⁩	`/api/v1/capabilities`	الأدوات والفئات التي يعرضها هذا النشر فعليًا. استعلِم عنها أولًا.

العرض والمستندات

الطريقة	المسار	الغرض
⁨POST⁩	`/api/v1/render`	عرض مستند من قائمة عمليات مرتّبة وإعادة ملف ⁨PDF.⁩
⁨POST⁩	`/api/v1/extract-text`	استخراج المحتوى النصي من ملف ⁨PDF.⁩
⁨POST⁩	`/api/v1/merge`	دمج عدة مدخلات ⁨PDF⁩ في مستند واحد.
⁨POST⁩	`/api/v1/split`	تقسيم ملف ⁨PDF⁩ إلى عدة مستندات.

المهام غير المتزامنة

الطريقة	المسار	الغرض
⁨POST⁩	`/api/v1/jobs`	إرسال عملية طويلة الأمد كمهمة.
⁨GET⁩	`/api/v1/jobs/{id}`	استطلاع حالة المهمة.
⁨GET⁩	`/api/v1/jobs/{id}/result`	استرداد نتيجة المهمة المكتملة.

الجلسات

تُبقي الجلسات مستندًا مفتوحًا عبر عدة استدعاءات، لتبنيه تدريجيًا وتعرضه مرة واحدة في النهاية.

الطريقة	المسار	الغرض
⁨POST⁩	`/api/v1/sessions`	فتح جلسة.
⁨GET⁩ / ⁨DELETE⁩	`/api/v1/sessions/{sessionId}`	التحقق من جلسة أو إغلاقها.
⁨POST⁩	`/api/v1/sessions/{sessionId}/pages`	إضافة صفحة.
⁨POST⁩	`/api/v1/sessions/{sessionId}/text`	إضافة نص.
⁨POST⁩	`/api/v1/sessions/{sessionId}/images`	إضافة صورة.
⁨POST⁩	`/api/v1/sessions/{sessionId}/tables`	إضافة جدول.
⁨POST⁩	`/api/v1/sessions/{sessionId}/html`	إضافة ⁨HTML⁩ مُعروض.
⁨POST⁩	`/api/v1/sessions/{sessionId}/font`	تعيين الخط النشط.
⁨POST⁩	`/api/v1/sessions/{sessionId}/render`	عرض مستند الجلسة.

عمليات الإصدار التجاري

تُسجَّل هذه المسارات فقط عند تثبيت الإصدار التجاري المطابق. كثير منها مُقيَّد بالموافقة عبر تدفّق تأكيد يتضمن إشراك الإنسان؛ راجع فئات المخاطر.

الطريقة	المسار	الغرض
⁨POST⁩	`/api/v1/sign`	تطبيق توقيع رقمي.
⁨POST⁩	`/api/v1/fill-form`	تعبئة نموذج تفاعلي.
⁨POST⁩	`/api/v1/redact`	تنقيح المحتوى.
⁨POST⁩	`/api/v1/compare`	مقارنة مستندَي ⁨PDF.⁩
⁨POST⁩	`/api/v1/check-accessibility`	تشغيل فحص بنيوي لإمكانية الوصول.
⁨POST⁩	`/api/v1/optimize`	تحسين مستند وتقليص حجمه.

نموذج الأخطاء

يستخدم نقل ⁨REST⁩ رموز حالة ⁨HTTP⁩ بالدلالات المحددة في ⁨RFC 9110⁩: 2xx للنجاح، و4xx لطلبٍ يجب على المُستدعي إصلاحه (400 نص طلب مُشوَّه، و401 رمز مفقود أو غير صالح، و403 فئة أو موافقة مرفوضة، و404 مسار أو مهمة غير معروفين، و409 تعارض في التكرار الآمن، و422 طلب صحيح البنية لا يستطيع المحرك معالجته)، و5xx لإخفاق من جانب الخادم. يتضمن ردّ 401 تحدّي WWW-Authenticate.

تأتي نصوص الأخطاء على هيئة مستندات application/problem+json وفق ⁨RFC 9457⁩ (تفاصيل المشكلة لواجهات ⁨HTTP⁩ البرمجية): type ثابت، وtitle قصير، وstatus رقمي، وdetail قابل للقراءة البشرية. طابِق وفق type، لا وفق سلسلة detail. راجع أيضًا ⁨RFC 9110⁩ (دلالات ⁨HTTP⁩) و⁨RFC 9457⁩ للتعريفات المعيارية.

أرسِل الطلبات التي تغيّر الحالة مع ترويسة Idempotency-Key كي يُعالَج الطلب المُعاد مرة واحدة فقط.

المواصفة القابلة للقراءة آليًا

العقد الكامل منشور كمستند ⁨OpenAPI 3.1⁩ ثابت:

https://nextpdf.dev/docs/openapi/nextpdf-connect.yaml

استخدمه بوصفه مصدر الحقيقة الوحيد لواجهة ⁨REST⁩:

افتح مستكشف واجهة ⁨API⁩ التفاعلي — مرجع ⁨Scalar⁩ داخل المتصفح، مستضاف ذاتيًا ومُولَّد من هذا العقد — لقراءة كل عملية وتجربتها مع مخططات طلبها واستجابتها.
استورده إلى عميل طلبات مثل ⁨Postman⁩ أو ⁨Insomnia.⁩
ولِّد عميلًا مضبوط الأنواع للغتك باستخدام مولّد ⁨OpenAPI.⁩

المستند عقد ثابت مُثبَّت بإصدار الحزمة. لا يُقدَّم عبر نقطة نهاية حيّة، لذا يبقى مستقرًا عبر عمليات النشر.

راجع أيضًا

مرجع ⁨Connect API⁩ — فهرس الأدوات الكامل عبر ⁨MCP⁩ و⁨REST⁩ و⁨gRPC.⁩
دليل نقل ⁨REST⁩ — مسار ⁨RoadRunner⁩، ومصادقة الحامل، وتوجيه الفئات.
نظرة عامة على ⁨NextPDF Connect⁩ — تعريف الخادم وكيفية تشغيله.