Flusso completo del report
1. Crea la struttura del report
Crea un modello di report con titolo, periodo, grafico e tabella dettagliata. Usa il posizionamento flow per contenuti su più pagine. Aggiungi intestazione, piè di pagina e numero di pagina secondo necessità.
2. Definisci i dati una volta
Ad esempio usa le proprietà month e revenue in un array chiamato monthlyRevenue. Associa il grafico a quell'array, scegli month come campo categoria e revenue come campo serie. Associa la tabella dettagliata allo stesso array per usare gli stessi dati in entrambe le viste.
3. Prova i casi limite
Prova array vuoto, categoria singola, nomi lunghi, campi mancanti e molte righe. Confronta i totali del grafico con la tabella. Non usare valori negativi nei grafici a torta o ad anello. Se le etichette si affollano, ingrandisci il grafico, riduci le categorie o presenta i dettagli nella tabella.
Il ciclo completo di generazione del report
Un report viene solitamente prodotto in blocco e richiede più tempo di una singola fattura, quindi passa dalla coda. Verifica prima il grafico da solo, poi metti in coda il documento e seguilo tramite webhook o polling.
# 1 - Verifica il grafico da solo prima di inserirlo in un documento
curl -X POST https://api.pdfgine.com/api/v1/templates/chart-preview \
-H "X-PDFgine-Key: $PDFGINE_KEY" \
-H "Content-Type: application/json" \
-d '{
"width": 640,
"locale": "it",
"element": {
"id": "quarterly-volume",
"type": "chart",
"placementMode": "flow",
"layout": { "width": 100, "widthUnit": "percent", "height": 240 },
"content": {
"title": "Documenti prodotti",
"data": [
{ "quarter": "Q1", "documents": 120 },
{ "quarter": "Q2", "documents": 180 },
{ "quarter": "Q3", "documents": 240 },
{ "quarter": "Q4", "documents": 310 }
]
},
"chart": {
"type": "bar",
"labelField": "quarter",
"series": [{ "field": "documents", "label": "Documenti", "color": "#e3232a" }],
"showLegend": true,
"showValues": true
}
}
}'
# 2 - Metti il report in coda - la risposta è 202 con una statusUrl
curl -X POST https://api.pdfgine.com/api/v1/documents/render \
-H "X-PDFgine-Key: $PDFGINE_KEY" \
-H "Content-Type: application/json" \
-d '{
"templateCode": "maintenance-report",
"format": "pdf",
"locale": "it",
"webhookUrl": "https://example.com/hooks/pdfgine",
"data": { "document": { "title": "Manutenzione trimestrale" } }
}'
# 3 - Seguilo - interroga questo endpoint se non hai impostato un webhook
curl -s https://api.pdfgine.com/api/v1/async-jobs/queue_fe86ad38402a4909b3b5a7965847924a \
-H "X-PDFgine-Key: $PDFGINE_KEY"La coda risponde con 202 e una statusUrl, non con il documento finito. Fornisci webhookUrl se preferisci ricevere una notifica anziché interrogare il servizio: la coda ti chiama quando il documento è pronto e ritenta le chiamate non riuscite.
4. Verifica e condividi l'output
Dopo aver controllato salvataggio e pubblicazione, genera gli output PDF e Word richiesti. Nel visualizzatore verifica il numero di pagine e che i grafici riempiano lo spazio disponibile. Un grafico Word è un'immagine, non un grafico nativo modificabile. Per condivisioni esterne controlla scadenza e permessi di download; non inserire mai una chiave API in un link condiviso.
Grafici e report →Gli errori più comuni
- La coda risponde 202 con statusUrl, non con il report. Leggere documentId direttamente da quella risposta restituisce sempre null.
- Un mese senza righe è un caso reale. Prova l'array vuoto prima che un cliente riceva un report con grafico vuoto e tabella senza intestazione.
- Confronta il grafico con la sua tabella. Un grafico associato a un array e un totale calcolato da un altro producono un errore numerico difficile da notare.
- I valori negativi in un grafico a torta o ad anello non possono essere rappresentati fedelmente. Correggili nei dati di origine, non nel grafico.
- Un'elaborazione in blocco incontra due limiti: le pagine della quota e i documenti al minuto del piano. Distribuisci l'esecuzione anziché accumulare risposte 429.