Introduction

تجمیع صورتحساب یک جریان کاری است که چندین سند مالی را به یک PDF واحد ترکیب می‌کند با استفاده از GroupDocs.Merger برای Python. تیم‌های مالی اغلب نیاز دارند فاکتور را همراه با یادداشت‌های تحویل، گزارش‌های سرویس و شرایط گارانتی ارسال کنند، اما ترکیب دستی فایل‌ها منجر به خطا می‌شود و زمان‌بر است. GroupDocs.Merger این فرآیند را خودکار می‌کند، به‌طوری که هر پیوست به‌درستی ترتیب داده می‌شود، به‌صورت اختیاری ایمن می‌شود و به‌عنوان یک PDF تمیز تحویل داده می‌شود.

در این آموزش خواهید دید چگونه:

  • یک فاکتور PDF ساده را با هر تعداد فایل پشتیبانی ترکیب کنید.
  • فرمت‌های ترکیبی مانند تصاویر JPG و قراردادهای DOCX را مدیریت کنید.
  • یک فاکتور محافظت‌شده با رمز عبور را باز کنید، پیوست‌ها را اضافه کنید و دوباره رمزگذاری کنید.
  • فقط صفحات انتخابی را از پیوست‌های بزرگ گنجانده و بسته نهایی را فشرده نگه دارید.

من دقیقاً با این سناریو در سه‌ماهه گذشته مواجه شدم؛ سیستم حسابداری ما فاکتور محافظت‌شده با رمز عبور تولید می‌کرد و تیم حقوقی یک سند گارانتی چندصفحه‌ای DOCX اضافه می‌کرد. کد زیر این مشکل را در کمتر از پنج دقیقه حل کرد.

When does it make sense to merge a password‑protected invoice with other documents?

بسیاری از شرکت‌ها فاکتورها را در حالت استراحت رمزگذاری می‌کنند تا الزامات انطباق را برآورده سازند. وقتی فاکتور باید همراه با پیوست‌های بدون محافظت (رسیدها، شرایط، تصاویر) به مشتری ارسال شود، رمز عبور اصلی برای ترکیب باید حذف شود و سپس بر روی بسته نهایی دوباره اعمال گردد. GroupDocs.Merger به شما امکان می‌دهد رمز باز کردن را از طریق LoadOptions فراهم کنید، فایل‌های اضافی را بپیوندید و در نهایت PDF ترکیبی را با AddPasswordOptions محافظت کنید. این کار محرمانگی را حفظ می‌کند در حالی که یک سند واحد و آسان برای باز کردن ارائه می‌دهد.

Prerequisites

  • Python 3.8+ (از طریق پل .NET)
  • GroupDocs.Merger برای Python – نصب با:
pip install groupdocs-merger
  • یک فاکتور PDF اصلی (invoice.pdf) و فهرستی از مسیرهای فایل‌های پیوست.
  • (اختیاری) رمزهای عبور برای فاکتور منبع و PDF خروجی.

Step 1: Basic Consolidation of PDF Attachments

ساده‌ترین حالت ترکیب یک فاکتور PDF با سایر PDFها، تصاویر یا فایل‌های Word است. API به‌صورت خودکار ورودی‌های غیر‑PDF را قبل از ترکیب به PDF تبدیل می‌کند.

import groupdocs_merger as gm

# Paths to source files
invoice = "invoice.pdf"
attachments = ["delivery_note.pdf", "service_report.pdf"]
output = "billing_package.pdf"

with gm.Merger(invoice) as merger:
    for path in attachments:
        merger.join(path)  # Normalises each file to PDF and appends it
    merger.save(output)

نکات کلیدی:

  • gm.Merger با سند اصلی (فاکتور) ساخته می‌شود.
  • join() هر فرمت پشتیبانی‌شده‌ای را می‌پذیرد؛ کتابخانه تبدیل را انجام می‌دهد.
  • save() PDF ترکیبی را در مسیر مشخص‌شده می‌نویسد.

Step 2: Consolidating Mixed‑Format Attachments

بسته‌های صورتحساب واقعی اغلب شامل تصاویر اسکن‌شده (JPG) و قراردادهای قانونی (DOCX) می‌شوند. همان کد کار می‌کند چون GroupDocs.Merger هر پیوست را به‌صورت لحظه‌ای به PDF نرمالایز می‌کند.

attachments = ["receipt.jpg", "warranty_terms.docx", "extra_clause.pdf"]
output = "billing_mixed.pdf"

with gm.Merger(invoice) as merger:
    for path in attachments:
        merger.join(path)  # JPG and DOCX are converted to PDF automatically
    merger.save(output)

چرا مهم است: تبدیل همه چیز به PDF نیاز دریافت‌کننده به استفاده از چندین برنامه مشاهده‌گر را از بین می‌برد و تجربه‌ای یکپارچه فراهم می‌کند.

Step 3: Handling Password‑Protected Invoices

اگر فاکتور رمزگذاری شده باشد، رمز عبور را از طریق LoadOptions ارائه دهید. پس از ترکیب، می‌توانید با AddPasswordOptions دوباره رمز عبور را بر روی PDF نهایی اعمال کنید.

import io

invoice_password = "Inv$2026"
output_password = "Bill$2026"

load_options = gm.domain.options.LoadOptions(invoice_password)
buffer = io.BytesIO()

# Open the protected invoice, join attachments, write to memory buffer
with gm.Merger(invoice, load_options) as merger:
    for path in attachments:
        merger.join(path)
    merger.save(buffer)

# Re‑secure the merged document
add_pwd = gm.domain.options.AddPasswordOptions(output_password)
buffer.seek(0)
with gm.Merger(buffer) as merger:
    merger.add_password(add_pwd)
    merger.save(output)

نکات کلیدی:

  • LoadOptions فاکتور منبع را باز می‌کند.
  • نتیجه ترکیبی ابتدا در یک جریان حافظه (BytesIO) نوشته می‌شود.
  • AddPasswordOptions رمز جدیدی را بر روی فایل نهایی اعمال می‌کند.

Step 4: Selecting Specific Pages from Attachments

گاهی فقط زیرمجموعه‌ای از یک پیوست مرتبط است (مثلاً دو صفحه اول یک گزارش سرویس طولانی). از PageJoinOptions برای تعیین بازهٔ ۱‑پایه استفاده کنید.

page_picks = [
    ("service_report.pdf", 1, 2),   # Include pages 1‑2 only
    ("terms_and_conditions.pdf", 3, 3)  # Include only page 3
]
output = "billing_selected_pages.pdf"

with gm.Merger(invoice) as merger:
    for path, first, last in page_picks:
        options = gm.domain.options.PageJoinOptions(first, last)
        merger.join(path, options)
    merger.save(output)

نتیجه: PDF نهایی شامل فاکتور به‌همراه فقط صفحات انتخاب‌شده است و بسته سبک‌وزن می‌ماند.

Full Example

مثال کامل کارآمد، شامل تمام فایل‌های منبع و اسناد نمونه، در GitHub موجود است: billing-consolidator-demo-using-groupdocs-merger-python.

Best Practices & Tips

  • Performance: برای دسته‌های بزرگ، فقط گزینه‌های مورد نیاز را فعال کنید (مثلاً از تبدیل فرمت‌های غیرضروری خودداری کنید).
  • Memory Management: همیشه از عبارت with استفاده کنید تا اطمینان حاصل شود Merger به‌سرعت منابع را آزاد می‌کند.
  • Security: پس از ترکیب، رمزگذاری را دوباره اعمال کنید تا محرمانگی فاکتور اصلی حفظ شود.
  • File Limits: GroupDocs.Merger از PDFهای تا ۲ GB پشتیبانی می‌کند؛ فایل‌های بزرگتر ممکن است نیاز به تقسیم قبل از ترکیب داشته باشند.

Conclusion

GroupDocs.Merger برای Python یک API ساده فراهم می‌کند تا مجموعه‌ای پراکنده از اسناد صورتحساب را به یک بسته PDF حرفه‌ای تبدیل کنید. چه با PDFهای ساده، رسانه‌های ترکیبی، فاکتورهای رمزگذاری‌شده یا نیاز به برش صفحات پیوست‌ها سروکار داشته باشید، این کتابخانه کار سنگین را در چند خط کد انجام می‌دهد.

Next steps:

  • فهرست کامل فرمت‌های پشتیبانی‌شده را در documentation بررسی کنید.
  • یاد بگیرید چگونه به PDF ترکیبی واترمارک یا امضای دیجیتال اضافه کنید ([API reference][API_REF_URL]).
  • پروژه‌های نمونه در GitHub را برای سناریوهای پیشرفته‌تر ببینید ([Examples Repo][EXAMPLES_URL]).

Additional Resources

  • GroupDocs.Merger Documentation
  • [API Reference for Python][API_REF_URL]
  • [Sample Projects on GitHub][EXAMPLES_URL]
  • [GroupDocs Merger Forum][FORUM_URL]