XGenerate — Document Assembly

Guida · API REST

Convertire Markdown in DOCX con una chiamata API

Il Suo sistema scrive Markdown: note di rilascio, rapporti, testo da un modello. Lo invii all'API e riceva un documento Word in cui titoli, elenchi, tabelle ed enfasi sono vera formattazione Word. Aggiunga il Suo template di carta intestata: il testo prende il posto del segnaposto body e gli altri campi unione vengono compilati da JSON.

Richiedi una demo Apri il contratto API

Perché non convertire il Markdown da soli

  • Un convertitore nel Suo processo produce un documento nudo; intestazione, font e stili che la Sua azienda si aspetta non stanno nel testo.
  • I convertitori a riga di comando sono un binario in più da installare e tenere aggiornato su ogni server che scrive documenti.
  • Un testo generato, da un modello o da un flusso di lavoro, deve diventare un documento che le persone possono ancora modificare e approvare.

La richiesta

Trasporto multipart: il Markdown è la parte markdown, il formato un semplice valore di form; format=DOCX restituisce il file Word, PDF le pagine renderizzate. Una parte file opzionale porta un template Word il cui segnaposto MERGEFIELD body riceve il testo, e una parte fields compila gli altri campi unione del template. Senza template si applicano solo le carte intestate della busta fields.

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

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

La risposta

La chiamata multipart restituisce il DOCX con Content-Type application/vnd.openxmlformats-officedocument.wordprocessingml.document. Il trasporto JSON restituisce filename, content, format e warnings, con il file codificato in base64 in content. Con un template, gli avvisi indicano i segnaposto per immagini, QR e carta intestata rimasti senza valore; i campi unione e le regioni senza dati vengono rimossi senza avviso. La richiesta riesce in ogni caso.

Cosa XGenerate non fa

Il Markdown copre le basi GFM: titoli, elenchi, enfasi, link, codice, citazioni e tabelle pipe. La sintassi delle immagini è ridotta al testo alternativo e nulla viene caricato dalla rete. Il testo viene renderizzato dal motore Word; layout CSS complessi e JavaScript non vengono interpretati. Per un layout che deve corrispondere a un documento esistente, il template Word è la via.

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