Guide · API REST

Générer un PDF à partir de XML et d'un modèle Word

Vos données quittent le système source en XML : une commande, un export, un message. La mise en page est un modèle Word avec des champs de fusion standard. L'adaptateur qui mappe vos éléments et attributs sur les champs du modèle est livré dans le cadre de votre intégration ; l'appel de génération derrière lui est celui qui sert déjà les appelants JSON et renvoie le PDF ou le DOCX fini.

Demander une démo Ouvrir le contrat d'API

Pourquoi ne pas construire le PDF depuis XML vous-même

Une chaîne de feuilles de style de XML vers des objets de formatage fait de la mise en page un artefact de développeur ; les responsables du document ne peuvent plus la modifier.
Une bibliothèque PDF alimentée par du XML analysé lie la mise en page à un environnement d'exécution ; chaque changement de texte part avec une livraison.
Chaque format de modèle avec sa propre syntaxe impose une formation et des modèles captifs.

La requête

L'API d'aujourd'hui prend l'enveloppe fields, pas du XML. L'adaptateur XML est livré dans le cadre de votre intégration (suivi sous xgenerateio/xgenerate#364) : il mappe vos éléments et attributs sur des champs scalaires et les éléments répétés sur des lignes de liste, nommés d'après les codes MERGEFIELD du modèle. L'exemple montre le XML, l'enveloppe qu'il devient et l'appel de génération qui existe aujourd'hui.

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. Your XML as it leaves the source system.
cat > invoice.xml <<'XML'
<invoice number="2026-0042" date="2026-10-25">
  <recipient>
    <name>Camille Durand</name>
  </recipient>
  <lines>
    <line description="Consulting, October" amount="CHF 4'800.00"/>
    <line description="Travel expenses" amount="CHF 312.40"/>
  </lines>
</invoice>
XML

# 2. The fields envelope the XML adapter produces (delivered as part of your
#    integration): elements and attributes become fields, repeating elements
#    become list rows. Names match the MERGEFIELD codes in the Word template.
cat > fields.json <<'JSON'
{
  "fields": [
    { "name": "invoice.number", "value": "2026-0042" },
    { "name": "invoice.date",   "value": "2026-10-25" },
    { "name": "recipient.name", "value": "Camille Durand" }
  ],
  "lists": [
    { "name": "invoice.lines", "value": [
      { "fields": [ { "name": "description", "value": "Consulting, October" },
                    { "name": "amount",      "value": "CHF 4'800.00" } ] },
      { "fields": [ { "name": "description", "value": "Travel expenses" },
                    { "name": "amount",      "value": "CHF 312.40" } ] }
    ] }
  ]
}
JSON

# 3. The generate call as it exists today: Word template + envelope, PDF back (format=DOCX for Word).
curl -sS https://api.xgenerate.io/v2/documents/generate \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@invoice.docx" \
  -F "fields=@fields.json;type=application/json" \
  -F "format=PDF" \
  -o invoice.pdf

Depuis .NET

using System.Net.Http.Json;
using System.Xml.Linq;

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

// The mapping step your integration adds: elements and attributes become fields,
// repeating elements become list rows. Names match the template's MERGEFIELD codes.
var xml = XDocument.Load("invoice.xml").Root!;
var fields = new
{
    fields = new[]
    {
        new { name = "invoice.number", value = xml.Attribute("number")!.Value },
        new { name = "invoice.date",   value = xml.Attribute("date")!.Value },
        new { name = "recipient.name", value = xml.Element("recipient")!.Element("name")!.Value }
    },
    lists = new[]
    {
        new
        {
            name = "invoice.lines",
            value = xml.Element("lines")!.Elements("line").Select(line => new
            {
                fields = new[]
                {
                    new { name = "description", value = line.Attribute("description")!.Value },
                    new { name = "amount",      value = line.Attribute("amount")!.Value }
                }
            }).ToArray()
        }
    }
};

// The generate call as it exists today: Word template + envelope over the JSON transport.
var request = new
{
    filename = "invoice.docx",
    content = Convert.ToBase64String(await File.ReadAllBytesAsync("invoice.docx")),
    format = "PDF",
    fields
};
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);

La réponse

L'appel multipart renvoie le PDF en octets bruts ; le transport JSON renvoie filename, content, format et warnings. Les avertissements nomment les emplacements d'image, de QR et d'en-tête restés sans valeur ; les champs de fusion et les régions sans données sont supprimés sans avertissement. La requête réussit dans les deux cas.

Le résultat

Première page de la facture de référence rendue : en-tête, bloc d'adresse, tableau des lignes et totaux — La facture de référence, rendue à partir d'un modèle Word avec des champs de fusion standard. Modèle, requête et PDF attendu : exemple publié

Ce que XGenerate ne fait pas

Le XML n'est pas une entrée de l'API aujourd'hui : les points de terminaison de génération prennent l'enveloppe fields en JSON, ou un corps HTML ou Markdown, et l'adaptateur XML est construit dans le cadre de votre intégration à partir de votre XML d'exemple (xgenerateio/xgenerate#364). Les feuilles de style XSLT ne sont pas exécutées. Les blocs conditionnels dépendant d'une valeur ne sont pas pris en charge ; les champs IF de Word autour d'un texte le sont.

Essayez-le sur votre propre modèle

Envoyez-nous un fichier Word que vous utilisez aujourd'hui. Nous le rendons avec vos données et vous renvoyons le PDF avec le modèle adapté, pour que votre évaluation ne dépende pas de nous.

Demander une démo