Genera un documento

Cosa fa questo endpoint

Una chiamata trasforma un modello e i tuoi dati in un file finito. Il documento viene prodotto mentre attendi e la risposta contiene un indirizzo di download, senza polling. Per documenti lunghi o processi in blocco, l'endpoint in coda svolge lo stesso lavoro in background.

Invia il codice del modello e i dati e ricevi il documento. L'URL di download nella risposta è relativo all'indirizzo di base e si recupera con la stessa chiave 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": "it",
        "purpose": "production",
        "data": {
          "document": { "title": "INV-2026-001" }
        }
      }'

Il campo format accetta "pdf" o "docx". I valori numerici restano validi per i client esistenti: 1 è PDF, 2 è DOCX. Le risposte restituiscono il formato come numero.

purpose production consuma quota. Quando provi un modello, invia editor-test: l'output non consuma quota e usa la revisione della bozza non pubblicata.

L'intero ciclo di richiesta e risposta

Questa è la risposta alla chiamata precedente e la chiamata che recupera il file. Lo stato è 202: la richiesta è stata accettata e il documento è pronto.

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

Gli errori più comuni

• La generazione risponde 202, non 200. Un client che considera errore qualsiasi stato diverso da 200 segnala un successo come errore.
• purpose decide due cose insieme: production usa la versione pubblicata e consuma quota, editor-test usa la bozza non pubblicata senza consumarla. Provare un modello con production è il modo più costoso.
• 422 non è un guasto del server. Il corpo elenca sotto errors tutti i campi richiesti dal modello: la soluzione è correggere i dati inviati, non riprovare.
• 402 indica che la quota mensile di pagine è esaurita. L'intestazione X-PDFgine-Quota-Remaining ti avvisa prima di arrivarci.
• downloadUrl è relativo all'indirizzo API. Memorizzarlo come URL assoluto lo rende inutilizzabile quando cambia l'indirizzo: salva documentId e costruisci l'indirizzo.