Générer un document

Rôle de ce point de terminaison

Un appel transforme un modèle et vos données en fichier terminé. Le document est produit pendant l’attente et la réponse contient une adresse de téléchargement ; aucune interrogation d’état n’est nécessaire. Pour les documents longs ou les lots, le point de terminaison en file réalise la même opération en arrière-plan.

Envoyez le code du modèle et vos données, puis recevez le document. L’URL de téléchargement de la réponse est relative à l’adresse de base et s’utilise avec la même clé API.

curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "locale": "fr",
        "purpose": "production",
        "data": {
          "document": { "title": "INV-2026-001" }
        }
      }'

Le champ format accepte "pdf" ou "docx". Les valeurs numériques restent compatibles avec les clients existants : 1 correspond à PDF, 2 à DOCX. Les réponses renvoient le format sous forme de nombre.

Le mode production consomme du quota. Lorsque vous testez un modèle, envoyez editor-test : cette sortie ne consomme aucun quota et utilise la révision du brouillon non publié.

L’aller-retour complet

Voici la réponse à l’appel ci-dessus et l’appel qui récupère le fichier. Le statut est 202 : la requête a été acceptée et le document est prêt.

HTTP/1.1 202 Accepted
X-PDFgine-Pages: 1
X-PDFgine-Quota-Remaining: 4999

{
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "format": "pdf",
  "templateCode": "invoice",
  "templateVersion": 1,
  "templateVersionSource": "published",
  "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
  "pageCount": 1,
  "quotaRemaining": 4999,
  "meteringBasis": "pdf-equivalent"
}

curl https://api.pdfgine.com/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -o invoice.pdf

Les problèmes les plus courants

• Le rendu répond 202, pas 200. Un client qui considère toute réponse autre que 200 comme un échec signale une réussite comme erreur.
• purpose décide de deux choses à la fois : production utilise la version publiée et consomme du quota ; editor-test utilise le brouillon non publié et n’en consomme pas. Tester avec production est la manière la plus coûteuse d’essayer un modèle.
• 422 n’est pas une panne du serveur. Le corps liste dans errors tous les champs attendus par le modèle ; la correction concerne les données envoyées, pas une nouvelle tentative.
• 402 signifie que le quota mensuel de pages est épuisé. L’en-tête X-PDFgine-Quota-Remaining vous prévient avant d’y arriver.
• downloadUrl est relative à l’adresse de l’API. La stocker comme URL absolue ne fonctionnera plus le jour où l’adresse changera ; stockez documentId et construisez l’adresse.