XGenerate — Document Assembly

Guida · API REST

Compilare un template Word dal codice, senza Word

Due chiamate. La prima legge il template e restituisce ogni segnaposto che dichiara: campi unione, regioni ripetute, slot immagine e QR. La seconda invia i valori e restituisce il PDF o il DOCX finito. Niente Word sul server, niente interop Office, nessun componente aggiuntivo.

Richiedi una demo Apri il contratto API

Cosa va storto senza un'API

  • L'interop Office su un server è lento, a thread singolo e non supportato in modalità non presidiata.
  • Modificare a mano document.xml si rompe appena qualcuno ridisegna il template in Word.
  • Gli elenchi di segnaposto divergono: il codice attende campi che il template non ha più, o ne ignora di nuovi.

La richiesta

La chiamata di estrazione prende solo il template e risponde con la busta iniziale: una voce per segnaposto, valori null. Compili quella busta e la rimandi con il template all'endpoint di generazione.

TOKEN=$(curl -sS https://auth.xgenerate.io/realms/xgenerate/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id="$XGENERATE_CLIENT_ID" \
  -d client_secret="$XGENERATE_CLIENT_SECRET" | jq -r .access_token)

# 1. Discover the placeholders: the seed envelope lists every field, region, image and QR-bill slot.
curl -sS https://api.xgenerate.io/v2/documents/fields \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@letter.docx" \
  | jq '{fields: [.fields[].name], lists: [.lists[].name], images: [.images[].name]}'

# 2. Fill it: send the same template with the values.
cat > fields.json <<'JSON'
{ "fields": [
    { "name": "recipient.name", "value": "Camille Durand" },
    { "name": "letter.date",    "value": "25.10.2026" },
    { "name": "letter.subject", "value": "Your contract renewal" } ] }
JSON

curl -sS https://api.xgenerate.io/v2/documents/generate \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@letter.docx" \
  -F "fields=@fields.json;type=application/json" \
  -F "format=PDF" \
  -o letter.pdf

Da .NET 

using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", token);

var template = Convert.ToBase64String(await File.ReadAllBytesAsync("letter.docx"));

// 1. Discover the placeholders the template declares.
var extracted = await http.PostAsJsonAsync(
    "https://api.xgenerate.io/v2/documents/fields", new { content = template });
extracted.EnsureSuccessStatusCode();
var seed = await extracted.Content.ReadFromJsonAsync<Envelope>();
// seed!.Fields holds one entry per merge field, each with Value null.

// 2. Fill them and render.
var request = new
{
    filename = "letter.docx",
    content = template,
    format = "PDF",
    fields = new
    {
        fields = new[]
        {
            new { name = "recipient.name", value = "Camille Durand" },
            new { name = "letter.subject", value = "Your contract renewal" }
        }
    }
};
var response = await http.PostAsJsonAsync(
    "https://api.xgenerate.io/v2/documents/generate", request);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadFromJsonAsync<GenerateResult>();
await File.WriteAllBytesAsync(result!.Filename, Convert.FromBase64String(result.Content));

record Field(string Name, string? Value);
record Envelope(Field[] Fields);
record GenerateResult(string Filename, string Content, string Format);

La risposta

La chiamata di estrazione restituisce la busta DocumentFields in JSON. La chiamata di generazione restituisce il PDF come byte grezzi sul trasporto multipart, oppure filename, content, format e warnings sul trasporto JSON; gli avvisi indicano gli slot immagine, QR e intestazione senza valore, e i campi unione senza dati vengono rimossi senza avviso.

Il risultato

Prima pagina della fattura di riferimento renderizzata: intestazione, blocco indirizzo, tabella delle righe e totali
La fattura di riferimento, renderizzata da un template Word con campi unione standard. Template, richiesta e PDF atteso: esempio pubblicato

Cosa XGenerate non fa

I template usano campi unione Word standard, regioni TableStart / TableEnd e segnaposto immagine tramite testo alternativo. Le espressioni di calcolo vengono valutate tramite un file di binding opzionale o l'API /bindings/evaluate, fuori dal template Word. I blocchi condizionali per valore non sono supportati; i campi IF di Word attorno a un testo sì.

Lo provi sul Suo template

Ci invii un file Word che usa oggi. Lo renderizziamo con i Suoi dati e Le restituiamo il PDF insieme al template adattato, così la Sua valutazione non deve aspettare noi.

Richiedi una demo

Guide correlate