GroupDocs.Assembly Cloud API ile Çevrimiçi Fatura Oluşturma

Genel Bakış

Anlık fatura oluşturma, faturalama sistemleri, e-ticaret platformları ve SaaS uygulamaları için yaygın bir gereksinimdir.
GroupDocs.Assembly Cloud ile sunucularınıza herhangi bir ofis yazılımı kurmadan tamamen bulutta profesyonel faturalar oluşturabilirsiniz.

Temel faydalar

Şablon esnekliği – Microsoft Word, LibreOffice Writer vb. gibi yerel bir editörde fatura düzenleri tasarlayın.
Dinamik veri bağlama – Şablonları JSON veya XML verileriyle doldurun; basit yer tutucular veya hesaplamalar, döngüler ve koşullu bölümler için gelişmiş LINQ ifadeleri kullanın.
Birden fazla çıktı formatı – Son faturayı düzenleme için DOCX veya yalnızca okunabilir dağıtım için PDF olarak oluşturun.
Güvenli depolama – Kimlik doğrulama tokenları aracılığıyla GroupDocs Cloud’da depolanan şablon ve belgelere erişin.
Hafif ortam – Tüm işlem GroupDocs Cloud’da gerçekleşir, altyapınızı üçüncü‑taraf kütüphanelerinden veya yüksek CPU ve bellek gereksinimlerinden kurtarır.

Aşağıdaki bölümlerde, şablon ve veri kaynağı hazırlamaktan .NET SDK ile C# kullanarak ve basit cURL komutlarıyla fatura oluşturmayı içeren tüm süreci adım adım inceleyeceğiz.

Fatura Şablonunu Hazırlama

Fatura düzenini tercih ettiğiniz masaüstü editörü (Microsoft Word, LibreOffice Writer vb.) kullanarak tasarlayın.
Daha sonra sağlayacağınız JSON alanlarıyla eşleşen yer tutucu etiketler ekleyin, örneğin:

Şablon	JSON Yolu
`<<[Invoice.Number]>>`	`invoice.number`
`<<[Customer.Name]>>`	`customer.name`

Ve tablo renderleme şablonu tanımı aşağıdaki gibi görünecektir:

Açıklama	Miktar	Birim Fiyat	Maliyet
`<<foreach [in Items]>>` `<<[Description]>>`	`<<[Quantity]>>`	`$<<[UnitPrice]:"N2">>`	`$<<[Quantity*UnitPrice]:"N2">>` `<</foreach>>`

Kolaylık sağlamak için aşağıda gösterilen bir şablon örneğini indirebilirsiniz:

Veya kendi şablonunuzu oluşturup GroupDocs Cloud depolamasına yükleyin (sonraki bölüm).

Şablonu Bulut Depolamaya Yükleme

C# kodu için ana adımlar

Configuration nesnesini App SID ve App Key bilgilerinizle oluşturun.
AssemblyApi istemcisini başlatın.
Yerel şablon dosyasını bulut depolamasındaki bir yola (ör. templates/invoice-template.docx) yükleyin.

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

İpucu: Komut satırı yaklaşımını tercih ediyorsanız dosyayı basit bir cURL komutuyla da yükleyebilirsiniz (cURL ile Fatura Oluşturma bölümüne bakın).

Veri Kaynağı Oluşturma

Fatura verileriyle bir JSON oluşturun

Aşağıda, şablonda kullanılan yer tutuculara karşılık gelen örnek JSON bulunmaktadır.
invoice-data.json olarak resources klasörüne kaydedin veya doğrudan kodunuza gömün.

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

Kod içinde JSON dosyasını kullanma

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

Not: Aynı JSON, cURL kullanırken istek gövdesine satır içi olarak gönderilebilir; dosya yaklaşımı büyük veri kümeleri için uygundur.

.NET SDK ile Fatura Oluşturma

C# kodu için ana adımlar

Şablonu (zaten açıklandı) yükleyin.
JSON veri kaynağını okuyun.
AssembleOptions yapılandırın – çıktı formatını (docx veya pdf) belirleyin ve şablona bağlayın.
AssembleDocument çağırarak faturayı oluşturun.
Oluşturulan dosyayı yerel olarak ya da başka bir bulut konumuna kaydedin.

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

Sonuç: invoice-output.pdf (veya SaveFormat‘ı değiştirdiyseniz .docx) tamamen doldurulmuş faturayı içerir ve müşteriye göndermeye hazırdır.

cURL ile Fatura Oluşturma

Herhangi bir SDK kurmak ve çözümü kod içinde inşa etmek istemiyorsanız, tüm süreç basit HTTP çağrılarıyla yapılabilir.

1️⃣ Erişim tokenı alın

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"

Yanıt, access_token içerir – sonraki adımlar için değerini kopyalayın.

2️⃣ cURL ile şablonu yükleyin

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"

Şablon zaten depolanmışsa (SDK ile yükleme adımında açıklandığı gibi), bu çağrıyı atlayabilirsiniz.

3️⃣ Faturayı birleştirin

Yukarıdaki [JSON Veri Kaynağı Oluşturma {#json-data}] bölümünde gösterildiği gibi resources klasöründe invoice-data.json adlı bir JSON dosyası oluşturun.
Ve şimdi AssembleDocument uç noktasını çağırın.

Büyük fatura veri kümeleriyle çalışırken, en verimli yaklaşım, fatura verisini okumak için bir ara değişken kullanmak ve ardından bu veriyi API isteğine geçirmek.

Aşağıdaki örnek bu yaklaşımı göstermektedir:

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

Komut, faturayı oluşturur ve /output/invoice-generated.pdf dosyası olarak GroupDocs Cloud depolamasına kaydeder.

4️⃣ Oluşturulan faturayı indirin

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

Sonuç: Artık herhangi bir C# kodu yazmadan gönderime hazır bir faturanız var.

Sonuç

Bu makalede, GroupDocs.Assembly Cloud‘un fatura oluşturmayı ne kadar kolaylaştırdığını gösterdik:

Hafif bulut işleme – sunucularınızda üçüncü‑taraf ağır araçlar bulunmaz.
Şablon tasarım özgürlüğü – Word/LibreOffice’de şablon belgeleri oluşturup bulut depolamasına kaydedin.
Dinamik veri bağlama – JSON (veya XML) doğrudan besleyin; LINQ, hesaplamalar, döngüler ve koşullar desteklenir.
Farklı çıktı formatları – düzenleme için DOCX, değiştirilemez dağıtım için PDF seçin.
Basit entegrasyon – .NET SDK veya birkaç cURL çağrısını kullanın; tam kod örnekleriyle gösterilmiştir.

Bugün bir şablon yükleyip birleştirme uç noktasını çağırarak faturalama iş akışlarınızı otomatikleştirmeye başlayın!

İlgili Bağlantılar

GroupDocs.Assembly Cloud API Referansı – https://reference.groupdocs.cloud/assembly/
GroupDocs.Assembly Cloud Dokümantasyonu – https://docs.groupdocs.cloud/assembly/
Belge Şablonları Oluşturma Hızlı Başlangıç Kılavuzu – https://docs.groupdocs.cloud/assembly/getting-started/quick-start/
Gelişmiş Elemanlarla Çalışma (Barkodlar, Yer İşaretleri, Bağlantılar ve Daha Fazlası) – https://docs.groupdocs.cloud/assembly/developer-guide/working-with-other-elements/
Gelişmiş Şablon Tanım Söz Dizimi Kapsamlı Kılavuzu – https://docs.groupdocs.com/assembly/net/advanced-usage/

Sık Sorulan Sorular (SSS)

LibreOffice Writer yerine Microsoft Word kullanabilir miyim?
Evet. API, şablonu oluşturmak için kullanılan editörden bağımsız olarak herhangi bir DOCX dosyasıyla çalışır.
Şablon içinde toplamlar veya vergiler gibi hesaplamalar mümkün mü?
Kesinlikle. LINQ ifadeleri veya basit aritmetik kullanarak yer tutucularda hesaplama yapabilirsiniz, örnek: <<[item.quantity * item.unitPrice]>>.
Şablon veya veri dosyasının maksimum boyutu nedir?
Servis 500 MB’a kadar dosyayı destekler; tipik fatura şablonları bu sınırın çok çok altındadır.
Bulut depolamada hedef klasörü önceden oluşturmam gerekiyor mu?
Hayır. Yükleme uç noktası, klasör yoksa hiyerarşiyi otomatik olarak oluşturur.
Ücretsiz deneme alabilir miyim?
Evet, ayda 150 ücretsiz API çağrısı mevcuttur.

Genel Bakış#

Fatura Şablonunu Hazırlama#

Şablonu Bulut Depolamaya Yükleme#

Veri Kaynağı Oluşturma#

.NET SDK ile Fatura Oluşturma#

cURL ile Fatura Oluşturma#

Sonuç#

İlgili Bağlantılar#

Sık Sorulan Sorular (SSS)#