Guida al prodotto e alle API
Risposta
Cosa viene restituito
Ogni generazione riuscita risponde con lo stesso oggetto. Due campi meritano di essere conservati: documentId identifica il file finché viene conservato e pageCount determina l'addebito mensile.
Risposta
{
"documentId": "doc_5bd26de32c324a4bb8cffad2c80edd01",
"jobId": "job_00b96f006b034258b00b650d724d0207",
"fileName": "invoice-doc_5bd26de32c324a4bb8cffad2c80edd01.pdf",
"format": "pdf",
"templateCode": "invoice",
"templateVersion": 5,
"templateVersionSource": "published",
"downloadUrl": "/api/v1/documents/doc_5bd2.../download/pdf",
"previewUrl": null,
"pageCount": 1,
"quotaRemaining": 4999,
"meteringBasis": "pdf-equivalent",
"createdAt": "2026-08-28T13:23:32+00:00"
}Una generazione resta privata e il download richiede la tua chiave API. Usa l'endpoint di anteprima solo quando vuoi intenzionalmente un link cliente a scadenza.
Intestazioni della risposta
Ogni risposta di generazione ripete i valori di consumo nelle intestazioni, così puoi monitorare la quota senza una seconda chiamata.
X-PDFgine-Pages | Numero di pagine di questo documento |
|---|---|
X-PDFgine-Job | Identificatore del processo di generazione |
X-PDFgine-Quota-Remaining | Pagine rimaste dopo l'operazione |
X-PDFgine-Metering-Basis | Unità di misurazione |
Campo per campo
Per pdf, docx e html vengono restituiti gli stessi campi; cambia solo fileName.
| Campo | Significato |
|---|---|
documentId | L'identificatore del file prodotto. Download, stato e condivisione lo usano tutti, quindi è il valore da memorizzare. |
downloadUrl | Relativo all'indirizzo API e recuperato con la stessa chiave. È un percorso, non un link pubblico. |
templateVersion | La versione del modello che ha prodotto il file. Conservala per spiegare una ristampa anche mesi dopo. |
templateVersionSource | published per una generazione di produzione, draft quando purpose è editor-test. |
pageCount | Quante pagine sono state prodotte: è ciò che viene conteggiato nella quota. |
quotaRemaining | Pagine rimaste nel mese corrente al momento della risposta. |
meteringBasis | Cosa significa una pagina ai fini della fatturazione. pdf-equivalent conta un output docx o html con lo stesso numero di pagine che avrebbe il PDF. |
previewUrl | Compilato solo quando il documento è stato condiviso; altrimenti null. |
Gli errori più comuni
- downloadUrl è un percorso. Incollarlo in un browser senza l'indirizzo API e la chiave restituisce 404 o 401, non il file.
- Memorizza documentId, non l'intera risposta. La conservazione elimina i file dopo il periodo previsto dal piano e un URL salvato non punta più a nulla.
- quotaRemaining è un'istantanea di quel momento, non un contatore in tempo reale. Due chiamate contemporanee possono leggere lo stesso numero.
- pageCount è l'unità di fatturazione, non il numero di file. Un documento di dieci pagine costa dieci pagine, sia in pdf sia in docx.
- previewUrl uguale a null non significa che la condivisione sia fallita, ma che questa generazione non è stata condivisa. La condivisione è una chiamata separata.