أنشئ أول ملف PDF لك باستخدام NextPDF Connect

لمحة سريعة

ترشدك هذه الوصفة عبر أقصر مسار من جلسة فارغة إلى ملف ⁨PDF⁩ مُصيَّر باستخدام ⁨NextPDF Connect.⁩ ستنشئ مستندًا بحجم ⁨A4⁩ من صفحة واحدة، وتضيف عنوانًا وعنوانًا فرعيًا، ثم تعيد الملف بترميز ⁨base64.⁩ تنجز أدوات ⁨Core⁩ الثلاث العمل: create_pdf وadd_text وoutput_pdf. ولا تحتاج إلى خطوط أو صور أو فئة مرخَّصة.

يرسل ناقل ⁨Connect⁩ كل استدعاء أداة على هيئة طلب، ويعيد نتيجة الأداة على هيئة استجابة. وتظل طبقة النقل مستقلة عن النتيجة التي تُبلِّغ عنها الأداة (⁨PSR-18⁩ §⁨p2⁩).

التثبيت

ثبّت ⁨NextPDF Server⁩ واربط ناقلًا:

composer require nextpdf/server

شغّل الخادم باستخدام الناقل الذي يتوقعه مضيفك: ⁨Model Context Protocol⁩ عبر ⁨stdio⁩ أو ⁨REST⁩ أو ⁨gRPC.⁩ راجع توفّر الناقل أدناه. تنتمي الأدوات في هذه الوصفة إلى ⁨Core.⁩ فهي تأتي مع الخادم، لذلك لا تحتاج إلى حزمة ⁨Pro⁩ أو ⁨Enterprise.⁩

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

جلسة ⁨Connect⁩ هي مخزن مستندات على الخادم مفهرس بحسب document_id. يفتح create_pdf جلسة ويعيد المعرّف. ويستخدم كل استدعاء أداة لاحق ذلك المعرّف. يبدأ المستند بصفحة فارغة واحدة. شجرة الصفحات هي البنية التي يستخدمها القارئ للوصول إلى كل صفحة (⁨ISO 32000-2⁩ §7.7.3). يصيّر output_pdf الجلسة إلى ⁨PDF.⁩ ثم يُتلِف الجلسة افتراضيًا لتحرير الذاكرة.

عند استدعاء add_text دون تحديد صريح لـx أو y، ينساب النص إلى موضعه. يبدأ من المؤشر الحالي، ثم يتقدّم المؤشر بعد كل استدعاء.

سطح ⁨API⁩

يتولى سجل الأدوات حلّ هذه الأدوات عند بدء تشغيل الخادم. الأسماء المعروضة هنا هي أسماء البروتوكول في السجل. ويظل الكتالوج المرجعي هو كتالوج الأدوات المُدمج. تعتمد الأدوات المتاحة على الفئة المثبَّتة، لكن هذه الأدوات الثلاث متوفرة دائمًا في ⁨Core.⁩

الأداة	الدور	فئة المخاطرة
create_pdf	فتح جلسة مستند	آمِنة
add_text	كتابة نص في المستند	تنبيه
output_pdf	تصيير ⁨PDF⁩ وإعادته	موافقة مطلوبة (وضع الملف) / مراجعة (⁨base64⁩)

نموذج التعليمات البرمجية — بدء سريع

يُجري المضيف ثلاثة استدعاءات أدوات بهذا الترتيب:

1. استدعِ create_pdf مع page_size: "A4" وorientation: "portrait"، ومع عنوان المستند ومؤلفه. يعيد الخادم document_id.
2. استدعِ add_text مع ذلك document_id، ونص العنوان، وقيمة كبيرة لـfont_size، وwidth: 0 (عرض المحتوى الكامل)، وalignment: "center".
3. استدعِ output_pdf مع document_id. إذا لم يوجد file_path، يعيد الخادم ⁨PDF⁩ بترميز ⁨base64⁩ ويُتلِف الجلسة.

فيما يلي الحد الأدنى لكائن وسائط create_pdf:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

تتضمن الاستجابة document_id وعدد الصفحات وهندسة الصفحة. تعامل مع المعرّف بوصفه قيمة مبهمة، ولا تستنتج منه أي معنى.

نموذج التعليمات البرمجية — الإنتاج

في بيئة الإنتاج، يتحقق المُستدعي من كل استجابة قبل إجراء الاستدعاء التالي. ولا يعيد أبدًا استخدام document_id بعد أن يتلف output_pdf الجلسة.

1. create_pdf — تأكّد من أن الاستجابة تحتوي على document_id. إذا أعاد الخادم خطأ حدّ الجلسات، فحرّر الجلسات غير المستخدمة وأعِد المحاولة.
2. add_text (العنوان) — تأكّد من أن الاستجابة تحتوي على position.
3. add_text (العنوان الفرعي) — استخدم قيمة أصغر لـfont_size؛ يتابع المؤشر أسفل العنوان.
4. output_pdf — اقرأ حقل base64 وفُكّ ترميزه إلى بايتات. تؤكد الراية destroyed أن الجلسة قد أُزيلت.

يُعاد الملف ضمنيًا (وضع ⁨base64⁩)، لذلك لا يوجد أثر جانبي على نظام الملفات ولا بوابة موافقة بشرية. راجع فئة مخاطرة ⁨HITL⁩.

الحالات الحدّية والمزالق

• الجلسة المُتلَفة. بعد تشغيل output_pdf بالقيمة الافتراضية destroy: true، لا يعود document_id صالحًا. وأي استدعاء لاحق يستخدمه يعيد خطأ مستند غير معروف. أنشئ جلسة جديدة بدلًا من ذلك.
• حجم صفحة غير معروف. يرفض الخادم أي page_size لا يتعرّف عليه، ويعيد خطأً واضحًا. استخدم حجمًا موثَّقًا (⁨A3⁩ أو ⁨A4⁩ أو ⁨A5⁩ أو ⁨A6⁩ أو ⁨Letter⁩ أو ⁨Legal⁩ أو ⁨Tabloid⁩).
• نص فارغ. ينتج عن text الفارغ مُدخل بعرض صفري، لا خطأ. تحقّق من مُدخلاتك قبل الاستدعاء.
• حد الجلسات. يفرض مخزن الذاكرة حدًّا أقصى على عدد الجلسات التي تعمل في وقت واحد. حرّر الجلسات فورًا باستخدام output_pdf.

الأداء

تُصيَّر صفحة واحدة تحتوي على نص فقط ضمن ميزانية الصفحة بهامش مريح، ويكون المُخرَج عادةً بحجم 1–3 ⁨KB.⁩ تستخدم هذه الوصفة ملف تعريف قابلية إعادة الإنتاج بالتصيير المزدوج structural. يتضمن ⁨PDF⁩ قيمة /ID في المُذيِّل وطوابع زمنية تتغير من تشغيل إلى آخر، لذلك تكون المقارنة البنيوية (المُطبَّعة) هي المقارنة الدقيقة.

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

لا يخلّف مسار ⁨base64⁩ أي أثر جانبي على نظام الملفات. أما مسار الإخراج إلى ملف فيخلّف أثرًا، وهو مُقيَّد ببوابة. راجع قسم ⁨HITL.⁩ تعامل مع ⁨base64⁩ المُعاد كمحتوى مستند، لا كقناة موثوقة. فهو بالضبط البايتات التي أنتجتها الأدوات.

المطابقة

البيان	المواصفة	البند	⁨reference_id⁩
يرسل الناقل طلبًا ويتلقّى استجابة بمعزل عن النتيجة.	⁨PSR-18⁩	§⁨p2⁩
يتم الوصول إلى الصفحات عبر شجرة صفحات المستند.	⁨ISO 32000-2⁩	§7.7.3

تصف هذه الوصفة كيفية إنتاج الخادم للمُخرَجات. ولا تؤكّد المطابقة لأي ملف تعريف.

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

غير منطبق — الأدوات الثلاث جميعها من ⁨Core.⁩

توفّر الناقل

الناقل	متوفّر	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	نعم	تُربَط استدعاءات الأدوات بـtools/call في ⁨MCP.⁩
⁨REST⁩	نعم	كل أداة عملية ⁨REST⁩؛ والنتيجة هي متن الاستجابة.
⁨gRPC⁩	نعم	كل أداة استدعاء أحادي.

نتيجة الأداة هي نفسها عبر جميع النواقل؛ يختلف التأطير فقط. وتبقى النتيجة غير الناجحة استجابة عادية، لا فشلًا في النقل (⁨PSR-18⁩ §⁨p2⁩).

فئة مخاطرة ⁨HITL⁩

يصنّف الخادم كل استدعاء أداة على سُلّم مخاطر المشاركة البشرية (⁨HITL⁩): آمِنة (0) ← تنبيه (1) ← مراجعة (2) ← موافقة مطلوبة (3). create_pdf آمِنة، وadd_text تنبيه. تصنيف output_pdf هو موافقة مطلوبة، لكنه في وضع ⁨base64⁩ (دون file_path) ينخفض إلى مراجعة ويعمل دون تأكيد بشري. أما الكتابة إلى ملف فتُبقيه عند موافقة مطلوبة. راجع موافقة الإخراج ومرجع فئات مخاطرة ⁨HITL⁩.

مغلَّف ⁨JSON⁩ لبوابة التأكيد

تبقى هذه الوصفة في وضع ⁨base64⁩، لذلك تعيد بوابة التأكيد مغلَّف السماح:

{ "allowed": true }

مغلَّف التحدي (allowed: false، مع سلسلة challenge وtoken أحادي الاستخدام) موثَّق في موافقة الإخراج.

انظر أيضًا

• مستند متعدد الصفحات
• تضمين الصور
• كتالوج الأدوات
• فئات مخاطرة ⁨HITL⁩