Overview
실시간으로 인보이스를 생성하는 것은 청구 시스템, 전자상거래 플랫폼, SaaS 애플리케이션 등에서 흔히 요구되는 기능입니다.
GroupDocs.Assembly Cloud를 사용하면 서버에 오피스 소프트웨어를 설치하지 않고도 완전한 클라우드 환경에서 전문가 수준의 인보이스를 만들 수 있습니다.
주요 장점
- 템플릿 유연성 – Microsoft Word, LibreOffice Writer 등 익숙한 편집기로 인보이스 레이아웃을 디자인할 수 있습니다.
- 동적 데이터 바인딩 – JSON 또는 XML 데이터를 사용해 템플릿에 데이터를 채우며, 계산, 반복, 조건 구문 등을 LINQ 표현식으로 구현할 수 있습니다.
- 다양한 출력 포맷 – 편집 가능한 DOCX와 최종 배포용 PDF 중 선택하여 인보이스를 생성합니다.
- 안전한 저장소 – 인증 토큰을 통해 GroupDocs Cloud에 저장된 템플릿과 문서에 접근합니다.
- 경량 환경 – 모든 처리 과정이 GroupDocs Cloud에서 진행되므로 서버 인프라에 별도의 라이브러리나 고성능 CPU·메모리가 필요하지 않습니다.
아래 섹션에서는 템플릿과 데이터 소스를 준비하고, .NET SDK(C#)와 순수 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 Cloud 스토리지에 업로드합니다.
Upload Template to Cloud Storage
C# 코드 주요 단계
1️⃣ Configuration 객체에 App SID와 App Key를 설정합니다.
2️⃣ AssemblyApi 클라이언트를 초기화합니다.
3️⃣ 로컬 템플릿 파일을 클라우드 스토리지의 경로(예: 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);
}
Tip: 명령줄을 선호한다면 아래 cURL을 이용한 인보이스 생성 섹션에 나와 있는 간단한 cURL 명령으로도 파일을 업로드할 수 있습니다.
Create Data Source
인보이스 데이터를 담은 JSON 작성
아래 예시는 템플릿에 사용된 플레이스홀더와 일치하는 JSON 구조입니다.resources 폴더에 invoice-data.json 파일로 저장하거나 코드에 직접 포함해 사용할 수 있습니다.
{
"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");
Note: cURL를 사용할 경우 요청 본문에 JSON을 그대로 삽입해도 무방합니다. 파일 방식은 데이터 양이 많을 때 편리합니다.
Generate Invoice with .NET SDK
C# 코드 주요 단계
1️⃣ 템플릿 업로드(위 단계)
2️⃣ JSON 데이터 로드
3️⃣ AssembleOptions 설정 – 출력 형식(docx 또는 pdf)과 템플릿 경로 지정
4️⃣ AssembleDocument 호출로 인보이스 생성
5️⃣ 생성된 파일을 로컬 또는 다른 클라우드 위치에 저장
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);
}
Result:
invoice-output.pdf(또는SaveFormat을docx로 바꾸면.docx) 파일이 생성되어 고객에게 바로 전달하거나 추가 편집이 가능합니다.
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️⃣ 인보이스 조합(Assemble)
위 Create Data Source 섹션에 소개된 invoice-data.json 파일을 resources 폴더에 준비합니다.
대용량 데이터셋을 다룰 때는 파일 내용을 변수에 담아 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
위 명령은 인보이스를 생성하고 결과 파일을 /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
Result: 코드 작성 없이 바로 사용 가능한 인보이스 파일이 로컬에 저장됩니다.
Conclusion
이번 글에서는 GroupDocs.Assembly Cloud를 활용해 인보이스 생성 작업을 얼마나 간단히 자동화할 수 있는지 살펴보았습니다.
- 경량 클라우드 처리 – 서버에 무거운 서드파티 툴이 필요 없습니다.
- 템플릿 설계 자유도 – Word·LibreOffice 등 익숙한 편집기로 템플릿을 만든 뒤 클라우드에 저장합니다.
- 동적 데이터 바인딩 – JSON(또는 XML) 그대로 전달하고 LINQ, 계산식, 반복·조건 구문을 지원합니다.
- 다양한 출력 포맷 – 편집 가능한 DOCX와 읽기 전용 PDF 중 선택 가능합니다.
- 쉬운 통합 – .NET SDK 또는 몇 줄의 cURL 명령만으로 구현할 수 있습니다.
템플릿을 업로드하고 Assemble 엔드포인트를 호출하기만 하면 청구 업무 자동화가 바로 시작됩니다. 지금 바로 시도해 보세요!
See also
- 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/
Frequently Asked Questions (FAQs)
LibreOffice Writer를 사용해도 템플릿을 만들 수 있나요?
네. 어떤 편집기로 만든 DOCX 파일이든 API에서 동일하게 동작합니다.템플릿 안에서 계산(예: 합계, 세금 등)을 수행할 수 있나요?
가능합니다. 플레이스홀더에 LINQ 식이나 단순 산술식을 넣으면 됩니다. 예:<<[item.quantity * item.unitPrice]>>.템플릿이나 데이터 파일의 최대 크기는 어느 정도인가요?
서비스는 최대 500 MB까지 지원합니다. 일반적인 인보이스 템플릿은 이보다 훨씬 작습니다.업로드 전에 클라우드 스토리지에 대상 폴더를 미리 만들어야 하나요?
필요 없습니다. 업로드 엔드포인트가 폴더가 없을 경우 자동으로 생성합니다.무료 체험을 제공하나요?
네, 월 150회까지 무료 API 호출이 가능합니다.