XGenerate — Document Assembly

Leitfaden · REST-API

Word-Vorlage aus Code ausfüllen, ohne Word

Zwei Aufrufe. Der erste liest die Vorlage und liefert jeden deklarierten Platzhalter: Seriendruckfelder, wiederholte Bereiche, Bild- und QR-Slots. Der zweite sendet die Werte und liefert das fertige PDF oder DOCX. Kein Word auf dem Server, kein Office-Interop, kein Add-in.

Demo anfragen API-Vertrag öffnen

Was ohne API schiefgeht

  • Office-Interop auf einem Server ist langsam, single-threaded und für unbeaufsichtigten Betrieb nicht unterstützt.
  • Handgeschriebenes document.xml bricht, sobald jemand die Vorlage in Word umgestaltet.
  • Platzhalterlisten driften: der Code erwartet Felder, die die Vorlage nicht mehr hat, oder übersieht neue.

Die Anfrage

Der Extraktionsaufruf nimmt nur die Vorlage und antwortet mit dem Seed-Envelope: ein Eintrag pro Platzhalter, Werte null. Befüllen Sie diesen Envelope und senden Sie ihn mit der Vorlage an den Generate-Endpoint.

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

Aus .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);

Die Antwort

Der Extraktionsaufruf liefert den DocumentFields-Envelope als JSON. Der Generate-Aufruf streamt das PDF beim Multipart-Transport zurück oder liefert filename, content, format und warnings beim JSON-Transport; Warnungen nennen Bild-, QR- und Briefkopf-Slots ohne Wert, Seriendruckfelder ohne Daten werden ohne Warnung entfernt.

Das Ergebnis

Erste Seite der gerenderten Referenzrechnung: Briefkopf, Adressblock, Positionstabelle und Summen
Die Referenzrechnung, gerendert aus einer Word-Vorlage mit Standard-Seriendruckfeldern. Vorlage, Anfrage und erwartetes PDF: bereitgestelltes Beispiel

Was XGenerate nicht tut

Vorlagen nutzen Standard-Seriendruckfelder, TableStart/TableEnd-Bereiche und Bildplatzhalter per Alternativtext. Berechnete Ausdrücke werden über einen optionalen Bindings-Sidecar oder die API /bindings/evaluate ausgewertet, nicht direkt in der Word-Vorlage. Bedingte Blöcke nach Datenwert werden nicht unterstützt; Word-IF-Felder um Text schon.

Testen Sie es mit Ihrer eigenen Vorlage

Schicken Sie uns eine Word-Datei, die Sie heute verwenden. Wir rendern sie mit Ihren Daten und senden das PDF zusammen mit der angepassten Vorlage zurück — Ihre Evaluation muss nicht auf uns warten.

Demo anfragen

Verwandte Leitfäden