NextPDF Connect — وسيلة نقل REST

لمحة سريعة

تُشغِّل وسيلة نقل ⁨REST⁩ (النقل التمثيلي للحالة) الملف bin/nextpdf-server داخل تجمُّع عُمَّال ⁨RoadRunner⁩ لطلبات ⁨HTTP⁩. يعرّف مستند ⁨OpenAPI 3.1⁩ هذه الواجهة. تُصادق وسيلة النقل كل طلب لا يخص فحوص الصحة بمفتاح ⁨API⁩ من نوع الحامل (⁨bearer⁩)، وتُقيِّد مسارات ⁨Pro⁩ و⁨Enterprise⁩ بحسب الطبقة المُثبَّتة.

التثبيت

composer require nextpdf/server
./vendor/bin/rr get-binary

نظرة مفاهيمية عامة

يمرّ كل طلب عبر سلسلة وسطاء (⁨middleware⁩) وفق توصية ⁨PHP⁩ المعيارية 15 (⁨PSR-15⁩) قبل أن يصل إلى مُعالِج: إسناد مُعرِّف الطلب، وفرض حدود حجم جسم الطلب وحمولة الطبقة، ومشاركة الموارد عبر الأصول المختلفة (⁨CORS⁩)، والمصادقة، وتفويض القدرات، وتحديد المعدّل لكل عنوان ⁨IP⁩ ولكل عميل، وعدم التكرارية (⁨idempotency⁩)، ومهلة زمنية. إذا لم يستطع وسيط ⁨PSR-15⁩ إنتاج الاستجابة بنفسه، فإنه يُفوِّض مُعالِج الطلب المُقدَّم (⁨PSR-15⁩ §2.2 MiddlewareInterface::process، البند psr_15_handlers#2.2.p14). كائنات طلب ⁨PSR-7⁩ في هذا المسار غير قابلة للتغيير: فأي استدعاء يُغيِّر الحالة يُعيد نسخة جديدة بدلاً من تعديل الأصل (⁨PSR-7⁩ §3.2.1).

يُبنى جدول المسارات عند الإقلاع وفق بيئة التشغيل. تُسجَّل مسارات ⁨Core⁩ دائماً. تُسجَّل مسارات عمليات ⁨Pro⁩ فقط عند تثبيت ⁨Pro⁩ أو ⁨Enterprise⁩. تُسجَّل مسارات ⁨Enterprise⁩ فقط عند تثبيت ⁨Enterprise⁩. ولا تُسجَّل مسارات الجلسات إلا عند تمكين الجلسات.

واجهة ⁨API⁩

المسارات المُسجَّلة دائماً

الطريقة	المسار	المصادقة
GET	/healthz	لا شيء (فحص الحيوية)
GET	/readyz	لا شيء (فحص الجاهزية)
POST	/api/v1/render	حامل (⁨bearer⁩)
GET	/api/v1/capabilities	حامل (⁨bearer⁩)
POST	/api/v1/jobs	حامل (⁨bearer⁩)
GET	/api/v1/jobs/{id}	حامل (⁨bearer⁩)
GET	/api/v1/jobs/{id}/result	حامل (⁨bearer⁩)
DELETE	/api/v1/jobs/{id}	حامل (⁨bearer⁩)
POST	/api/v1/extract-text · /merge · /split	حامل (⁨bearer⁩)

نقاط نهاية فحوص الصحة آمنة ومخصّصة للقراءة فقط. لا تُحدِث أي تغيير في الحالة، وهي خاصية الطريقة الآمنة المُعرَّفة في طلب التعليقات (⁨RFC⁩) 9110 (⁨RFC 9110⁩ §9.2.1).

المسارات المُقيَّدة بالطبقة (تعتمد على بيئة التشغيل)

يُسجِّل ⁨NextPDF⁩ هذه المسارات فقط عند تثبيت الحزمة المقابلة:

• ⁨Pro⁩ أو ⁨Enterprise⁩ مُثبَّت: /api/v1/sign، /fill-form، /redact، /compare، /check-accessibility، /optimize.
• ⁨Enterprise⁩ مُثبَّت: /api/v1/compliance-check، /forensic-analyze، /ai-certify.

إذا لم تكن طبقة المسار مُثبَّتة، فلا يُسجَّل المسار ولا يُوجَّه الطلب. وإذا كان المفتاح صالحاً لكن طبقته أدنى من طبقة المسار، فيُرفَض الطلب بالرمز 403. وعند إتاحة التوقيع، يوفّر ⁨NextPDF Connect⁩ مع ⁨Pro⁩ التوقيع بمستوى التوقيعات الإلكترونية المتقدمة لـ ⁨PDF⁩ (⁨PAdES⁩) من نوع ⁨baseline-B⁩ (⁨B-B⁩) فقط؛ أما ملفات تعريف التحقق طويل الأمد فليست جزءاً من واجهة وسيلة النقل هذه.

عقد ⁨OpenAPI⁩

تُوزَّع واجهة ⁨REST⁩ كمستند ⁨OpenAPI 3.1⁩ ثابت في openapi/nextpdf-connect.yaml داخل الحزمة. تستخدم مخطط أمان مفتاح ⁨API⁩ من نوع الحامل في ترويسة Authorization (Bearer npk_live_{kid}_{secret}). وتستخدم استجابات الأخطاء مستندات تفاصيل المشكلة وفق ⁨RFC 7807⁩ مع عنوان ⁨URL⁩ في الحقل type لكل حالة.

عرض ⁨OpenAPI⁩ — ⁨Scalar⁩

وفقاً للبند §12 من خطة منصة التوثيق، يعرض موقع التوثيق المُجمَّع مستند ⁨OpenAPI⁩ هذا عبر ⁨Scalar⁩ (@scalar/api-reference). وتُضمِّنه صفحة تكامل ⁨REST⁩ كمكوِّن <ScalarApiReference src=…>. يظلّ openapi/nextpdf-connect.yaml في الحزمة هو مصدر الحقيقة. تسحب عملية بناء الموقع هذا الملف وتعرضه بدلاً من صيانة مرجع نقاط نهاية موازٍ يدوياً. ولا توجد نقطة نهاية لخدمة ⁨OpenAPI⁩ في وقت التشغيل ضمن الخادم؛ فالمستند هو ناتج وقت البناء.

مثال برمجي — بداية سريعة

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

مثال برمجي — الإنتاج

شغِّل الملف الشخصي المُدمَج لتعمل وسيلتا نقل ⁨REST⁩ و⁨gRPC⁩ تحت مُشرِف واحد:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
export NEXTPDF_WORKER_COUNT=8
./vendor/bin/rr serve -c .rr.full.yaml

الحالات الحدّية والتنبيهات

• يُعيد مسار الطبقة الرمز 404 عند غياب الحزمة. لا يُسجَّل المسار، ومن ثَمَّ لا يُطابقه المُوجِّه. وهذا سلوك متوقَّع، وليس فشلاً في المصادقة.

• 401 مقابل 403. يعني 401 أنّ الطلب لا يحمل مفتاحاً صالحاً، وتتضمن الاستجابة ترويسة WWW-Authenticate: Bearer وفق ⁨RFC 9110⁩ §11.6.1. يعني 403 أنّ المفتاح صالح، لكنّ طبقته غير مُخوَّلة لهذه العملية.

• الجلسات مُعطَّلة افتراضياً. توجد مسارات /api/v1/sessions/... فقط عندما يكون NEXTPDF_SESSIONS_ENABLED=true وتكون الأدوات متاحة.

• تبقى العمليات عالية المخاطر مُقيَّدة. يمرّ استدعاء ⁨REST⁩ الذي يُشغِّل أداة ApprovalRequired عبر بوابة التدخل البشري ذاتها التي يمرّ بها بروتوكول سياق النموذج (⁨MCP⁩). انظر /⁨connect/hitl-risk-tiers/.⁩

الأداء

يعالج كل عامل من عُمَّال ⁨RoadRunner⁩ طلباً واحداً في كل مرّة. تشغل عمليات العرض الطويلة والمتزامنة عاملاً طوال مدة تنفيذها. استخدم مسارات المهام غير المتزامنة للأعمال البطيئة كي يتحرّر العُمَّال. حدِّد حجم التجمُّع بناءً على زمن الاستجابة المُلاحَظ؛ انظر /⁨connect/production-usage/.⁩

ملاحظات أمنية

أنهِ أمان طبقة النقل (⁨TLS⁩) أمام مُستمِع ⁨REST⁩. يعمل مُستمِع ⁨HTTP⁩ بنصّ صريح بالتصميم ويتوقّع وجود مُنهٍ أمامه. استخدم مفتاح npk_live_ عشوائياً بدرجة كافية للمصادقة، وخزِّن المفاتيح خارج التحكم بالمصدر، وفضِّل مخزن مفاتيح ملفّي يدعم إعادة التحميل الساخن. انظر /⁨connect/security-and-operations/.⁩

المطابقة

الادّعاء	المصدر	reference_id
يجب أن يحمل 401 تحدّي WWW-Authenticate	⁨RFC 9110⁩ §11.6.1
الطرق الآمنة مخصّصة للقراءة فقط	⁨RFC 9110⁩ §9.2.1
طلبات ⁨PSR-7⁩ غير قابلة للتغيير	⁨PSR-7⁩ §3.2.1
الوسيط الذي لا يستطيع إنتاج الاستجابة يُفوِّض مُعالِج الطلب المُقدَّم	⁨PSR-15⁩ §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

السياق التجاري

لا تظهر مسارات التوقيع والتنقيح (⁨redaction⁩) والمقارنة وإمكانية الوصول والتحسين والامتثال إلا عند تثبيت nextpdf/premium. يبقى نموذج المصادقة دون تغيير؛ أما طبقة المفتاح فهي ما يُحدِّد الوصول.

انظر أيضاً

• /⁨connect/quickstart/⁩ — طلب عرض قابل للتشغيل
• /⁨connect/security-and-operations/⁩ — نمط المصادقة و⁨TLS⁩
• /⁨connect/production-usage/⁩ — المهام، وعدم التكرارية، وتحديد المعدّل
• /⁨transports/mcp/⁩ · /⁨transports/grpc/⁩ — وسائل النقل الأخرى
• /⁨connect/tool-catalog/⁩ — كيف تتطابق مجموعة المسارات مع كتالوج الأدوات