XGenerate — Document Assembly

Leitfaden · REST-API

Serienbrief: eine PDF pro Empfänger

Der Seriendruck in Word erzeugt ein langes Dokument. Ein API-Aufruf erzeugt ein Dokument: Schleife über Ihre Empfänger, dieselbe Vorlage mit den Werten jedes Datensatzes, jede PDF mit eindeutigem Dateinamen. Briefe, Zertifikate, Lohnabrechnungen, Rechnungen.

Demo anfragen API-Vertrag öffnen

Wo der Seriendruck in Word aufhört

  • Der Seriendruck schreibt eine Datei für alle Datensätze; die Aufteilung in einzelne PDFs braucht Makros oder Handarbeit.
  • Er braucht Word auf einem Arbeitsplatz und eine Person, die ihn startet, und passt deshalb in keinen Workflow und keinen Nachtlauf.
  • Anhänge, Dateinamen und Archivierung pro Empfänger liegen ausserhalb dessen, was der Seriendruck kann.

Die Anfrage

Eine Anfrage pro Datensatz: die Schleife baut aus jedem Empfänger einen Fields-Envelope und sendet ihn mit der Vorlage. Der Dienst ist zustandslos, Anfragen dürfen parallel laufen; den Dateinamen wählen Sie.

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)

# recipients.json holds one object per letter:
# [ { "name": "Camille Durand", "street": "12 rue de la République", "city": "69002 Lyon" }, ... ]

index=0
jq -c '.[]' recipients.json | while IFS= read -r r; do
  index=$((index + 1))
  jq -n --argjson r "$r" '{ fields: [
      { name: "recipient.name",   value: $r.name },
      { name: "recipient.street", value: $r.street },
      { name: "recipient.city",   value: $r.city } ] }' > fields.json
  out="letter-$index.pdf"
  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 "$out"
done

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"));
var recipients = new[]
{
    new { Name = "Camille Durand", Street = "12 rue de la République", City = "69002 Lyon" },
    new { Name = "Jonas Keller",   Street = "Bahnhofstrasse 10",       City = "8001 Zürich" }
};

// One request per recipient; the service is stateless, so run them in parallel if you like.
for (var index = 0; index < recipients.Length; index++)
{
    var r = recipients[index];
    var request = new
    {
        filename = "letter.docx",
        content = template,
        format = "PDF",
        fields = new
        {
            fields = new[]
            {
                new { name = "recipient.name", value = r.Name },
                new { name = "recipient.street", value = r.Street },
                new { name = "recipient.city", value = r.City }
            }
        }
    };
    var response = await http.PostAsJsonAsync(
        "https://api.xgenerate.io/v2/documents/generate", request);
    response.EnsureSuccessStatusCode();

    var result = await response.Content.ReadFromJsonAsync<GenerateResult>();
    var file = $"letter-{index + 1}.pdf";
    await File.WriteAllBytesAsync(file, Convert.FromBase64String(result!.Content));
}

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

Die Antwort

Jeder Aufruf streamt eine 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 und Bereiche 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

Es gibt keinen Batch-Endpoint: eine Anfrage pro Dokument, gesteuert von Ihrer Schleife oder Warteschlange. Der Schweizer QR-Zahlteil ist nur im PDF möglich.

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