XGenerate — Document Assembly

Leitfaden · REST-API

Markdown mit einem API-Aufruf in DOCX umwandeln

Ihr System schreibt Markdown: Release Notes, Berichte, Text aus einem Modell. Senden Sie ihn an die API und erhalten Sie ein Word-Dokument zurück, dessen Überschriften, Listen, Tabellen und Hervorhebungen echte Word-Formatierung sind. Fügen Sie Ihre Briefkopf-Vorlage hinzu, und der Text landet an ihrem body-Platzhalter, die übrigen Seriendruckfelder werden aus JSON befüllt.

Demo anfragen API-Vertrag öffnen

Warum Markdown nicht selbst umwandeln

  • Ein Konverter im eigenen Prozess liefert ein nacktes Dokument; Briefkopf, Schriften und Formatvorlagen, die Ihr Unternehmen erwartet, stehen nicht im Text.
  • Kommandozeilen-Konverter sind eine weitere Binärdatei, die auf jedem Server, der Dokumente schreibt, installiert und gepatcht werden muss.
  • Generierter Text, aus einem Modell oder einem Workflow, muss zu einem Dokument werden, das Menschen noch bearbeiten und freigeben können.

Die Anfrage

Multipart-Transport: das Markdown ist der Part markdown, das Format ein einfacher Formularwert; format=DOCX liefert die Word-Datei, PDF die gerenderten Seiten. Ein optionaler Part file trägt eine Word-Vorlage, deren Platzhalter MERGEFIELD body den Text aufnimmt; ein Part fields befüllt ihre übrigen Seriendruckfelder. Ohne Vorlage wirken aus dem fields-Umschlag nur Briefköpfe.

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. Plain Markdown: the text is the document.
curl -sS https://api.xgenerate.io/v2/documents/generate-from-markdown \
  -H "Authorization: Bearer $TOKEN" \
  -F "markdown=@release-notes.md;type=text/markdown" \
  -F "format=DOCX" \
  -o release-notes.docx

# 2. Onto a letterhead: the template's MERGEFIELD body receives the text,
#    its other merge fields are filled from the fields part.
cat > fields.json <<'JSON'
{ "fields": [ { "name": "document.date", "value": "25.10.2026" } ] }
JSON

curl -sS https://api.xgenerate.io/v2/documents/generate-from-markdown \
  -H "Authorization: Bearer $TOKEN" \
  -F "markdown=@release-notes.md;type=text/markdown" \
  -F "file=@letterhead.docx" \
  -F "fields=@fields.json;type=application/json" \
  -F "format=DOCX" \
  -o release-notes.docx

Aus .NET 

using System.Net.Http.Json;

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

// JSON transport: the Markdown travels as text, the optional letterhead template base64-encoded.
var request = new
{
    filename = "release-notes.md",
    markdown = await File.ReadAllTextAsync("release-notes.md"),
    template = Convert.ToBase64String(await File.ReadAllBytesAsync("letterhead.docx")),
    fields = new
    {
        fields = new[] { new { name = "document.date", value = "25.10.2026" } }
    },
    format = "DOCX"
};
var response = await http.PostAsJsonAsync(
    "https://api.xgenerate.io/v2/documents/generate-from-markdown", request);
response.EnsureSuccessStatusCode();

// result.Filename is "release-notes.docx": the extension follows the requested format.
var result = await response.Content.ReadFromJsonAsync<GenerateResult>();
await File.WriteAllBytesAsync(result!.Filename, Convert.FromBase64String(result.Content));

record GenerateResult(string Filename, string Content, string Format);

Die Antwort

Der Multipart-Aufruf streamt das DOCX mit Content-Type application/vnd.openxmlformats-officedocument.wordprocessingml.document zurück. Der JSON-Transport liefert filename, content, format und warnings, die Datei base64-codiert in content. Mit Vorlage nennen Warnungen Bild-, QR- und Briefkopf-Platzhalter ohne Wert; Seriendruckfelder und Bereiche ohne Daten werden ohne Warnung entfernt. Die Anfrage gelingt in beiden Fällen.

Was XGenerate nicht tut

Markdown deckt die GFM-Grundlagen ab: Überschriften, Listen, Hervorhebungen, Links, Code, Zitate und Pipe-Tabellen. Bild-Syntax wird auf ihren Alternativtext reduziert, und aus dem Netz wird nichts geladen. Der Text wird durch die Word-Engine gerendert; komplexe CSS-Layouts und JavaScript werden nicht interpretiert. Für ein Layout, das einem bestehenden Dokument entsprechen muss, ist die Word-Vorlage der Weg.

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