使用 GroupDocs.Assembly 雲端 API 線上建立發票

Overview

即時產生發票是計費系統、電子商務平台與 SaaS 應用程式的常見需求。
使用 GroupDocs.Assembly Cloud，您可以在完全不安裝任何辦公軟體的情況下，於雲端產生專業發票。

主要優勢

範本彈性 – 可在 Microsoft Word、LibreOffice Writer 等本機編輯器中設計發票版面。
動態資料綁定 – 使用簡單佔位標籤或進階 LINQ 表達式，將 JSON 或 XML 資料填入範本，支援計算、迴圈與條件區塊。
多種輸出格式 – 將最終發票產生成 DOCX（供後續編輯）或 PDF（唯讀發佈）。
安全儲存 – 透過驗證金鑰存取儲存在 GroupDocs Cloud 的範本與文件。
輕量環境 – 所有處理均在 GroupDocs Cloud 完成，讓您的基礎設施免除第三方函式庫或高 CPU、記憶體需求。

接下來的章節，我們將逐步說明整個流程——從準備範本與資料來源，到使用 C# 的 .NET SDK 以及純 cURL 指令產生發票。

Prepare Invoice Template

使用您慣用的桌面編輯器（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 雲端儲存（下一節說明）。

Upload Template to Cloud Storage

C# 程式碼的主要步驟

使用您的 App SID 與 App Key 建立 Configuration 物件。
初始化 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);
}

提示： 若您偏好使用命令列，也可參考 Generate Invoice with cURL 章節中的簡易 cURL 指令上傳檔案。

Create Data Source

建立符合範本佔位標籤的 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");

注意： 若使用 cURL，亦可將相同的 JSON 直接放入請求主體中；檔案方式適合資料量較大的情境。

Generate Invoice with .NET SDK

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 而定）即為已填入資料的完整發票，可直接寄送給客戶。

Generate Invoice with 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️⃣ 組合發票

先將 resources/invoice-data.json 依前述建立，接著呼叫 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

結果： 您將獲得可直接寄送的 PDF 發票，且全程未撰寫任何 C# 程式碼。

Conclusion

本文展示了 GroupDocs.Assembly Cloud 如何讓發票產生變得輕而易舉：

輕量雲端處理 – 伺服器上不需要任何第三方重型工具。
範本設計自由 – 在 Word／LibreOffice 中建立範本，並儲存至雲端。
動態資料綁定 – 直接傳遞 JSON（或 XML），支援 LINQ、計算、迴圈與條件。
多種輸出格式 – 可選 DOCX 供後續編輯，或 PDF 作為最終不可變版本。
簡易整合 – 透過 .NET SDK 或多段 cURL 呼叫即可完成，且皆附有完整範例程式碼。

立即上傳您的範本並呼叫組合端點，開始自動化您的帳務工作流程吧！

Frequently Asked Questions (FAQs)

我可以使用 LibreOffice Writer 而不是 Microsoft Word 來製作範本嗎？
可以，API 能處理任何由 LibreOffice Writer 產生的 DOCX 檔案。
能否在範本內執行計算（如總計、稅金）？
完全可以。您可以在佔位標籤中使用 LINQ 表達式或簡易算術，例如 <<[item.quantity * item.unitPrice]>>。
範本或資料檔案的最大上傳大小是多少？
服務支援最高 500 MB 的檔案，常見的發票範本遠低於此上限。
上傳前需要先在雲端儲存中建立目標資料夾嗎？
不需要，若資料夾不存在，上傳端點會自動建立。
是否提供免費試用？
有的，每月提供 150 次免費 API 呼叫。

在雲端只需幾步即可線上建立發票

Overview

Prepare Invoice Template

Upload Template to Cloud Storage

Create Data Source

Generate Invoice with .NET SDK

Generate Invoice with cURL

Conclusion

See also

Frequently Asked Questions (FAQs)

Overview#

Prepare Invoice Template#

Upload Template to Cloud Storage#

Create Data Source#

Generate Invoice with .NET SDK#

Generate Invoice with cURL#

Conclusion#

See also#

Frequently Asked Questions (FAQs)#

Overview

Prepare Invoice Template

Upload Template to Cloud Storage

Create Data Source

Generate Invoice with .NET SDK

Generate Invoice with cURL

Conclusion

See also

Frequently Asked Questions (FAQs)