Crea fatture online con l'API GroupDocs.Assembly Cloud

Panoramica

Generare fatture al volo è una necessità comune per i sistemi di fatturazione, le piattaforme di e‑commerce e le applicazioni SaaS.
Con GroupDocs.Assembly Cloud è possibile creare fatture professionali interamente nel cloud, senza installare software di ufficio sui propri server.

Vantaggi principali

Flessibilità del modello – Progetta il layout della fattura in editor nativi come Microsoft Word, LibreOffice Writer, ecc.
Collegamento dati dinamico – Popola i modelli con dati JSON o XML, usando semplici segnaposto o espressioni LINQ avanzate per calcoli, cicli e sezioni condizionali.
Molteplici formati di output – Genera la fattura finale in DOCX per ulteriori modifiche o in PDF per distribuzione in sola lettura.
Archiviazione sicura – Accedi ai modelli e ai documenti memorizzati in GroupDocs Cloud tramite token di autenticazione.
Ambiente leggero – Tutta l’elaborazione avviene su GroupDocs Cloud, liberando la tua infrastruttura da librerie di terze parti o da elevati requisiti di CPU e memoria.

Nelle sezioni seguenti vedremo l’intero processo – dalla preparazione del modello e della fonte dati alla generazione della fattura con il .NET SDK (C#) e con semplici comandi cURL.

Prepara il modello di fattura

Progetta il layout della fattura usando il tuo editor desktop preferito (Microsoft Word, LibreOffice Writer, ecc.).
Inserisci tag segnaposto che corrispondano ai campi JSON che fornirai in seguito, ad esempio:

Modello	Percorso JSON
`<<[Invoice.Number]>>`	`invoice.number`
`<<[Customer.Name]>>`	`customer.name`

E la definizione del rendering della tabella avrà questo aspetto:

Descrizione	Quantità	Prezzo unitario	Costo
`<<foreach [in Items]>>` `<<[Description]>>`	`<<[Quantity]>>`	`$<<[UnitPrice]:"N2">>`	`$<<[Quantity*UnitPrice]:"N2">>` `<</foreach>>`

Per comodità, scarica l’esempio di modello mostrato qui sotto:

Oppure crea il tuo modello e caricalo nello storage di GroupDocs Cloud (sezione successiva).

Carica il modello nello storage cloud

Passaggi principali per il codice C#

Crea un oggetto Configuration con il tuo App SID e App Key.
Inizializza il client AssemblyApi.
Carica il file modello locale in un percorso nello storage cloud (ad es. 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);
}

Suggerimento: Puoi anche caricare il file usando un semplice comando cURL (vedi la sezione Genera fattura con cURL) se preferisci un approccio da riga di comando.

Crea la fonte dati

Crea un JSON con i dati della fattura

Di seguito è riportato un esempio di JSON che corrisponde ai segnaposto usati nel modello.
Salvalo come invoice-data.json nella cartella resources o incorporalo direttamente nel tuo codice.

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

Utilizza il file JSON nel codice

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

Nota: Lo stesso JSON può essere inviato inline nel corpo della richiesta quando si usa cURL; il metodo basato su file è più comodo per set di dati più grandi.

Genera la fattura con .NET SDK

Passaggi principali per il codice C#

Carica il modello (già trattato).
Leggi la fonte dati JSON.
Configura AssembleOptions – specifica il formato di output (docx o pdf) e collega il modello.
Chiama AssembleDocument per generare la fattura.
Salva il file risultante localmente o in un altro percorso cloud.

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

Risultato: invoice-output.pdf (o .docx se hai cambiato SaveFormat) contiene la fattura completamente popolata, pronta per essere inviata al cliente.

Genera la fattura con cURL

Se preferisci non installare alcun SDK e realizzare la soluzione solo con chiamate HTTP, l’intero processo può essere eseguito con semplici comandi cURL.

1️⃣ Ottieni un token di accesso

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"

La risposta contiene access_token – copialo per i prossimi step.

2️⃣ Carica il modello 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 il modello è già presente (come descritto nella sezione upload tramite SDK), puoi saltare questa chiamata.

3️⃣ Assembla la fattura

Crea un file JSON chiamato invoice-data.json nella cartella resources come mostrato nella sezione [Crea la fonte dati {#json-data}].

Quando si lavora con grandi volumi di dati di fatturazione, è più efficiente usare una variabile intermedia per leggere i dati e passarli nella richiesta API. L’esempio seguente dimostra questo approccio:

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

Il comando crea la fattura e la memorizza nello storage di GroupDocs Cloud nel file /output/invoice-generated.pdf.

4️⃣ Scarica la fattura generata

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

Risultato: Hai ora una fattura pronta per l’invio senza scrivere alcun codice C#.

Conclusione

In questo articolo abbiamo mostrato come GroupDocs.Assembly Cloud renda la generazione delle fatture semplice e priva di sforzi:

Elaborazione cloud leggera – nessuno strumento di terze parti pesante sui tuoi server.
Libertà nella progettazione del modello – crea documenti modello in Word/LibreOffice e archiviali nello storage cloud.
Collegamento dati dinamico – alimenta direttamente JSON (o XML), con supporto a LINQ, calcoli, cicli e condizioni.
Formati di output diversi – scegli DOCX per ulteriori modifiche o PDF per distribuzione immutabile.
Integrazione semplice – usa il .NET SDK o le chiamate cURL, illustrati con esempi completi.

Inizia oggi ad automatizzare i tuoi flussi di fatturazione caricando un modello e chiamando l’endpoint assemble!

Vedi anche

GroupDocs.Assembly Cloud API Reference – https://reference.groupdocs.cloud/assembly/
GroupDocs.Assembly Cloud Documentation – https://docs.groupdocs.cloud/assembly/
Guida rapida per la creazione di modelli di documento – https://docs.groupdocs.cloud/assembly/getting-started/quick-start/
Lavorare con elementi avanzati (Codici a barre, Segnalibri, Collegamenti ipertestuali, ecc.) – https://docs.groupdocs.cloud/assembly/developer-guide/working-with-other-elements/
Guida completa alla sintassi avanzata di definizione dei modelli – https://docs.groupdocs.com/assembly/net/advanced-usage/

Domande frequenti (FAQ)

Posso usare LibreOffice Writer invece di Microsoft Word per il modello?
Sì. L’API funziona con qualsiasi file DOCX, indipendentemente dall’editor usato per crearlo.
È possibile eseguire calcoli (es. totali, tasse) all’interno del modello?
Assolutamente. Puoi usare espressioni LINQ o semplici operazioni aritmetiche nei segnaposto, ad esempio <<[item.quantity * item.unitPrice]>>.
Qual è la dimensione massima di un modello o file dati che posso caricare?
Il servizio supporta file fino a 500 MB; i tipici modelli di fattura sono ben al di sotto di questo limite.
Devo pre‑creare la cartella di destinazione nello storage cloud prima di caricare?
No. L’endpoint di upload crea automaticamente la gerarchia di cartelle se non esiste.
Ottengo una prova gratuita?
Sì, sono disponibili 150 chiamate API gratuite al mese.

Panoramica#

Prepara il modello di fattura#

Carica il modello nello storage cloud#

Crea la fonte dati#

Genera la fattura con .NET SDK#

Genera la fattura con cURL#

Conclusione#

Vedi anche#

Domande frequenti (FAQ)#