Tạo Hóa Đơn Trực Tuyến với API GroupDocs.Assembly Cloud

Tổng quan

Việc tạo hóa đơn “mọc chờ” (on‑the‑fly) là nhu cầu phổ biến của các hệ thống thanh toán, nền tảng thương mại điện tử và ứng dụng SaaS.
Với GroupDocs.Assembly Cloud, bạn có thể tạo các hóa đơn chuyên nghiệp hoàn toàn trên đám mây mà không cần cài đặt phần mềm văn phòng nào trên máy chủ.

Lợi ích chính

Linh hoạt trong mẫu – Thiết kế bố cục hóa đơn bằng Word, LibreOffice Writer hoặc bất kỳ trình soạn thảo nào hỗ trợ xuất file DOCX.
Ràng buộc dữ liệu động – Điền dữ liệu vào mẫu bằng JSON hoặc XML; bạn có thể dùng các placeholder đơn giản hoặc các biểu thức LINQ phức tạp cho phép tính, vòng lặp và điều kiện.
Nhiều định dạng đầu ra – Tạo hóa đơn dưới dạng DOCX (có thể chỉnh sửa) hoặc PDF (đọc‑chỉ) tùy nhu cầu.
Lưu trữ an toàn – Truy cập các mẫu và tài liệu được lưu trong GroupDocs Cloud thông qua token xác thực.
Môi trường nhẹ – Toàn bộ quá trình xử lý diễn ra trên GroupDocs Cloud, giảm tải cho hạ tầng của bạn, không cần sử dụng thư viện bên thứ ba hay tài nguyên CPU, RAM cao.

Trong các phần tiếp theo, chúng tôi sẽ hướng dẫn chi tiết từng bước: từ chuẩn bị mẫu và nguồn dữ liệu, đến việc tạo hóa đơn bằng .NET SDK (C#) và bằng các lệnh cURL thuần.

Chuẩn Bị Mẫu Hóa Đơn

Thiết kế bố cục hóa đơn bằng trình soạn thảo máy tính để bàn yêu thích của bạn (Microsoft Word, LibreOffice Writer, …).

Chèn placeholder tags tương ứng với các trường JSON mà bạn sẽ cung cấp, ví dụ:

Placeholder	Đường dẫn JSON
`<<[Invoice.Number]>>`	`invoice.number`
`<<[Customer.Name]>>`	`customer.name`

Và định nghĩa bảng sẽ trông như sau:

Mô tả	Số lượng	Đơn giá	Thành tiền
`<<foreach [in Items]>>` `<<[Description]>>`	`<<[Quantity]>>`	`$<<[UnitPrice]:"N2">>`	`$<<[Quantity*UnitPrice]:"N2">>` `<</foreach>>`

Bạn có thể tải về một mẫu ví dụ dưới đây để tham khảo:

Hoặc tự tạo mẫu của mình và tải lên GroupDocs Cloud (bước tiếp theo).

Tải Mẫu Lên Lưu Trữ Đám Mây

Các bước chính cho mã C#

Tạo đối tượng Configuration với App SID và App Key của bạn.
Khởi tạo client AssemblyApi.
Tải tệp mẫu lên đường dẫn trong lưu trữ đám mây (ví dụ: templates/invoice-template.docx).

// 1️⃣ Khởi tạo cấu hình Cloud API
var config = new Configuration
{
    AppSid = "YOUR_APP_SID",      // thay bằng App SID của bạn
    AppKey = "YOUR_APP_KEY"       // thay bằng App Key của bạn
};
var assemblyApi = new AssemblyApi(config);

// 2️⃣ Đường dẫn trong cloud nơi lưu mẫu
string cloudTemplatePath = "templates/invoice-template.docx";

// 3️⃣ Mở tệp mẫu cục bộ (đảm bảo đã chuẩn bị)
using (var templateStream = File.OpenRead("resources/invoice-template.docx"))
{
    // 4️⃣ Tạo yêu cầu tải lên – API yêu cầu một stream + đường dẫn đích
    var uploadRequest = new UploadFileRequest(templateStream, cloudTemplatePath);

    // 5️⃣ Thực thi tải lên; mẫu đã sẵn sàng trong Cloud storage
    assemblyApi.UploadFile(uploadRequest);
}

Mẹo: Nếu bạn muốn thực hiện bằng dòng lệnh, có thể dùng một lệnh cURL đơn giản (xem phần Tạo Hóa Đơn bằng cURL) để tải lên.

Tạo Nguồn Dữ Liệu

JSON mẫu cho hóa đơn

Dưới đây là JSON khớp với các placeholder được sử dụng trong mẫu.

{
  "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
}

Sử dụng tệp JSON trong mã

// Đọc nội dung JSON từ file – chuỗi này sẽ được truyền cho API
string jsonData = File.ReadAllText("resources/invoice-data.json");

Lưu ý: Khi dùng cURL, bạn có thể đặt trực tiếp JSON trong phần body của yêu cầu; việc dùng tệp chỉ tiện cho dữ liệu lớn.

Tạo Hóa Đơn Bằng .NET SDK

Các bước chính cho mã C#

Upload mẫu (đã thực hiện ở trên).
Đọc nguồn dữ liệu JSON.
Cấu hình AssembleOptions – chỉ định định dạng xuất (docx hoặc pdf) và liên kết tới mẫu.
Gọi AssembleDocument để tạo hóa đơn.
Lưu tệp kết quả về máy hoặc tải lên vị trí khác trong cloud.

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

// 1️⃣ Khởi tạo Assembly API (cấu hình giống bước tải mẫu)
var config = new Configuration { AppSid = "YOUR_APP_SID", AppKey = "YOUR_APP_KEY" };
var assemblyApi = new AssemblyApi(config);

// 2️⃣ Đọc dữ liệu JSON (xem phần trước)
string jsonData = File.ReadAllText("resources/invoice-data.json");

// 3️⃣ Định nghĩa tùy chọn assemble
var assembleOptions = new AssembleOptions
{
    // Định dạng đầu ra: "docx" để chỉnh sửa, "pdf" để phát hành
    SaveFormat = "pdf",

    // Truyền toàn bộ chuỗi JSON – API sẽ tự phân tích
    ReportData = jsonData,

    // Tham chiếu tới mẫu đã tải lên
    TemplateFileInfo = new TemplateFileInfo
    {
        FilePath = "templates/invoice-template.docx"   // đường dẫn trong cloud
    }
};

// 4️⃣ Tạo đối tượng yêu cầu
var assembleRequest = new AssembleDocumentRequest(assembleOptions);

// 5️⃣ Thực thi – kết quả là stream chứa file đã tạo
var assembledDocument = assemblyApi.AssembleDocument(assembleRequest);

// 6️⃣ Lưu kết quả về máy
using (var outputStream = File.Create("output/invoice-output.pdf"))
{
    assembledDocument.CopyTo(outputStream);
}

Kết quả: invoice-output.pdf (hoặc .docx nếu thay đổi SaveFormat) chứa hoá đơn đã được điền đầy đủ, sẵn sàng gửi cho khách hàng.

Tạo Hóa Đơn Bằng cURL

Nếu bạn không muốn cài đặt SDK và muốn thực hiện toàn bộ quy trình bằng các yêu cầu HTTP, chỉ cần một vài lệnh cURL.

1️⃣ Lấy token truy cập

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"

Phản hồi sẽ chứa access_token; sao chép giá trị này cho các bước tiếp theo.

2️⃣ Tải mẫu lên (nếu chưa có)

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"

Nếu mẫu đã tồn tại trong cloud, bước này có thể bỏ qua.

3️⃣ Tạo hoá đơn

Tạo tệp invoice-data.json trong thư mục resources theo mẫu đã mô tả ở phần Tạo Nguồn Dữ Liệu.

Sau đó thực hiện:

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

Lệnh này tạo hoá đơn và lưu vào vị trí /output/invoice-generated.pdf trong lưu trữ GroupDocs Cloud.

4️⃣ Tải xuống hoá đơn đã tạo

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

Kết quả: Bạn sẽ nhận được file invoice-generated.pdf, sẵn sàng gửi cho khách hàng mà không cần viết một dòng mã C# nào.

Kết Luận

Bài viết đã chỉ ra cách GroupDocs.Assembly Cloud giúp bạn tự động hoá quy trình tạo hoá đơn:

Xử lý trên đám mây nhẹ – Không cần cài đặt phần mềm nặng trên máy chủ.
Tự do thiết kế mẫu – Tạo mẫu trong Word/LibreOffice, lưu trữ trên cloud.
Ràng buộc dữ liệu động – Cung cấp JSON (hoặc XML) trực tiếp, hỗ trợ LINQ, phép tính, vòng lặp và điều kiện.
Định dạng đầu ra đa dạng – Chọn DOCX để tiếp tục chỉnh sửa hoặc PDF để phát hành không thay đổi.
Tích hợp đơn giản – Dùng .NET SDK hoặc một vài lệnh cURL, đều có ví dụ mẫu đầy đủ.

Hãy bắt đầu tự động hoá quy trình thanh toán của bạn ngay hôm nay bằng cách tải lên mẫu và gọi endpoint assemble!

Xem Thêm

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/

Câu Hỏi Thường Gặp (FAQs)

Tôi có thể dùng LibreOffice Writer thay vì Microsoft Word cho mẫu của mình không?
Có. API hoạt động với bất kỳ tệp DOCX nào, bất kể công cụ tạo ra.
Có thể thực hiện các phép tính (ví dụ: tổng, thuế) trong mẫu không?
Chắc chắn. Bạn có thể dùng biểu thức LINQ hoặc phép tính đơn giản trong placeholder, ví dụ <<[item.quantity * item.unitPrice]>>.
Kích thước tối đa của mẫu hoặc tệp dữ liệu tôi có thể tải lên là bao nhiêu?
Dịch vụ hỗ trợ tệp lên đến 500 MB; các mẫu hoá đơn thường dưới mức này.
Tôi có cần tạo trước thư mục đích trong lưu trữ đám mây trước khi tải lên không?
Không. Endpoint tải lên sẽ tự động tạo cấu trúc thư mục nếu chưa tồn tại.
Tôi có nhận được bản dùng thử miễn phí không?
Có, bạn sẽ được cấp 150 lần gọi API miễn phí mỗi tháng.

Tổng quan#

Chuẩn Bị Mẫu Hóa Đơn#

Tải Mẫu Lên Lưu Trữ Đám Mây#

Tạo Nguồn Dữ Liệu#

Tạo Hóa Đơn Bằng .NET SDK#

Tạo Hóa Đơn Bằng cURL#

1️⃣ Lấy token truy cập#

2️⃣ Tải mẫu lên (nếu chưa có)#

3️⃣ Tạo hoá đơn#

4️⃣ Tải xuống hoá đơn đã tạo#

Kết Luận#

Xem Thêm#

Câu Hỏi Thường Gặp (FAQs)#