Leitfaden · REST-API

HTML mit einem API-Aufruf in DOCX umwandeln

Das Layout lebt als HTML in Ihrer Anwendung. Senden Sie das Dokument an die API und erhalten Sie eine Word-Datei, deren Überschriften, Absätze, Listen und Tabellen echte Word-Formatierung sind, die Ihre Anwender weiter bearbeiten können. Derselbe Aufruf mit format=PDF liefert die paginierte A4-Fassung.

Demo anfragen API-Vertrag öffnen

Warum die Word-Datei nicht im Code bauen

Eine HTML-zu-Word-Bibliothek im eigenen Prozess bindet Sie an eine Laufzeit und eine HTML-Teilmenge; der nächste Dienst in einem anderen Stack fängt von vorn an.
Die Umwandlung über Word auf einem Server bringt eine Office-Installation in Ihr Deployment und ist für den unbeaufsichtigten Betrieb nicht unterstützt.
Anwender wollen ändern, was Ihre Anwendung gerendert hat: ein PDF friert es ein, ein DOCX gibt es ihnen zurück.

Die Anfrage

Multipart-Transport: das HTML ist der Part html, das Format ein einfacher Formularwert; format=DOCX liefert die Word-Datei, PDF die paginierten Seiten. Ein optionaler Part watermark stempelt einen Text auf jede Seite. Externe Bilder und Stylesheets werden nie geladen; betten Sie Bilder als Data-URIs ein.

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 HTML body is the html part; format=DOCX returns the Word file, PDF the paginated pages.
curl -sS https://api.xgenerate.io/v2/documents/generate-from-html \
  -H "Authorization: Bearer $TOKEN" \
  -F "html=@summary.html;type=text/html" \
  -F "format=DOCX" \
  -o summary.docx

Aus .NET

using System.Net.Http.Json;

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

// JSON transport: the HTML travels as text. Inline styles and <style> blocks are kept;
// external images and stylesheets are never fetched, so embed images as data URIs.
var html = """
    <style>h1 { color: #1f2937; } td { padding: 4px 8px; }</style>
    <h1>Quarterly summary</h1>
    <p>Revenue grew by <b>12 %</b> against the previous quarter.</p>
    <table>
      <tr><th>Region</th><th>Revenue</th></tr>
      <tr><td>DACH</td><td>CHF 1.2 M</td></tr>
      <tr><td>France</td><td>CHF 0.8 M</td></tr>
    </table>
    """;
var request = new { filename = "summary.html", html, format = "DOCX" };
var response = await http.PostAsJsonAsync(
    "https://api.xgenerate.io/v2/documents/generate-from-html", request);
response.EnsureSuccessStatusCode();

// result.Filename is "summary.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. Warnungen sind Rendering-Hinweise, etwa eine Schriftersetzung oder ein auf 64 Zeichen gekürzter Wasserzeichentext; die Anfrage gelingt in beiden Fällen.

Was XGenerate nicht tut

HTML wird durch die Word-Engine mit einer unterstützten Teilmenge gerendert: Überschriften, Absätze, Inline-Formatierung, Listen, Tabellen, Inline-Style-Attribute und Style-Blöcke, Bilder als Data-URIs und CSS-Seitenumbrüche auf Absatzebene. Komplexe CSS-Layouts und JavaScript werden nicht interpretiert, externe Ressourcen nie geladen. 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