Criar faturas online com a API GroupDocs.Assembly Cloud

Visão geral

Gerar faturas em tempo real é uma necessidade comum para sistemas de faturação, plataformas de comércio eletrónico e aplicações SaaS.
Com GroupDocs.Assembly Cloud pode criar faturas profissionais totalmente na nuvem, sem instalar nenhum software de escritório nos seus servidores.

Principais benefícios

Flexibilidade de modelo – Desenhe o layout da fatura num editor nativo como Microsoft Word, LibreOffice Writer, etc.
Ligação dinâmica de dados – Preencha os modelos com dados JSON ou XML, usando marcadores simples ou expressões LINQ avançadas para cálculos, loops e seções condicionais.
Vários formatos de saída – Gere a fatura final em DOCX para edição adicional ou em PDF para distribuição só de leitura.
Armazenamento seguro – Aceda a modelos e documentos armazenados na GroupDocs Cloud através de tokens de autenticação.
Ambiente leve – Todo o processamento ocorre na GroupDocs Cloud, libertando a sua infraestrutura de bibliotecas de terceiros ou de exigências elevadas de CPU ou memória.

Nas secções seguintes vamos percorrer todo o processo – desde a preparação do modelo e da fonte de dados até à geração da fatura com o SDK .NET em C# e com comandos cURL simples.

Preparar o modelo de fatura

Desenhe o layout da fatura usando o seu editor de desktop preferido (Microsoft Word, LibreOffice Writer, etc.).
Insira marcadores de posição que correspondam aos campos JSON que irá fornecer mais tarde, por exemplo:

Marcador	Caminho JSON
`<<[Invoice.Number]>>`	`invoice.number`
`<<[Customer.Name]>>`	`customer.name`

E a definição do modelo de renderização de tabela ficará da seguinte forma:

Descrição	Quantidade	Preço Unitário	Custo
`<<foreach [in Items]>>` `<<[Description]>>`	`<<[Quantity]>>`	`$<<[UnitPrice]:"N2">>`	`$<<[Quantity*UnitPrice]:"N2">>` `<</foreach>>`

Para sua conveniência, pode descarregar um exemplo de modelo apresentado abaixo:

Ou crie o seu próprio modelo e carregue‑o para o armazenamento Cloud da GroupDocs (secção seguinte).

Carregar o modelo para o armazenamento Cloud

Passos principais para o código C#

Crie um objeto Configuration com o seu App SID e App Key.
Inicialize o cliente AssemblyApi.
Carregue o ficheiro de modelo local para um caminho no armazenamento cloud (por exemplo templates/invoice-template.docx).

// 1️⃣ Initialise 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);
}

Dica: Também pode carregar o ficheiro usando um simples comando cURL (veja a secção Gerar fatura com cURL) se preferir uma abordagem linha de comando.

Criar a fonte de dados

Construa um JSON com os dados da fatura

Abaixo está o JSON de exemplo que corresponde aos marcadores de posição usados no modelo.
Guarde‑o como invoice-data.json na pasta resources ou incorpore‑o diretamente no seu código.

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

Usar o ficheiro JSON no código

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

Nota: O mesmo JSON pode ser enviado diretamente no corpo da requisição ao usar cURL; a abordagem por ficheiro é conveniente para conjuntos de dados maiores.

Gerar fatura com o SDK .NET

Passos principais para o código C#

Carregar o modelo (já tratado).
Ler a fonte de dados JSON.
Configurar AssembleOptions – especificar o formato de saída (docx ou pdf) e referir o modelo.
Invocar AssembleDocument para gerar a fatura.
Gravar o ficheiro resultante localmente ou numa outra localização na cloud.

using GroupDocs.Assembly.Cloud.Sdk;
using GroupDocs.Assembly.Cloud.Sdk.Model;
using GroupDocs.Assembly.Cloud.Sdk.Model.Requests;
using System.IO;

// 1️⃣ Initialise 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);
}

Resultado: invoice-output.pdf (ou .docx se mudar SaveFormat) contém a fatura totalmente preenchida pronta para ser enviada ao cliente.

Gerar fatura com cURL

Se preferir não instalar nenhum SDK e construir a solução em código, todo o processo pode ser executado com chamadas HTTP simples.

1️⃣ Obter um token de acesso

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"

A resposta contém access_token – copie o seu valor para os passos seguintes.

2️⃣ Carregar o modelo via 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"

Se o modelo já estiver armazenado (conforme descrito na secção de carregamento via SDK), pode ignorar esta chamada.

3️⃣ Montar a fatura

Crie um ficheiro JSON chamado invoice-data.json na pasta resources conforme descrito na secção [Criar a fonte de dados {#json-data}] acima.

Em seguida, chame o endpoint AssembleDocument.

Ao trabalhar com grandes volumes de faturas, a abordagem mais eficiente consiste em usar uma variável intermédia para ler os dados da fatura e depois passá‑los à requisição API. O exemplo abaixo demonstra este método:

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

O comando constrói a fatura e armazena‑a no armazenamento Cloud da GroupDocs no ficheiro /output/invoice-generated.pdf.

4️⃣ Descarregar a fatura gerada

Para descarregar a fatura, basta executar o seguinte comando:

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

Resultado: agora tem uma fatura pronta a ser enviada, sem escrever nenhuma linha de código C#.

Conclusão

Neste artigo demonstrámos como o GroupDocs.Assembly Cloud simplifica a geração de faturas:

Processamento leve na nuvem – sem ferramentas externas pesadas nos seus servidores.
Liberdade de design de modelo – crie documentos‑modelo no Word/LibreOffice e armazene‑os na cloud.
Ligação dinâmica de dados – alimente JSON (ou XML) directamente, com suporte a LINQ, cálculos, loops e condicionais.
Vários formatos de saída – escolha DOCX para edição adicional ou PDF para distribuição imutável.
Integração simples – use o SDK .NET ou alguns comandos cURL, ilustrados com exemplos completos.

Comece a automatizar os seus fluxos de faturação hoje, carregando um modelo e invocando o endpoint Assemble!

Ver também

GroupDocs.Assembly Cloud API Reference – https://reference.groupdocs.cloud/assembly/
GroupDocs.Assembly Cloud Documentation – https://docs.groupdocs.cloud/assembly/
Guia de início rápido para criação de modelos de documento – https://docs.groupdocs.cloud/assembly/getting-started/quick-start/
Trabalhando com elementos avançados (códigos de barras, marcadores, hiperligações, etc.) – https://docs.groupdocs.cloud/assembly/developer-guide/working-with-other-elements/
Guia abrangente da sintaxe avançada de definição de modelo – https://docs.groupdocs.com/assembly/net/advanced-usage/

Perguntas Frequentes (FAQs)

Posso usar o LibreOffice Writer em vez do Microsoft Word para o meu modelo?
Sim. A API funciona com qualquer ficheiro DOCX, independentemente do editor usado para o criar.
É possível efectuar cálculos (por exemplo, totais, impostos) dentro do modelo?
Absolutamente. Pode usar expressões LINQ ou aritméticas simples nos marcadores, por exemplo, <<[item.quantity * item.unitPrice]>>.
Qual é o tamanho máximo de um modelo ou ficheiro de dados que posso carregar?
O serviço aceita ficheiros até 500 MB; os modelos de fatura típicos ficam muito abaixo desse limite.
Preciso pré‑criar a pasta de destino no armazenamento Cloud antes de carregar?
Não. O endpoint de upload cria a hierarquia de pastas automaticamente caso não exista.
Existe um teste gratuito?
Sim, são disponibilizadas 150 chamadas de API gratuitas por mês.

Visão geral#

Preparar o modelo de fatura#

Carregar o modelo para o armazenamento Cloud#

Criar a fonte de dados#

Gerar fatura com o SDK .NET#

Gerar fatura com cURL#

Conclusão#

Ver também#

Perguntas Frequentes (FAQs)#