Tworzenie faktur online z API GroupDocs.Assembly Cloud

Przegląd

Generowanie faktur w locie to powszechne wymaganie dla systemów rozliczeniowych, platform e‑commerce oraz aplikacji SaaS.
Z GroupDocs.Assembly Cloud możesz tworzyć profesjonalne faktury w pełni w chmurze, bez instalowania oprogramowania biurowego na własnych serwerach.

Kluczowe korzyści

Elastyczność szablonu – projektuj układy faktur w natywnym edytorze, takim jak Microsoft Word, LibreOffice Writer itp.
Dynamiczne powiązanie danych – wypełniaj szablony danymi JSON lub XML, używając prostych znaczników lub zaawansowanych wyrażeń LINQ do obliczeń, pętli i sekcji warunkowych.
Wiele formatów wyjściowych – generuj finalną fakturę jako DOCX do dalszej edycji lub jako PDF do dystrybucji tylko do odczytu.
Bezpieczne przechowywanie – uzyskaj dostęp do szablonów i dokumentów przechowywanych w GroupDocs Cloud poprzez tokeny uwierzytelniające.
Lekka infrastruktura – całe przetwarzanie odbywa się w GroupDocs Cloud, odciążając Twoje serwery z ciężkich bibliotek oraz wysokich wymagań CPU i pamięci.

W kolejnych sekcjach przeprowadzimy Cię przez cały proces – od przygotowania szablonu i źródła danych po wygenerowanie faktury przy użyciu .NET SDK w C# oraz prostych poleceń cURL.

Przygotuj szablon faktury

Zaprojektuj układ faktury w ulubionym edytorze desktopowym (Microsoft Word, LibreOffice Writer itp.).
Wstaw znaczniki zastępcze, które odpowiadają polom JSON, które podasz później, na przykład:

Szablon	Ścieżka JSON
`<<[Invoice.Number]>>`	`invoice.number`
`<<[Customer.Name]>>`	`customer.name`

Definicja szablonu renderującego tabelę może wyglądać tak:

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

Dla wygody możesz pobrać przykładowy szablon pokazany poniżej:

Lub utwórz własny szablon i prześlij go do przechowywania w GroupDocs Cloud (następna sekcja).

Prześlij szablon do przechowywania w chmurze

Główne kroki dla kodu C#

Utwórz obiekt Configuration z Twoim App SID i App Key.
Zainicjalizuj klienta AssemblyApi.
Prześlij lokalny plik szablonu na wybraną ścieżkę w przechowywaniu w chmurze (np. 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);
}

Wskazówka: możesz również przesłać plik przy użyciu prostego polecenia cURL (zobacz sekcję Generate Invoice with cURL), jeśli wolisz podejście wiersza poleceń.

Utwórz źródło danych

Utwórz JSON z danymi faktury

Poniżej znajduje się przykładowy JSON, który odpowiada znacznikom użytym w szablonie.
Zapisz go jako invoice-data.json w folderze resources lub wstaw bezpośrednio do kodu.

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

Użycie pliku JSON w kodzie

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

Uwaga: ten sam JSON można przesłać bezpośrednio w ciało żądania przy użyciu cURL; podejście z plikiem jest wygodne przy większych zestawach danych.

Generuj fakturę przy użyciu .NET SDK

Główne kroki dla kodu C#

Prześlij szablon (opisano wyżej).
Odczytaj źródło danych JSON.
Skonfiguruj AssembleOptions – określ format wyjściowy (docx lub pdf) i podaj ścieżkę do szablonu.
Wywołaj AssembleDocument, aby wygenerować fakturę.
Zapisz otrzymany plik lokalnie lub w innym miejscu w chmurze.

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

Wynik: invoice-output.pdf (lub .docx, jeśli zmienisz SaveFormat) zawiera w pełni wypełnioną fakturę gotową do wysłania klientowi.

Generuj fakturę przy użyciu cURL

Jeśli wolisz nie instalować SDK i napisać rozwiązanie w kodzie, cały proces można wykonać przy pomocy zwykłych wywołań HTTP.

1️⃣ Uzyskaj token dostępu

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"

W odpowiedzi znajduje się access_token – skopiuj jego wartość do kolejnych kroków.

2️⃣ Prześlij szablon przy użyciu 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"

Jeśli szablon jest już przechowywany (jak opisano w sekcji przesyłania przy użyciu SDK), możesz pominąć to wywołanie.

3️⃣ Złóż fakturę

Utwórz plik JSON o nazwie invoice-data.json w folderze resources, zgodnie z opisem w sekcji [Utwórz źródło danych {#json-data}].

Następnie wywołaj endpoint AssembleDocument. Przy dużych zestawach danych najefektywniej jest wczytać dane do zmiennej i przekazać je w żądaniu API. Przykład:

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

Polecenie tworzy fakturę i zapisuje ją w przechowywaniu GroupDocs Cloud pod ścieżką /output/invoice-generated.pdf.

4️⃣ Pobierz wygenerowaną fakturę

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

Wynik: masz gotową do wysłania fakturę, nie pisząc żadnego kodu w C#.

Podsumowanie

W tym artykule pokazaliśmy, jak GroupDocs.Assembly Cloud upraszcza generowanie faktur:

Lekkie przetwarzanie w chmurze – nie obciążasz własnych serwerów ciężkimi bibliotekami.
Swoboda projektowania szablonu – twórz dokumenty w Word/LibreOffice i przechowuj je w chmurze.
Dynamiczne powiązanie danych – podawaj JSON (lub XML) bezpośrednio, z obsługą LINQ, obliczeń, pętli i warunków.
Różne formaty wyjściowe – wybierz DOCX do dalszej edycji lub PDF do niezmiennej dystrybucji.
Prosta integracja – użyj .NET SDK lub kilku poleceń cURL, zilustrowanych pełnymi przykładami kodu.

Rozpocznij automatyzację procesów rozliczeniowych już dziś, przesyłając szablon i wywołując endpoint assemble!

Zobacz także

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/

Najczęściej zadawane pytania (FAQ)

Czy mogę używać LibreOffice Writer zamiast Microsoft Word do tworzenia szablonu?
Tak. API działa z każdym plikiem DOCX, niezależnie od edytora, którym został utworzony.
Czy można wykonywać obliczenia (np. sumy, podatki) wewnątrz szablonu?
Absolutnie. Możesz używać wyrażeń LINQ lub prostych działań arytmetycznych w znacznikach, np. <<[item.quantity * item.unitPrice]>>.
Jaki jest maksymalny rozmiar pliku szablonu lub danych, który mogę przesłać?
Usługa obsługuje pliki do 500 MB; typowe szablony faktur są znacznie mniejsze.
Czy muszę wcześniej utworzyć docelowy folder w przechowywaniu w chmurze przed przesłaniem?
Nie. Endpoint przesyłania automatycznie tworzy hierarchię folderów, jeśli nie istnieje.
Czy dostępna jest wersja próbna?
Tak, oferowane jest 150 darmowych wywołań API miesięcznie.

Przegląd#

Przygotuj szablon faktury#

Prześlij szablon do przechowywania w chmurze#

Utwórz źródło danych#

Generuj fakturę przy użyciu .NET SDK#

Generuj fakturę przy użyciu cURL#

Podsumowanie#

Zobacz także#

Najczęściej zadawane pytania (FAQ)#