Flujo completo de un informe

1. Crea la estructura del informe

Crea una plantilla de informe con título, período, gráfico y tabla de detalle. Usa posicionamiento de flujo para contenido que pueda ocupar varias páginas. Añade encabezado, pie y número de página según necesites.

2. Define los datos una vez

Por ejemplo, usa propiedades month y revenue en un array llamado monthlyRevenue. Vincula el gráfico al array, selecciona month como categoría y revenue como serie. Vincula la tabla de detalle al mismo array para que ambas vistas usen los mismos datos.

3. Prueba los casos extremos

Prueba un array vacío, una categoría, nombres largos, campos ausentes y muchas filas. Compara los totales del gráfico con la tabla. No uses negativos en gráficos circulares o de anillo. Si las etiquetas se amontonan, amplía el gráfico, reduce categorías o muestra los detalles en la tabla.

El proceso completo de un informe

Un informe suele generarse por lotes y tarda más que una factura individual, por lo que pasa por la cola. Comprueba primero el gráfico por separado y, después, encola el documento y sigue su estado mediante un webhook o consultas periódicas.

# 1 - Comprobar el gráfico por separado antes de incluirlo en 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": "es",
        "element": {
          "id": "quarterly-volume",
          "type": "chart",
          "placementMode": "flow",
          "layout": { "width": 100, "widthUnit": "percent", "height": 240 },
          "content": {
            "title": "Documentos generados",
            "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": "Documentos", "color": "#e3232a" }],
            "showLegend": true,
            "showValues": true
          }
        }
      }'

# 2 - Encolar el informe - la respuesta es 202 con un 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": "es",
        "webhookUrl": "https://example.com/hooks/pdfgine",
        "data": { "document": { "title": "Mantenimiento trimestral" } }
      }'

# 3 - Seguir su estado - consultar este endpoint si no se configuró un webhook
curl -s https://api.pdfgine.com/api/v1/async-jobs/queue_fe86ad38402a4909b3b5a7965847924a \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

La cola responde con un 202 y un statusUrl, no con el documento terminado. Indica webhookUrl si prefieres recibir una notificación en lugar de consultar; la cola te avisará cuando el documento esté listo y reintentará las llamadas fallidas.

4. Verifica y comparte el resultado

Tras comprobar el guardado y la publicación, genera PDF y Word. En el visor, revisa las páginas y que los gráficos ocupen el espacio disponible. Un gráfico Word es una imagen, no un gráfico nativo editable. Comprueba la caducidad y los permisos de descarga al compartir fuera; nunca incluyas una clave API en un enlace compartido.

Los errores más habituales

• La cola responde 202 con statusUrl, no con el informe. Leer documentId directamente de esa respuesta siempre devuelve null.
• Un mes sin filas es un caso real. Prueba el array vacío antes de que un cliente reciba un informe con un gráfico en blanco y una tabla sin encabezados.
• Compara el gráfico con su tabla. Un gráfico vinculado a un array y una fila total calculada sobre otro producen uno de los errores numéricos más silenciosos de un informe.
• Los valores negativos no pueden representarse honestamente en un gráfico circular o de anillo. Corrígelos en los datos de origen, no en el gráfico.
• Un trabajo masivo encuentra dos límites: las páginas de tu cuota y los documentos por minuto de tu plan. Distribuye la ejecución en lugar de acumular errores 429.