Produkt- und API-Leitfaden

Dokument erstellen

Was dieser Endpunkt macht

Ein Aufruf verwandelt Vorlage und Daten in eine fertige Datei. Das Dokument wird während der Wartezeit erstellt; die Antwort enthält eine Downloadadresse. Statusabfragen sind nicht nötig. Für lange Dokumente oder Stapelverarbeitung erledigt der Warteschlangenendpunkt dieselbe Arbeit im Hintergrund.

Senden Sie Vorlagencode und Daten und erhalten Sie das Dokument zurück. Die Download-URL der Antwort ist relativ zur Basisadresse und wird mit demselben API-Schlüssel abgerufen.

Anfrage 
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": "de",
        "purpose": "production",
        "data": {
          "document": { "title": "INV-2026-001" }
        }
      }'

Das Feld format akzeptiert "pdf" oder "docx". Numerische Werte funktionieren für bestehende Clients weiterhin: 1 ist PDF, 2 ist DOCX. Antworten liefern das Format als Zahl.

purpose production verbraucht Kontingent. Senden Sie beim Ausprobieren einer Vorlage editor-test: Diese Ausgabe verwendet den unveröffentlichten Entwurf und verbraucht kein Kontingent.

Der vollständige Ablauf

Dies ist die Antwort auf den obigen Aufruf und der Aufruf zum Abruf der Datei. Status 202 bedeutet: Die Anfrage wurde angenommen und das Dokument ist fertig.

Antwort 
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 
curl https://api.pdfgine.com/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -o invoice.pdf

Häufige Fehler

  • Die Erstellung antwortet mit 202, nicht 200. Ein Client, der jeden anderen Status als 200 als Fehler behandelt, meldet Erfolg als Fehler.
  • purpose entscheidet zweierlei: production verwendet die veröffentlichte Version und verbraucht Kontingent, editor-test den unveröffentlichten Entwurf ohne Verbrauch. Tests mit production sind die teuerste Art, eine Vorlage auszuprobieren.
  • 422 ist kein Serverfehler. Der Inhalt listet unter errors alle von der Vorlage benötigten Felder auf. Korrigieren Sie die gesendeten Daten, statt die Anfrage nur zu wiederholen.
  • 402 bedeutet, dass das monatliche Seitenkontingent verbraucht ist. Der Header X-PDFgine-Quota-Remaining informiert Sie schon vorher.
  • downloadUrl ist relativ zur API-Adresse. Als absolute URL gespeichert funktioniert sie nach einer Adressänderung nicht mehr. Speichern Sie documentId und bilden Sie die Adresse daraus.
Antwort →