Створення рахунків онлайн за допомогою GroupDocs.Assembly Cloud API

Огляд

Генерування рахунків «на льоту» – це поширена потреба для біллінгових систем, платформ електронної комерції та SaaS‑додатків.
За допомогою GroupDocs.Assembly Cloud ви можете створювати професійні рахунки повністю в хмарі, не встановлюючи жодного офісного ПЗ на своїх серверах.

Ключові переваги

Гнучкість шаблонів – розробляйте макети рахунків у рідному редакторі, наприклад Microsoft Word, LibreOffice Writer тощо.
Динамічне прив’язування даних – заповнюйте шаблони даними у форматі JSON або XML, використовуючи прості заповнювачі або розширені вирази LINQ для обчислень, циклів і умовних блоків.
Кілька форматів виводу – отримуйте фінальний рахунок у DOCX для подальшого редагування або у PDF для розповсюдження лише для читання.
Безпечне сховище – доступ до шаблонів і документів, збережених у GroupDocs Cloud, здійснюється за допомогою маркерів автентифікації.
Легка інфраструктура – вся обробка виконується в хмарі GroupDocs, звільняючи ваші сервери від важких бібліотек і високих вимог до процесора чи пам’яті.

У наступних розділах ми покроково розглянемо весь процес – від підготовки шаблону та джерела даних до генерації рахунку за допомогою .NET SDK на C# і простих викликів cURL.

Підготовка шаблону рахунку

Створіть макет рахунку у вашому улюбленому настільному редакторі (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 (наступний розділ).

Завантаження шаблону у хмарне сховище

Основні кроки для коду C#

Створіть об’єкт Configuration з вашими App SID та App Key.
Ініціалізуйте клієнт 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);
}

Порада: Ви можете також завантажити файл за допомогою простого cURL‑виклику (див. розділ Генерація рахунку за допомогою cURL), якщо вам зручніше працювати з командним рядком.

Створення джерела даних

Створіть 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");

Примітка: Той самий JSON можна передати безпосередньо у тілі запиту під час використання cURL; підхід з файлом зручний для великих наборів даних.

Генерація рахунку за допомогою .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) містить повністю заповнений рахунок, готовий до надсилання клієнту.

Генерація рахунку за допомогою 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"

Якщо шаблон уже збережений (як описано у розділі «Завантаження шаблону у хмарне сховище»), цей виклик можна пропустити.

3️⃣ Зберіть рахунок

Створіть файл invoice-data.json у папці resources, як показано у розділі [Створення джерела даних {#json-data}].

Потім викличте endpoint AssembleDocument. При роботі з великими наборами даних зручніше спочатку помістити їх у змінну, а вже потім передавати в запит 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

Команда створює рахунок і зберігає його у сховищі 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

Результат: у вас є готовий до надсилання рахунок без написання жодного коду на C#.

Висновок

У цій статті ми продемонстрували, як GroupDocs.Assembly Cloud спрощує процес генерації рахунків:

Легка хмарна обробка – без важких сторонніх інструментів на ваших серверах.
Свобода дизайну шаблонів – створюйте документи‑шаблони у Word/LibreOffice і зберігайте їх у хмарному сховищі.
Динамічне прив’язування даних – передавайте JSON (або XML) напряму, з підтримкою LINQ, обчислень, циклів і умов.
Різні формати виводу – обирайте DOCX для подальшого редагування або PDF для незмінного розповсюдження.
Просте інтегрування – використовуйте .NET SDK або кілька викликів cURL, як показано у прикладах.

Починайте автоматизовувати процеси білінгу вже сьогодні: завантажте шаблон і викличте endpoint assemble!

Дивіться також

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/

Часто задавані питання (FAQs)

Чи можу я використовувати LibreOffice Writer замість Microsoft Word для мого шаблону?
Так. API працює з будь‑яким DOCX‑файлом, незалежно від того, яким редактором його створено.
Чи можна виконувати обчислення (наприклад, підсумки, податки) безпосередньо у шаблоні?
Абсолютно. Ви можете використовувати вирази LINQ або просту арифметику в заповнювачах, наприклад <<[item.quantity * item.unitPrice]>>.
Який максимальний розмір шаблону або файлу даних, який можна завантажити?
Сервіс підтримує файли розміром до 500 МБ; типові шаблони рахунків значно менші за цей ліміт.
Чи потрібно попередньо створювати цільову папку в хмарному сховищі перед завантаженням?
Ні. Endpoint завантаження автоматично створює ієрархію папок, якщо вона не існує.
Чи є безкоштовна пробна версія?
Так, доступно 150 безкоштовних API‑викликів на місяць.

Огляд#

Підготовка шаблону рахунку#

Завантаження шаблону у хмарне сховище#

Створення джерела даних#

Генерація рахунку за допомогою .NET SDK#

Генерація рахунку за допомогою cURL#

1️⃣ Отримайте токен доступу#

2️⃣ Завантажте шаблон через cURL#

3️⃣ Зберіть рахунок#

4️⃣ Завантажте готовий рахунок#

Висновок#

Дивіться також#

Часто задавані питання (FAQs)#