نود HTML to PDF در N8N

نود HTML to PDF برای تبدیل محتوای HTML به فایل PDF درون ورکفلوهای n8n استفاده می‌شود. این نود وقتی به درد می‌خورد که بخواهید خروجی قابل چاپ و رسمی (مثل فاکتور، قرارداد، گزارش یا رسید پرداخت) را به‌صورت خودکار تولید کنید و سپس آن را ایمیل کنید، در فضای ابری ذخیره کنید یا به سیستم‌های دیگر ارسال کنید.

معرفی نود در N8N

این نود معمولاً HTML را (به‌صورت متن خام یا تولیدشده در مراحل قبلی) دریافت می‌کند، آن را با یک موتور رندر (معمولاً مبتنی بر Chromium) به PDF تبدیل می‌کند و خروجی را به شکل فایل باینری تحویل می‌دهد.

کارکرد اصلی: رندر HTML/CSS و تولید PDF خروجی
دسته‌بندی نود: Action
اهمیت در ورکفلوها: تبدیل خروجی‌های پویا (HTML قالب‌بندی‌شده) به سند استاندارد PDF که قابل آرشیو، امضا، چاپ و ارسال است.

موارد استفاده

1) تولید فاکتور PDF و ارسال برای مشتری

دریافت سفارش از WooCommerce/Shopify یا یک فرم
ساخت HTML فاکتور با داده‌های سفارش
تبدیل به PDF با HTML to PDF
ارسال PDF با Email (SMTP/Gmail) یا ذخیره در Google Drive

2) ساخت گزارش روزانه/هفتگی از داده‌ها

جمع‌آوری داده از Google Sheets، Notion، دیتابیس یا API
تبدیل داده به یک جدول HTML
خروجی PDF برای مدیر یا آرشیو

3) تولید قرارداد یا نامه اداری با قالب آماده

گرفتن اطلاعات مخاطب از CRM
جایگذاری متغیرها داخل قالب HTML
PDF نهایی برای امضا یا ارسال

سناریوهای متداول ترکیب با نودهای دیگر

Set / Edit Fields: ساخت فیلدهای لازم مثل نام مشتری، مبلغ، تاریخ
Function / Code: تولید HTML پویا، حلقه روی آیتم‌ها، ساخت جدول
HTTP Request: دریافت داده یا قالب HTML از سرویس خارجی
Move Binary Data: تبدیل بین JSON و Binary یا تغییر نام فایل
Email / Gmail / Microsoft Outlook: ارسال PDF به عنوان پیوست
Google Drive / S3 / Dropbox: ذخیره و بایگانی فایل PDF

پارامترها و تنظیمات

نام فیلدها ممکن است بسته به نسخه n8n یا پیاده‌سازی نود کمی متفاوت باشد، اما مفهوم و کاربردها معمولاً ثابت است. در ادامه رایج‌ترین پارامترها و تنظیمات این نود آورده شده است.

1) HTML

نام پارامتر: HTML
نوع داده: String
توضیح: محتوای HTML که باید به PDF تبدیل شود. بهتر است یک سند کامل HTML (شامل html و head و body) ارسال شود تا رندر پایدارتر باشد.
مثال عملی:

<html><head><meta charset=”utf-8″><style>body{font-family:Arial} .box{border:1px solid #ddd;padding:16px}</style></head><body><div class=”box”><h1>Invoice #123</h1><p>Total: 250,000 IRR</p></div></body></html>

2) Output Binary Property

نام پارامتر: Output Binary Property
نوع داده: String
توضیح: نام پراپرتی باینری که فایل PDF در آن ذخیره می‌شود (مثلاً pdf یا data).
مثال عملی: pdf

3) File Name

نام پارامتر: File Name
نوع داده: String
توضیح: نام فایل خروجی. اگر نود اجازه دهد، می‌توانید با Expression نام را پویا کنید.
مثال عملی: invoice-{{$json.orderId}}.pdf

4) Page Format / Paper Size

نام پارامتر: Page Format یا Paper Size
نوع داده: Option (A4, Letter, …)
توضیح: اندازه صفحه PDF.
مثال عملی: A4

5) Orientation

نام پارامتر: Orientation
نوع داده: Option (Portrait / Landscape)
توضیح: حالت عمودی یا افقی بودن صفحه.
مثال عملی: Portrait

6) Margins

نام پارامتر: Margins (Top/Right/Bottom/Left)
نوع داده: Number/String (بسته به پیاده‌سازی)
توضیح: حاشیه‌های صفحه. معمولاً با واحدهایی مثل mm, cm, in یا px قابل تنظیم است.
مثال عملی: Top: 10mm, Right: 10mm, Bottom: 12mm, Left: 10mm

7) Print Background

نام پارامتر: Print Background
نوع داده: Boolean
توضیح: اگر فعال باشد رنگ پس‌زمینه‌ها و تصاویر پس‌زمینه CSS در PDF چاپ می‌شوند. برای قالب‌های برندینگ بسیار مهم است.
مثال عملی: true

8) Scale

نام پارامتر: Scale
نوع داده: Number
توضیح: مقیاس رندر (مثلاً 0.9 یا 1.0 یا 1.1). برای جا شدن محتوا در صفحه کاربرد دارد.
مثال عملی: 1

9) Header / Footer Template

نام پارامتر: Header Template / Footer Template
نوع داده: String (HTML Template)
توضیح: HTML جداگانه برای سربرگ و پابرگ چاپ. معمولاً محدودیت‌هایی دارد و فقط برخی CSSها را می‌پذیرد.
مثال عملی:

10) Wait for Network / Timeout (در برخی پیاده‌سازی‌ها)

نام پارامتر: Timeout / Wait Until
نوع داده: Number/Option
توضیح: اگر HTML شما منابع خارجی (تصویر، فونت، CSS) را از اینترنت می‌گیرد، تنظیم زمان انتظار می‌تواند از ناقص شدن PDF جلوگیری کند.
مثال عملی: Timeout: 30000 (میلی‌ثانیه)

نکات مهم هنگام پیکربندی

فونت فارسی: اگر متن فارسی دارید، بهتر است از فونت‌های در دسترس محیط اجرا استفاده کنید یا فونت را به‌صورت Base64 در CSS Embed کنید؛ در غیر این صورت ممکن است حروف جدا جدا یا ناخوانا شوند.
CSS چاپ: از media print و اندازه‌های ثابت استفاده کنید تا شکست صفحات قابل کنترل باشد.
منابع خارجی: در محیط‌های محدود (Docker/Server بدون اینترنت) تصاویر یا CSSهای خارجی ممکن است لود نشوند؛ بهتر است فایل‌ها را inline یا به‌صورت Data URI قرار دهید.
اندازه تصاویر: تصاویر خیلی بزرگ می‌توانند زمان رندر را زیاد و خروجی را سنگین کنند.

ورودی‌ها و خروجی‌ها

ورودی (Input)

ورودی معمولاً آیتم‌های JSON است که داخل آن یک فیلد شامل HTML تولیدشده قرار دارد (یا HTML مستقیماً در تنظیمات نود نوشته می‌شود). در سناریوهای حرفه‌ای، HTML با Expression از فیلدهای ورودی ساخته می‌شود.

نمونه ساختار ورودی JSON

{ “orderId”: 123, “customer”: { “name”: “Ali Ahmadi”, “email”: “ali@example.com” }, “total”: 250000, “items”: [ { “title”: “Product A”, “qty”: 1, “price”: 150000 }, { “title”: “Product B”, “qty”: 1, “price”: 100000 } ], “html”: “<html>…</html>” }

خروجی (Output)

خروجی معمولاً همان آیتم(های) ورودی است به‌اضافه یک پراپرتی باینری که فایل PDF در آن قرار دارد. سپس می‌توانید این فایل را به نودهای ارسال ایمیل یا ذخیره‌سازی فایل وصل کنید.

نمونه خروجی (نمایش خلاصه ساختار)

{ “orderId”: 123, “customer”: { “name”: “Ali Ahmadi”, “email”: “ali@example.com” }, “total”: 250000, “binary”: { “pdf”: { “fileName”: “invoice-123.pdf”, “mimeType”: “application/pdf”, “fileSize”: 48231, “data”: “…” } } }

نکات پیشرفته و ترفندها

1) ساخت جدول آیتم‌ها به‌صورت پویا با Code node

اگر تعداد آیتم‌ها متغیر است، تولید HTML را در Code node انجام دهید و خروجی را در فیلد html قرار دهید. سپس HTML to PDF همان فیلد را به PDF تبدیل می‌کند.

2) کنترل شکست صفحه (Page Break) در CSS

برای گزارش‌ها و فاکتورهای چندصفحه‌ای، از CSS چاپ استفاده کنید:

3) Embed کردن تصویر لوگو با Data URI

اگر لوگو از URL لود شود ممکن است در برخی محیط‌ها به PDF نرسد. راه بهتر این است که تصویر را به base64 تبدیل و inline کنید:

4) ساخت نام فایل استاندارد و قابل جستجو

ترکیب تاریخ + شناسه: invoice-{{$json.orderId}}-{{$now.toFormat(‘yyyyLLdd’)}}.pdf
پرهیز از کاراکترهای غیرمجاز در نام فایل (مثل / : * ? ” < > |)

5) بهینه‌سازی حجم PDF

تصاویر را قبل از embed کردن کوچک‌سازی کنید.
از سایه‌ها و افکت‌های سنگین CSS کمتر استفاده کنید.
در صورت امکان، از فونت‌های سبک‌تر استفاده کنید.

محدودیت‌ها و خطاها

محدودیت‌ها

پشتیبانی ناقص از برخی CSSها: بعضی ویژگی‌های مدرن CSS ممکن است در رندر PDF دقیق مثل مرورگر نهایی نباشد.
وابستگی به محیط اجرا: اگر موتور رندر نیاز به کتابخانه‌های سیستم داشته باشد، در Docker یا سرور ممکن است نیاز به نصب پیش‌نیازها باشد.
منابع خارجی: تصاویر/فونت/stylesheetهای بیرونی ممکن است به دلیل محدودیت شبکه، CORS یا DNS لود نشوند.
فونت فارسی: اگر فونت مناسب در دسترس نباشد، نمایش فارسی ممکن است به‌هم بریزد.

خطاهای رایج و راه‌حل‌ها

PDF سفید یا ناقص: HTML ناقص است یا منابع خارجی لود نشده‌اند. HTML را کامل ارسال کنید، Timeout را افزایش دهید، و منابع را inline کنید.
به‌هم‌ریختگی فارسی یا جدا شدن حروف: فونت مناسب تعریف نشده است. فونت فارسی را Embed کنید یا از فونت نصب‌شده روی سیستم استفاده کنید و direction: rtl را تنظیم کنید.
عدم نمایش پس‌زمینه‌ها: Print Background غیرفعال است. آن را فعال کنید.
بزرگ شدن بیش از حد محتوا: Scale را تنظیم کنید یا از CSS برای کنترل عرض (مثلاً max-width) استفاده کنید.
خطای زمان اجرا (Timeout): HTML سنگین است یا تصاویر زیاد هستند. حجم تصاویر را کاهش دهید و زمان انتظار را افزایش دهید.

ایده ها

سیستم خودکار صدور گواهی دوره: دریافت نام و نمره از Google Sheets و خروجی PDF گواهی با QR Code
ساخت رزومه PDF از فرم آنلاین: دریافت اطلاعات از Typeform و تولید CV با قالب HTML
گزارش ماهانه فروش: جمع‌آوری داده از CRM و ارسال PDF به مدیران با ایمیل زمان‌بندی‌شده
تولید رسید پرداخت: بعد از تایید پرداخت از درگاه، رسید PDF ساخته و در تلگرام/ایمیل ارسال شود
آرشیو خودکار صفحات مهم: دریافت HTML از یک URL (با HTTP Request) و ذخیره نسخه PDF در S3

نود HTML to PDF در N8N