ایجاد فاکتورهای آنلاین با API ابر GroupDocs.Assembly

نمای کلی

تولید فاکتورهای به‌صورت پویا یک نیاز رایج برای سیستم‌های صورتحساب، پلتفرم‌های تجارت الکترونیک و برنامه‌های SaaS است.
با GroupDocs.Assembly Cloud می‌توانید فاکتورهای حرفه‌ای را کاملاً در ابر ایجاد کنید بدون اینکه نیاز به نصب نرم‌افزارهای اداری روی سرورهای خود داشته باشید.

مزایای کلیدی

انعطاف‌پذیری قالب – طرح فاکتور را در ویرایشگر بومی مانند Microsoft Word، LibreOffice Writer و غیره طراحی کنید.
اتصال داده دینامیک – قالب‌ها را با داده‌های JSON یا XML پر کنید، با استفاده از برچسب‌های ساده یا عبارات پیشرفته LINQ برای محاسبات، حلقه‌ها و بخش‌های شرطی.
قالب‌های خروجی متنوع – فاکتور نهایی را به‌صورت DOCX برای ویرایش بیشتر یا PDF برای توزیع فقط‑قابل‌خواندن تولید کنید.
ذخیره‌سازی ایمن – به قالب‌ها و اسناد ذخیره‌شده در GroupDocs Cloud از طریق توکن‌های احراز هویت دسترسی داشته باشید.
محیط سبُک – تمام پردازش‌ها در GroupDocs Cloud انجام می‌شود و زیرساخت شما از ابزارهای شخص ثالث یا نیازهای پردازشی سنگین رها می‌شود.

در بخش‌های زیر، کل فرآیند را قدم به قدم مرور می‌کنیم – از آماده‌سازی قالب و منبع داده تا تولید فاکتور با SDK .NET با C# و با استفاده از دستورات ساده cURL.

آماده‌سازی قالب فاکتور

قالب فاکتور را با ویرایشگر دلخواه دسکتاپ خود (Microsoft Word، LibreOffice Writer و غیره) طراحی کنید.
برچسب‌های placeholder را که با فیلدهای JSON که بعداً ارائه می‌کنید مطابقت دارند، اضافه کنید؛ برای مثال:

قالب	مسیر JSON
`<<[Invoice.Number]>>`	`invoice.number`
`<<[Customer.Name]>>`	`customer.name`

و تعریف رندر جدول به شکل زیر خواهد بود:

توضیح	تعداد	قیمت واحد	هزینه
`<<foreach [in Items]>>` `<<[Description]>>`	`<<[Quantity]>>`	`$<<[UnitPrice]:"N2">>`	`$<<[Quantity*UnitPrice]:"N2">>` `<</foreach>>`

برای راحتی شما می‌توانید یک نمونه قالب که در زیر نشان داده شده است دانلود کنید:

یا قالب خود را بسازید و آن را به فضای ذخیره‌سازی GroupDocs Cloud بارگذاری کنید (بخش بعدی).

بارگذاری قالب در فضای ذخیره‌سازی ابر

مراحل اصلی برای کد C#

یک شیء Configuration با App SID و App Key خود ایجاد کنید.
کلاینت AssemblyApi را مقداردهی اولیه کنید.
فایل قالب محلی را به مسیری در فضای ذخیره‌سازی ابر (مثلاً templates/invoice-template.docx) بارگذاری کنید.

// 1️⃣ Initialize the Cloud API configuration
var config = new Configuration
{
    AppSid = "YOUR_APP_SID",      // replace with your App SID
    AppKey = "YOUR_APP_KEY"       // replace with your App Key
};
var assemblyApi = new AssemblyApi(config);

// 2️⃣ Define the cloud path where the template will be stored
string cloudTemplatePath = "templates/invoice-template.docx";

// 3️⃣ Open the local template file (prepare this file beforehand)
using (var templateStream = File.OpenRead("resources/invoice-template.docx"))
{
    // 4️⃣ Build the upload request – the API expects a stream + target path
    var uploadRequest = new UploadFileRequest(templateStream, cloudTemplatePath);

    // 5️⃣ Execute the upload; the template is now available in Cloud storage
    assemblyApi.UploadFile(uploadRequest);
}

نکته: می‌توانید فایل را با یک فرمان ساده cURL (به بخش تولید فاکتور با cURL مراجعه کنید) نیز بارگذاری کنید اگر روش خط‌دست را ترجیح می‌دهید.

ایجاد منبع داده

ساخت JSON برای داده‌های فاکتور

در زیر یک نمونه JSON که با برچسب‌های استفاده شده در قالب مطابقت دارد آورده شده است.
این فایل را به‌نام invoice-data.json در پوشه resources ذخیره کنید یا مستقیماً در کد خود تعبیه کنید.

{
  "invoice": {
    "number": "INV-2024-001",
    "issueDate": "2024-01-15T00:00:00"
  },
  "customer": {
    "name": "John Smith",
    "company": "Acme Corporation",
    "email": "john.smith@example.com",
    "address": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  },
  "items": [
    {
      "description": "Web Development Services",
      "quantity": 40,
      "unitPrice": 150.00
    },
    {
      "description": "UI/UX Design",
      "quantity": 20,
      "unitPrice": 120.00
    },
    {
      "description": "Consulting Services",
      "quantity": 10,
      "unitPrice": 200.00
    }
  ],
  "taxRate": 10.0
}

استفاده از فایل JSON در کد

// Load the JSON data from a file – this string will be passed to the API
string jsonData = File.ReadAllText("resources/invoice-data.json");

توجه: همان JSON می‌تواند به‌صورت درون‌خطی در بدنه درخواست زمانی که از cURL استفاده می‌کنید ارسال شود؛ روش فایل برای مجموعه‌های داده بزرگ‌تر مناسب‌تر است.

تولید فاکتور با SDK .NET

مراحل اصلی برای کد C#

بارگذاری قالب (که پیشتر پوشش داده شد).
خواندن منبع داده JSON.
پیکربندی AssembleOptions – فرمت خروجی (docx یا pdf) و پیوند به قالب را مشخص کنید.
فراخوانی AssembleDocument برای تولید فاکتور.
ذخیره فایل حاصل به‌صورت محلی یا در مکان دیگر ابر.

using GroupDocs.Assembly.Cloud.Sdk;
using GroupDocs.Assembly.Cloud.Sdk.Model;
using GroupDocs.Assembly.Cloud.Sdk.Model.Requests;
using System.IO;

// 1️⃣ Initialize the Assembly API (same config as upload step)
var config = new Configuration { AppSid = "YOUR_APP_SID", AppKey = "YOUR_APP_KEY" };
var assemblyApi = new AssemblyApi(config);

// 2️⃣ Load JSON data (see previous section)
string jsonData = File.ReadAllText("resources/invoice-data.json");

// 3️⃣ Prepare assembly options
var assembleOptions = new AssembleOptions
{
    // Choose the format you need – "docx" for editable, "pdf" for final PDF
    SaveFormat = "pdf",

    // Pass the whole JSON string – the API parses it automatically
    ReportData = jsonData,

    // Reference the template that we uploaded earlier
    TemplateFileInfo = new TemplateFileInfo
    {
        FilePath = "templates/invoice-template.docx"   // cloud path
    }
};

// 4️⃣ Build the request object
var assembleRequest = new AssembleDocumentRequest(assembleOptions);

// 5️⃣ Execute the request – the response contains the generated file stream
var assembledDocument = assemblyApi.AssembleDocument(assembleRequest);

// 6️⃣ Persist the result locally
using (var outputStream = File.Create("output/invoice-output.pdf"))
{
    // Copy the API stream to a file on disk
    assembledDocument.CopyTo(outputStream);
}

نتیجه: invoice-output.pdf (یا .docx اگر SaveFormat را تغییر دهید) شامل فاکتور کاملاً پر شده است و آماده ارسال به مشتری می‌باشد.

تولید فاکتور با cURL

اگر نمی‌خواهید SDK نصب کنید و ترجیح می‌دهید تمام کارها را با درخواست‌های HTTP ساده انجام دهید، می‌توانید کل فرآیند را با cURL پیاده کنید.

1️⃣ دریافت توکن دسترسی

curl.exe -X POST "https://api.groupdocs.cloud/connect/token" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded"

پاسخ شامل access_token است – مقدار آن را برای مراحل بعدی کپی کنید.

2️⃣ بارگذاری قالب با cURL

curl.exe -X PUT "https://api.groupdocs.cloud/v1.0/assembly/storage/file/templates/invoice-template.docx" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -F "File=@resources/invoice-template.docx"

اگر قالب قبلاً ذخیره شده باشد، می‌توانید این فراخوانی را نادیده بگیرید.

3️⃣ ساخت فاکتور

فایلی به نام invoice-data.json همان‌طور که در بخش [ایجاد منبع داده {#json-data}] توضیح دادیم، آماده کنید.

سپس نقطهٔ انتهایی AssembleDocument را فراخوانی کنید.

REPORT_DATA_ESCAPED=$(python -c "import json,sys; print(json.dumps(open('resources/invoice-data.json','r',encoding='utf-8').read()))")
	  
curl.exe -v "https://api.groupdocs.cloud/v1.0/assembly/assemble" \
  -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "TemplateFileInfo": {
    "FilePath": "/templates/invoice-template.docx"
  },
  "SaveFormat": "pdf",
  "OutputPath": "/output/invoice-generated.pdf",
  "ReportData": $REPORT_DATA_ESCAPED
}
EOF

این دستور فاکتور را می‌سازد و در فضای ذخیره‌سازی GroupDocs Cloud در فایل /output/invoice-generated.pdf ذخیره می‌کند.

4️⃣ دانلود فاکتور تولید شده

curl.exe \
  "https://api.groupdocs.cloud/v1.0/assembly/storage/file/Output/invoice-generated.pdf" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/octet-stream" \
  -o invoice-generated.pdf

نتیجه: فاکتور آماده ارسال در اختیار شماست بدون اینکه نیاز به نوشتن کد C# داشته باشید.

نتیجه‌گیری

در این مقاله نشان دادیم GroupDocs.Assembly Cloud چگونه تولید فاکتور را ساده می‌کند:

پردازش سبُک در ابر – بدون ابزارهای سنگین شخص ثالث روی سرورهای شما.
آزادی طراحی قالب – اسناد قالب را در Word/LibreOffice تهیه کنید و در فضای ذخیره‌سازی ابر بارگذاری کنید.
اتصال داده دینامیک – JSON (یا XML) را مستقیماً پاس بدهید، با پشتیبانی از LINQ، محاسبات، حلقه‌ها و شرط‌ها.
قالب‌های خروجی متفاوت – برای ویرایش بیشتر DOCX یا برای توزیع غیرقابل ویرایش PDF را انتخاب کنید.
ادغام ساده – از SDK .NET یا چند فراخوانی cURL استفاده کنید، همراه با نمونه‌های کامل کد.

امروز شروع به خودکارسازی گردش کارهای صدور صورتحساب خود کنید؛ تنها با بارگذاری یک قالب و فراخوانی نقطهٔ انتهایی assemble!

مطالب مرتبط

GroupDocs.Assembly Cloud API Reference – https://reference.groupdocs.cloud/assembly/
GroupDocs.Assembly Cloud Documentation – https://docs.groupdocs.cloud/assembly/
Quick Start Guide for Building Document Templates – https://docs.groupdocs.cloud/assembly/getting-started/quick-start/
Working with Advanced Elements (Barcodes, Bookmarks, Hyperlinks, and More) – https://docs.groupdocs.cloud/assembly/developer-guide/working-with-other-elements/
Comprehensive Guide to Advanced Template Definition Syntax – https://docs.groupdocs.com/assembly/net/advanced-usage/

پرسش‌های متداول (FAQs)

آیا می‌توانم به جای Microsoft Word از LibreOffice Writer برای قالب استفاده کنم؟
بله. API با هر فایل DOCX کار می‌کند، صرف‌نظر از ویرایدگری که برای ساخت آن استفاده شده است.
آیا می‌توانم محاسباتی مانند مجموع یا مالیات را داخل قالب انجام دهم؟
حتماً. می‌توانید از عبارات LINQ یا محاسبات ساده در برچسب‌ها استفاده کنید، برای مثال <<[item.quantity * item.unitPrice]>>.
حداکثر حجم قالب یا فایل داده‌ای که می‌توانم بارگذاری کنم چیست؟
سرویس فایل‌های تا ۵۰۰ MB را پشتیبانی می‌کند؛ قالب‌های فاکتور معمولاً بسیار زیر این حد هستند.
آیا قبل از بارگذاری باید پوشه مقصد در فضای ذخیره‌سازی ابر را پیش‌ایجاد کنم؟
خیر. نقطه انتهایی بارگذاری به‌صورت خودکار هر پوشهٔ گمشده‌ای را در مسیر مشخص‌شده ایجاد می‌کند.
آیا دوره آزمایشی رایگان دریافت می‌کنم؟
بله، ۱۵۰ تماس API رایگان در هر ماه در اختیار شماست.

نمای کلی#

آماده‌سازی قالب فاکتور#

بارگذاری قالب در فضای ذخیره‌سازی ابر#

ایجاد منبع داده#

تولید فاکتور با SDK .NET#

تولید فاکتور با cURL#

نتیجه‌گیری#

مطالب مرتبط#

پرسش‌های متداول (FAQs)#