لمن هذا؟
- صاحب متجر أو مشروع صغير يبي يطلع فواتير PDF من نظامه.
- مطوّر عنده عقود أو عروض أسعار بصيغة Word ويبي يحوّلها PDF تلقائيًا.
- من يبني أتمتة (n8n أو سكربت) ويحتاج يدمج تقارير PDF في ملف واحد.
ماذا ستحتاج؟
- جهاز أو سيرفر فيه Docker.
- curl أو أي أداة ترسل طلبات HTTP.
- خمس دقائق.
- لو قالبك عربي: خط عربي مثل Noto Naskh Arabic أو Noto Sans Arabic.
النتيجة النهائية
تكتب أمر curl واحد، وتطلع لك فاتورة PDF عربية جاهزة من صفحة HTML.
الخطوات
1. شغّل Gotenberg
docker run --rm -p 127.0.0.1:3000:3000 gotenberg/gotenberg:8
استخدمنا 127.0.0.1 عشان تكون الخدمة متاحة على جهازك بس، مو للعالم. (أمر البداية السريعة الرسمي هو -p 3000:3000، لكن على السيرفر الأفضل تربطه بـ localhost.)
2. حوّل رابط (فاتورة HTML) إلى PDF
curl --request POST http://localhost:3000/forms/chromium/convert/url \
--form url=https://sparksuite.github.io/simple-html-invoice-template/ \
-o invoice.pdf
Chromium داخل الحاوية يفتح الصفحة ويطبعها PDF. نفس الفكرة لو عندك قالب فاتورة HTML في نظامك.
3. فاتورة عربية من ملف HTML (RTL)
ابدأ ملفك index.html بهذا السطر:
<html lang="ar" dir="rtl">
وعرّف خط عربي في CSS عبر @font-face، وحط ملف الخط جنب index.html. بعدها أرسل الملفين لمسار تحويل HTML في Chromium (اسم المسار والحقول بالضبط في صفحة Routes):
لو طلعت لك الحروف مفصولة أو مربعات فارغة، فالخط ما وصل للمحرك. أرسل ملف الخط مع الطلب، أو ابنِ صورة Docker خاصة فيها خطوط Noto.
4. حوّل عقد Word أو ادمج ملفات
لملفات Office (.docx و.xlsx و.pptx وأكثر من 100 صيغة) يستخدم Gotenberg محرك LibreOffice. وفيه مسارات لدمج ملفات PDF وتقسيمها وتدويرها، وإضافة علامة مائية أو ختم أو تشفير. أسماء المسارات وحقولها بالضبط موجودة في صفحة Routes الرسمية، راجعها قبل الاستخدام.
5. اختر الصورة المناسبة
gotenberg/gotenberg:8: النسخة الكاملة.gotenberg/gotenberg:8-chromium: أصغر بنحو 30%، فيها HTML/URL/Markdown، وما فيها Office.gotenberg/gotenberg:8-libreoffice: أصغر بنحو 40%، فيها Office، وما فيها HTML/URL.
مشاكل شائعة
- حروف عربية مكسورة أو مقلوبة: تأكد إن عندك
dir="rtl" lang="ar"، وإن الخط العربي يوصل للمحرك.
- فتحت المنفذ للإنترنت: هذا أخطر غلط. التوثيق يقول عامِل Gotenberg مثل قاعدة البيانات، فلا تكشفه للعامة. خلّه خلف تطبيقك أو على شبكة داخلية.
- اخترت صورة ناقصة: لو حوّلت Word على
8-chromiumبيفشل الطلب. استخدم الكاملة أو8-libreoffice. - ملفات كبيرة تمر عبر سيرفرك: يقدر Gotenberg يجيب الملف من S3/MinIO/GCS برابط presigned GET، ويرفع النتيجة عبر webhook برابط PUT، فما يمر الملف على تطبيقك أصلًا.
- التجربة على الديمو: demo.gotenberg.dev عليه حد للطلبات، وهو للتجربة بس. لا ترسل عليه بيانات عملاء.
Gotenberg أو خدمة PDF سحابية؟
فيه خدمات مدفوعة تحوّل HTML إلى PDF وتدعم العربي بشكل ممتاز، وميزتها إنك ما تشيل همّ تشغيل أي شي. أما Gotenberg فأداة وحدة تستضيفها بنفسك، وتجمع Chromium (HTML وURL وMarkdown) وLibreOffice (ملفات Office) وفوقهم الدمج والتشفير وPDF/A. هي أنسب لك لو عندك سيرفر وتبي تكون بياناتك عندك. أما السحابة فأنسب لو ما عندك أحد يتابع السيرفر.
مصطلحات
- API: واجهة تتعامل معها برمجيًا عبر طلبات HTTP.
- Docker / حاوية: طريقة تشغيل برنامج مع كل اللي يحتاجه في صندوق واحد.
- Chromium: محرك متصفح، هنا يُستخدم لطباعة صفحات الويب PDF.
- LibreOffice: حزمة مكتبية، هنا تُستخدم لتحويل ملفات Office.
- PDF/A و PDF/UA: معايير PDF للأرشفة طويلة المدى ولسهولة الوصول.
- Webhook: رابط يستقبل النتيجة تلقائيًا لما تخلص المعالجة.
هل هو مجاني أم مدفوع؟
مجاني ومفتوح المصدر بترخيص MIT. تشغّله على جهازك أو سيرفرك، وتتحمّل أنت تكلفة السيرفر بس.
أسئلة شائعة
ما هو Gotenberg وهل أحتاجه لمشروعي الصغير؟
Gotenberg هو API مفتوح المصدر بترخيص MIT يشتغل على Docker، ويحوّل HTML وصفحات الويب وملفات Office إلى PDF. تحتاجه لو تطلّع فواتير أو عقود أو تقارير بشكل متكرر وعندك سيرفر.
كيف أحوّل HTML أو صفحة ويب إلى PDF بطلب واحد؟
شغّل الحاوية، وأرسل طلب POST إلى /forms/chromium/convert/url ومعه الرابط. لو عندك ملف HTML جاهز، أرسله لمسار تحويل HTML.
هل يحوّل ملفات Word وExcel إلى PDF؟
نعم، عن طريق LibreOffice يحوّل .docx و.xlsx و.pptx وأكثر من 100 صيغة. استخدم الصورة الكاملة أو 8-libreoffice.
كيف أظهر النص العربي من اليمين لليسار بدون حروف مكسورة؟
حط dir="rtl" lang="ar" في وسم html، وأضف خط عربي عبر @font-face وأرسل ملفه مع الطلب، أو استخدم صورة Docker فيها خطوط Noto.
هل أفتح المنفذ 3000 على الإنترنت؟
لا. التوثيق الرسمي يقول عامله مثل قاعدة البيانات. اربطه بـ 127.0.0.1 أو خلّه خلف جدار ناري أو على شبكة داخلية.
ما الفرق بين Chromium وLibreOffice في Gotenberg؟
Chromium للويب (HTML وURL وMarkdown)، وLibreOffice لملفات Office.
متى أستخدم خدمة سحابية بدل الاستضافة الذاتية؟
لو ما عندك سيرفر أو أحد يتابعه، أو كمية التحويل قليلة وتبي تبدأ بسرعة.
ماذا بعد؟
- اقرأ صفحة Routes كاملة قبل ما تشغّله في الإنتاج.
- جرّب تصدير PDF/A لو تحتاج أرشفة.
- قريبًا لأعضاء VIP: نود n8n جاهز يطلع فاتورة PDF مع كل طلب، وقالب فاتورة HTML عربي. الشرح هنا يبقى مجاني.
المصادر ونسبة الصور
- مستودع Gotenberg على GitHub: https://github.com/gotenberg/gotenberg
- الموقع والتوثيق: https://gotenberg.dev/
- التثبيت: https://gotenberg.dev/docs/getting-started/installation
- المسارات (Routes): https://gotenberg.dev/docs/getting-started/routes
- الديمو: https://demo.gotenberg.dev
- قالب الفاتورة في المثال: https://sparksuite.github.io/simple-html-invoice-template/
- الغلاف: تصميم فريق أنور AI.
كن أول من يعلّق — شارك سؤالك أو تجربتك مع هذا المحتوى.