XGenerate — Document Assembly

Leitfaden · REST-API

Eine DOCX-Template-Engine, die Sie aufrufen statt installieren

Standard-Seriendruckfelder, TableStart- und TableEnd-Bereiche, Bildplatzhalter: die Vorlage bleibt eine normale .docx, die jeder bearbeiten kann. Ihr Code sendet Datei und Daten, die Engine liefert das fertige Dokument. Nichts zu installieren, kein Word auf dem Server, keine Syntax zu lernen.

Demo anfragen API-Vertrag öffnen

Was eine Bibliothek im eigenen Prozess kostet

  • Eine DOCX-Bibliothek bindet Sie an eine Sprache und eine Laufzeit; der nächste Dienst in einem anderen Stack fängt von vorn an.
  • Wer Dokumente über Word auf einem Server rendert, muss zusätzlich zur Anwendung eine Office-Installation pflegen und aktualisieren.
  • Engines mit eigener Platzhalter-Syntax machen jede Vorlage zur Entwicklerarbeit.

Die Anfrage

Der curl-Aufruf zeigt den Multipart-Transport; die Beispiele für .NET, Java und Python darunter nutzen den JSON-Transport (Vorlage base64-codiert in content) oder Multipart, je nachdem, was im jeweiligen Stack bequem ist. Der Fields-Envelope ist überall derselbe.

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)

# The template is a plain .docx with MERGEFIELD placeholders and a TableStart:items region.
curl -sS https://api.xgenerate.io/v2/documents/generate \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@contract.docx" \
  -F "fields=@fields.json;type=application/json" \
  -F "format=PDF" \
  -o contract.pdf

Aus .NET 

using System.Net.Http.Json;

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

var request = new
{
    filename = "contract.docx",
    content = Convert.ToBase64String(await File.ReadAllBytesAsync("contract.docx")),
    format = "PDF",
    fields = new
    {
        fields = new[] { new { name = "customer.name", value = "Alpenblick Consulting AG" } }
    }
};
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 GenerateResult(string Filename, string Content, string Format);

From Java 

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

var template = Base64.getEncoder().encodeToString(Files.readAllBytes(Path.of("contract.docx")));
var body = """
    {"filename": "contract.docx", "content": "%s", "format": "PDF",
     "fields": {"fields": [{"name": "customer.name", "value": "Alpenblick Consulting AG"}]}}
    """.formatted(template);

var request = HttpRequest.newBuilder(URI.create("https://api.xgenerate.io/v2/documents/generate"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

// response.body() holds filename, content (base64), format and warnings:
// parse it with your JSON library and Base64-decode content into contract.pdf.

From Python 

import requests

token = "..."  # client-credentials token from auth.xgenerate.io

with open("contract.docx", "rb") as template, open("fields.json", "rb") as fields:
    response = requests.post(
        "https://api.xgenerate.io/v2/documents/generate",
        headers={"Authorization": f"Bearer {token}"},
        files={
            "file": ("contract.docx", template),
            "fields": ("fields.json", fields, "application/json"),
        },
        data={"format": "PDF"},
        timeout=60,
    )
response.raise_for_status()

with open("contract.pdf", "wb") as out:
    out.write(response.content)

Die Antwort

Rohbytes beim Multipart-Transport, ein JSON-Objekt mit filename, content, format und warnings beim JSON-Transport. Warnungen nennen Bild-, QR- und Briefkopf-Platzhalter ohne Wert sowie Rendering-Hinweise wie Schriftersetzungen; Seriendruckfelder und Bereiche ohne Daten werden ohne Warnung entfernt. Die Anfrage gelingt in beiden Fällen.

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