Создание счетов онлайн с помощью GroupDocs.Assembly Cloud API

Обзор

Создание счетов в режиме онлайн — распространённая потребность биллинговых систем, платформ электронной коммерции и SaaS‑приложений.
С помощью GroupDocs.Assembly Cloud вы можете полностью в облаке генерировать профессиональные счета, не устанавливая офисное программное обеспечение на свои серверы.

Ключевые преимущества

Гибкость шаблонов — разрабатывайте макеты в привычном редакторе (Microsoft Word, LibreOffice Writer и др.).
Динамическое привязывание данных — заполняйте шаблоны JSON‑ или XML‑данными, используя простые заменители или сложные LINQ‑выражения для вычислений, циклов и условных блоков.
Несколько форматов вывода — получайте окончательный документ в DOCX (для дальнейшего редактирования) или PDF (для неизменяемого распространения).
Безопасное хранилище — доступ к шаблонам и документам в GroupDocs Cloud осуществляется через токены аутентификации.
Лёгкая среда — вся обработка происходит в облаке, освобождая вашу инфраструктуру от сторонних библиотек и высоких требований к процессору и памяти.

В следующих разделах мы пройдём весь процесс — от подготовки шаблона и источника данных до генерации счета с помощью .NET SDK и простых команд cURL.

Подготовка шаблона счета

Разработайте макет счета в любимом настольном редакторе (Microsoft Word, LibreOffice Writer и т.п.).
Вставьте теги‑заменители, соответствующие полям JSON, которые будете передавать позже, например:

Тег в шаблоне	Путь в JSON
`<<[Invoice.Number]>>`	`invoice.number`
`<<[Customer.Name]>>`	`customer.name`

Пример таблицы товаров в шаблоне:

Description	Quantity	Unit Price	Cost
`<nobr>`«foreach [in Items]»`</nobr><br/>`«[Description]»`	`<br/>`«[Quantity]»`	`<br/>`$«[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 можно отправить «in‑line» в теле запроса при работе с cURL; хранение в файле удобно, когда набор данных большой.

Генерация счета с помощью .NET SDK

Последовательность действий для C#

1️⃣ Инициализировать Assembly API (та же конфигурация, что и при загрузке).
2️⃣ Загрузить JSON‑данные (см. предыдущий раздел).
3️⃣ Подготовить параметры сборки.
4️⃣ Сформировать объект запроса.
5️⃣ Выполнить запрос — в ответе будет поток с готовым файлом.
6️⃣ Сохранить результат локально.

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

Результат: output/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.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️⃣ Сформировать счёт

Создайте файл invoice-data.json в папке resources (см. раздел Создание источника данных). Затем выполните запрос к конечной точке AssembleDocument.

# Считаем содержимое JSON‑файла и экранируем его
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

Результат: в текущей директории появился готовый к отправке PDF‑счёт.

Заключение

В этой статье мы продемонстрировали, как GroupDocs.Assembly Cloud упрощает генерацию счетов:

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

Начните автоматизировать биллинговые процессы уже сегодня: загрузите шаблон и вызовите конечную точку сборки!

Смотрите также

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/

Часто задаваемые вопросы (FAQ)

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

Обзор#

Подготовка шаблона счета#

Загрузка шаблона в облачное хранилище#

Создание источника данных#

Генерация счета с помощью .NET SDK#

Генерация счета с помощью cURL#

1️⃣ Получить токен доступа#

2️⃣ Загрузить шаблон (при необходимости)#

3️⃣ Сформировать счёт#

4️⃣ Скачать готовый документ#

Заключение#

Смотрите также#

Часто задаваемые вопросы (FAQ)#