Buat Invoice Secara Online dengan GroupDocs.Assembly Cloud API

Gambaran Umum

Membuat invoice secara langsung merupakan kebutuhan umum bagi sistem penagihan, platform e‑commerce, dan aplikasi SaaS.
Dengan GroupDocs.Assembly Cloud Anda dapat membuat invoice profesional sepenuhnya di cloud tanpa menginstal perangkat lunak kantor apa pun di server Anda.

Manfaat utama

Fleksibilitas Template – Rancang tata letak invoice di editor native seperti Microsoft Word, LibreOffice Writer, dll.
Pengikatan data dinamis – Isi template dengan data JSON atau XML, menggunakan placeholder sederhana atau ekspresi LINQ lanjutan untuk perhitungan, perulangan, dan bagian bersyarat.
Berbagai format output – Hasilkan invoice akhir sebagai DOCX untuk penyuntingan lebih lanjut atau sebagai PDF untuk distribusi hanya‑baca.
Penyimpanan aman – Akses template dan dokumen yang disimpan di GroupDocs Cloud melalui token otentikasi.
Lingkungan ringan – Semua pemrosesan berjalan di GroupDocs Cloud, membebaskan infrastruktur Anda dari pustaka pihak ketiga atau kebutuhan CPU atau memori yang tinggi.

Di bagian berikutnya kami akan membimbing Anda melalui seluruh proses – dari menyiapkan template dan sumber data hingga menghasilkan invoice dengan .NET SDK menggunakan C# dan dengan perintah cURL biasa.

Siapkan Template Invoice

Rancang tata letak invoice menggunakan editor desktop pilihan Anda (Microsoft Word, LibreOffice Writer, dll.).
Sisipkan tag placeholder yang sesuai dengan bidang JSON yang akan Anda sediakan nanti, misalnya:

Placeholder	Jalur JSON
`<<[Invoice.Number]>>`	`invoice.number`
`<<[Customer.Name]>>`	`customer.name`

Definisi rendering tabel pada template akan terlihat seperti berikut:

Description	Quantity	Unit Price	Cost
`<<foreach [in Items]>>` `<<[Description]>>`	`<<[Quantity]>>`	`$<<[UnitPrice]:"N2">>`	`$<<[Quantity*UnitPrice]:"N2">>` `<</foreach>>`

Untuk kenyamanan Anda, silakan unduh contoh template yang ditampilkan di bawah ini:

Atau buat template Anda sendiri untuk diunggah ke penyimpanan GroupDocs Cloud (bagian berikutnya).

Unggah Template ke Penyimpanan Cloud

Langkah utama untuk kode C#

Buat objek Configuration dengan App SID dan App Key Anda.
Inisialisasi klien AssemblyApi.
Unggah file template lokal ke jalur di penyimpanan cloud (mis. 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: Anda juga dapat mengunggah file menggunakan perintah cURL sederhana (lihat bagian Hasilkan Invoice dengan cURL) jika Anda lebih suka pendekatan baris perintah.

Buat Sumber Data

Buat JSON dengan data invoice

Berikut adalah contoh JSON yang cocok dengan placeholder yang digunakan dalam template.
Simpan sebagai invoice-data.json di folder resources atau sematkan langsung dalam kode Anda.

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

Menggunakan file JSON dalam kode

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

Catatan: JSON yang sama dapat dikirim secara inline dalam body permintaan ketika menggunakan cURL; pendekatan file lebih nyaman untuk set data yang lebih besar.

Hasilkan Invoice dengan .NET SDK

Langkah utama untuk kode C#

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);
}

Hasil: invoice-output.pdf (atau .docx bila Anda mengubah SaveFormat) berisi invoice yang sepenuhnya terisi dan siap dikirim ke pelanggan.

Hasilkan Invoice dengan cURL

Jika Anda lebih memilih untuk tidak menginstal SDK apa pun dan membangun solusi dengan kode minimal, seluruh proses dapat dilakukan dengan panggilan HTTP biasa.

1️⃣ Dapatkan token akses

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"

Respons berisi access_token – salin nilainya untuk langkah selanjutnya.

2️⃣ Unggah template melalui 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"

Jika template sudah disimpan (seperti dijelaskan pada langkah unggah‑via‑SDK), Anda dapat melewatkan panggilan ini.

3️⃣ Siapkan file JSON bernama invoice-data.json di folder resources seperti yang ditunjukkan pada bagian [Buat Sumber Data {#json-data}].
Kemudian panggil endpoint 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

Perintah ini membuat invoice dan menyimpannya di penyimpanan GroupDocs Cloud pada file /output/invoice-generated.pdf.

4️⃣ Unduh invoice yang telah dihasilkan

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

Hasil: Anda sekarang memiliki invoice siap dikirim tanpa menulis kode C# apa pun.

Kesimpulan

Dalam artikel ini kami menunjukkan bagaimana GroupDocs.Assembly Cloud memudahkan pembuatan invoice:

Pemrosesan cloud yang ringan – tidak ada alat pihak ketiga yang berat di server Anda.
Kebebasan desain template – buat dokumen template di Word/LibreOffice dan simpan di penyimpanan cloud.
Pengikatan data dinamis – beri JSON (atau XML) secara langsung, dengan dukungan LINQ, perhitungan, perulangan, dan kondisi.
Berbagai format output – pilih DOCX untuk penyuntingan lebih lanjut atau PDF untuk distribusi yang tidak dapat diubah.
Integrasi sederhana – gunakan .NET SDK atau beberapa panggilan cURL, diilustrasikan dengan contoh kode lengkap.

Mulailah mengotomatiskan alur kerja penagihan Anda hari ini dengan mengunggah template dan memanggil endpoint assemble!

Lihat Juga

Referensi API GroupDocs.Assembly Cloud – https://reference.groupdocs.cloud/assembly/
Dokumentasi GroupDocs.Assembly Cloud – https://docs.groupdocs.cloud/assembly/
Panduan Memulai Cepat untuk Membangun Template Dokumen – https://docs.groupdocs.cloud/assembly/getting-started/quick-start/
Bekerja dengan Elemen Lanjutan (Barcode, Bookmark, Hyperlink, dan Lainnya) – https://docs.groupdocs.cloud/assembly/developer-guide/working-with-other-elements/
Panduan Komprehensif untuk Sintaks Definisi Template Lanjutan – https://docs.groupdocs.com/assembly/net/advanced-usage/

Pertanyaan yang Sering Diajukan (FAQ)

Apakah saya dapat menggunakan LibreOffice Writer alih-alih Microsoft Word untuk template saya?
Ya. API bekerja dengan file DOCX apa pun, terlepas dari editor yang digunakan untuk membuatnya.
Apakah memungkinkan melakukan perhitungan (mis., total, pajak) di dalam template?
Tentu saja. Anda dapat menggunakan ekspresi LINQ atau aritmetika sederhana dalam placeholder, misalnya <<[item.quantity * item.unitPrice]>>.
Berapa ukuran maksimum file template atau data yang dapat saya unggah?
Layanan mendukung file hingga 500 MB; template invoice tipikal jauh di bawah batas ini.
Apakah saya harus membuat folder target di penyimpanan cloud sebelum mengunggah?
Tidak. Endpoint unggah membuat hierarki folder secara otomatis jika tidak ada.
Apakah saya mendapatkan percobaan gratis?
Ya, tersedia 150 panggilan API gratis per bulan.

Gambaran Umum#

Siapkan Template Invoice#

Unggah Template ke Penyimpanan Cloud#

Buat Sumber Data#

Hasilkan Invoice dengan .NET SDK#

Hasilkan Invoice dengan cURL#

Kesimpulan#

Lihat Juga#

Pertanyaan yang Sering Diajukan (FAQ)#