إنشاء الفواتير عبر الإنترنت باستخدام واجهة برمجة تطبيقات GroupDocs.Assembly Cloud

نظرة عامة

إنشاء الفواتير الفورية يُعد طلبًا شائعًا لأنظمة الفوترة، منصات التجارة الإلكترونية، وتطبيقات SaaS.
مع GroupDocs.Assembly Cloud يمكنك إنشاء فواتير احترافية بالكامل في السحابة دون الحاجة لتثبيت أي برنامج مكتبي على خوادمك.

الفوائد الرئيسية

مرونة القالب – صمم تخطيطات الفاتورة في محرر أصلي مثل Microsoft Word أو LibreOffice Writer.
ربط البيانات الديناميكي – املأ القوالب ببيانات JSON أو XML، باستخدام وسوم بسيطة أو تعبيرات LINQ المتقدمة للحسابات، الحلقات، والأقسام الشرطية.
تنسيقات إخراج متعددة – احصل على الفاتورة النهائية كـ DOCX للتحرير الإضافي أو PDF للتوزيع غير القابل للتعديل.
تخزين آمن – الوصول إلى القوالب والمستندات المخزنة في GroupDocs Cloud عبر رموز المصادقة.
بيئة خفيفة – جميع المعالجات تتم على سحابة GroupDocs، مما يُحرّر بنيتك التحتية من الاعتماد على مكتبات طرف ثالث أو متطلبات CPU أو الذاكرة العالية.

في الأقسام التالية سوف نتبع العملية بالكامل – من إعداد القالب ومصدر البيانات إلى توليد الفاتورة باستخدام SDK الخاص بـ .NET بلغة C# ومع أوامر cCurl البسيطة.

إعداد قالب الفاتورة

صمم تخطيط الفاتورة باستخدام محررك المكتبي المفضّل (Microsoft Word، LibreOffice Writer، إلخ).
أدرج وسوم العنصر النائب التي تُطابق حقول 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 بسيطة.

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"

إذا كان القالب مُخزنًا بالفعل (كما في خطوة الرفع عبر SDK)، يمكنك تخطي هذا الاستدعاء.

3️⃣ تجميع الفاتورة

أنشئ ملف JSON باسم invoice-data.json داخل مجلد resources كما هو موضح في قسم [إنشاء مصدر البيانات {#json-data}].

ثم استدعِ نقطة النهاية AssembleDocument.

عند التعامل مع مجموعات بيانات فواتير كبيرة، يفضَّل استخدام متغيّر وسيط لقراءة البيانات ثم تمريره إلى طلب الـ API. المثال التالي يوضح ذلك:

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، مع أمثلة شفرة كاملة.

ابدأ بأتمتة عمليات الفوترة اليوم عبر رفع قالب واستدعاء نقطة التجميع!

أيضاً قد يهمك

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)

هل يمكنني استخدام LibreOffice Writer بدلاً من Microsoft Word للقالب؟
نعم. الواجهة تعمل مع أي ملف DOCX، بغض النظر عن المحرر الذي تم إنشاءه به.
هل يمكن إجراء حسابات (مثل الإجماليات أو الضرائب) داخل القالب؟
بالتأكيد. يمكنك استعمال تعبيرات LINQ أو عمليات حسابية بسيطة داخل وسوم العنصر النائب، مثل <<[item.quantity * item.unitPrice]>>.
ما هو الحد الأقصى لحجم ملف القالب أو ملف البيانات الذي يمكن رفعه؟
تدعم الخدمة ملفات تصل إلى 500 ميغابايت؛ عادةً ما تكون قوالب الفواتير أصغر بكثير من هذا الحد.
هل أحتاج إلى إنشاء المجلد الهدف في التخزين السحابي قبل رفع القالب؟
لا. تقوم نقطة نهاية الرفع بإنشاء هيكل المجلدات تلقائيًا إذا لم يكن موجودًا.
هل يحصل المستخدم على نسخة تجريبية مجانية؟
نعم، يتوفر 150 طلب API مجاني شهريًا.

نظرة عامة#

إعداد قالب الفاتورة#

تحميل القالب إلى تخزين السحابة#

إنشاء مصدر البيانات#

توليد الفاتورة باستخدام SDK لـ .NET#

توليد الفاتورة باستخدام cURL#

الخلاصة#

أيضاً قد يهمك#

الأسئلة المتكررة (FAQs)#