مقدمه

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

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

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

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

چه زمانی ترکیب فاکتور محافظت‌شده با رمز عبور با اسناد دیگر منطقی است؟

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

پیش‌نیازها

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

گام ۱: تجمیع پایهٔ پیوست‌های PDF

ساده‌ترین حالت ترکیب یک فاکتور 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 ترکیبی را در مسیر مشخص‌شده می‌نویسد.

گام ۲: تجمیع پیوست‌های فرمت‑مختلط

بسته‌های صورتحساب واقعی اغلب شامل تصاویر اسکن‌شده (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 نیاز دریافت‌کننده به استفاده از چندین نمایشگر را از بین می‌برد و تجربهٔ یکپارچه‌ای فراهم می‌کند.

گام ۳: کار با فاکتورهای محافظت‌شده با رمز عبور

اگر فاکتور رمزگذاری شده باشد، رمز عبور را از طریق 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 رمز جدیدی به فایل نهایی اعمال می‌کند.

گام ۴: انتخاب صفحات خاص از پیوست‌ها

گاهی فقط زیرمجموعه‌ای از یک پیوست مورد نیاز است (مثلاً دو صفحهٔ اول یک گزارش سرویس طولانی). از 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 نهایی شامل فاکتور به‌همراه فقط صفحات انتخاب‌شده است و بستهٔ سبک‌تری تولید می‌کند.

مثال کامل

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

بهترین روش‌ها و نکات

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

نتیجه‌گیری

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