Product3 دقيقة قراءة

pdfx CLI: كتالوج واحد تستدعيه من طرفيتك

ترسل أداة pdfx الطلبات multipart نفسها التي يرسلها curl إلى واجهة PDF123 أو إلى خادم pdfx-server الخاص بك، وتضيف تشغيل الدفعات وكلمات مرور لكل ملف ورموز خروج يمكن للسكربت التفريع عليها.

By the PDF123 team · Updated 2026-09-29
pdfx CLI: كتالوج واحد تستدعيه من طرفيتك

PDF123 هو اسم المنتج. وأداة pdfx هي كتالوج العمليات نفسه مغلّفاً لسطر الأوامر: تبني طلب multipart الذي كان curl سيبنيه، وترسله إلى عنوان قاعدة API الذي تختاره، وتكتب الناتج بجوار ملفاتك. والدمج والضغط وOCR وبقية الكتالوج قابلة للاستدعاء بهذه الطريقة.

ما الذي يرسله الاستدعاء فعلاً

pdfx --api-base "$API_BASE" --api-key "$PDFX_API_KEY" \
  merge a.pdf b.pdf -o merged.pdf

و--api-base يتجه افتراضياً إلى https://pdf123.xyz، و--api-key (أو متغير البيئة PDFX_API_KEY) اختياري، فيعمل الكتالوج المجهول دون مفتاح. وجّه القاعدة إلى http://127.0.0.1:8080 لمنظومة docker-compose خاصة بك. ولا يوجد بروتوكول ثانٍ في الأسفل: الأداة عميل لسطح REST الموثّق على المطوّرين، وأسماء عملياتها تطابق أدوات البوابة ومستند OpenAPI عند /v1/openapi.json.

والكتالوج قابل للاكتشاف دون مغادرة الطرفية. يطبع pdfx list كل أداة، ويطبع pdfx describe add-stamp حقول أداة واحدة وقيمها الافتراضية، وهو التعريف نفسه الذي تعرضه البوابة في صورة نموذج.

تشغيل الدفعات والأعلام التي يجعلك curl تكتبها بنفسك

أعطِ أداة ملف واحد عدة مدخلات فتشغّلها دفعة واحدة داخل مجلد -o، طابعةً سطر input -> saved واحداً لكل ملف. وتذهب الأعطال إلى stderr بينما تكمل الملفات الباقية، فلا يوقف ملف PDF معطوب واحد في مجلد فواتير التشغيل كله. ويحدّد --concurrency <n> عدد الملفات قيد المعالجة في اللحظة نفسها (افتراضياً 2).

ويقبل -o ملفاً أو مجلداً ولا يكتب فوق ملف موجود أبداً، بل يستخدم اسم الملف الذي يمنحه الخادم داخل المجلد. وهذا مهم حين يسمّي الخادم الناتج على اسم المدخل: فلولاه لأتلف التشغيل ملف PDF الذي رفعته للتو.

وتُفتح المدخلات المشفّرة قبل الطلب، لا بواسطة الأداة: يغطي --input-password كل ملف في التشغيل، ويضبط --password-for report.pdf=secret كلمة مرور ملف واحد ويمكن تكراره، مع * نيابة عن البقية. فلا تحتاج دفعة تخلط ملفات مقفلة وأخرى مفتوحة إلى فرز يدوي. ويطبع --json الصيغة { path, contentType, bytes } لكل نتيجة، أو [{ input, ok, path | error, reason }] للدفعة، فيستطيع غلاف تحليل النتيجة بدل كشط الأسطر المقروءة للبشر.

رموز خروج يمكن للسكربت التفريع عليها

0 تعني النجاح، و1 تعني فشل طلب (وفي الدفعة: فشل ملف واحد على الأقل)، و2 خطأ في الاستخدام لم يُرفع فيه شيء، و130 تعني أنك قاطعت التشغيل فأُجهض الطلب الجاري. وتطبع الأعطال أسطر reason: وcode: وhint: تحت الرسالة متى توفرت، وهي ما ينبغي للسكربت مطابقته بدل النثر.

وثمة خروج واحد يسهل إساءة قراءته. فالأداة التي لا تجد ما تعيده تخرج بغير صفر مع code: no_content بدل كتابة ملف فارغ، فـ pdf-to-csv على PDF بلا جداول فشل، لا ملف CSV بحجم صفر.

إلى أين تذهب البايتات

تُرفع الملفات إلى عنوان قاعدة API، وتُعالَج هناك، وتُحذف بعد إرسال الرد. وهذا العقد نفسه الذي يخضع له نموذج المتصفح: الأداة تغيّر العميل لا الوجهة. وللمستندات التي لا يجوز أن تغادر شبكتك، شغّل pdfx-server بنفسك ووجّه --api-base إليه، وهو ما يغطيه الاستضافة الذاتية.

ولا يوجد وضع دون اتصال ترجع إليه: إن تعذّر الوصول إلى القاعدة فشل الأمر. فـ pdfx عميل شبكة يصادف أنه لطيف في الطرفية، لا محرّك PDF محلي.

ما ليست عليه الأداة

pdfx ليست واجهة رسومية مكتبية ولا مكتبة OCR قابلة للتضمين تربطها في تطبيق آخر. إنها عميل سطر أوامر لعمليات PDF، فالمهمة الفردية للبشر لا تزال البوابة تخدمها أفضل (الضغط وOCR وبقية الكتالوج)، وأي شيء يحتاج شجرة واجهة خاصة به سيعيد إنتاج مشكلة الانحراف الموصوفة في العملية نفسها، أربعة عملاء.

ويحصل الوكلاء على الأشكال نفسها من المهارة المنشورة عند /skills/pdf123.md التي توثّق طلبات الدمج وخطوط المعالجة بالكامل. ولإعادات محاولة آمنة لطلبات POST المُعدِّلة، أرسل Idempotency-Key؛ ولا تزال الأداة تصنع طلباً واحداً لكل استدعاء، فالترويسة مكانها أي شيء يعيد المحاولة (إعادات المحاولة الآمنة لمهام PDF). والمفاتيح وحدود المعدل ورموز الأخطاء على المطوّرين.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool