Guia do produto e da API

Fluxo completo de relatório

1. Crie a estrutura do relatório

Crie um modelo de relatório com título, período, gráfico e tabela de detalhes. Use fluxo para conteúdo que pode ocupar várias páginas. Adicione cabeçalho, rodapé e número de página conforme necessário.

2. Defina os dados uma vez

Por exemplo, use propriedades month e revenue em um array chamado monthlyRevenue. Vincule o gráfico ao array, escolha month como categoria e revenue como série. Vincule a tabela de detalhes ao mesmo array para ambas usarem os mesmos dados.

3. Teste os casos extremos

Teste um array vazio, uma categoria, nomes longos, campos ausentes e muitas linhas. Compare os totais do gráfico com a tabela. Não use negativos em pizza ou rosca. Se as etiquetas ficarem sobrepostas, aumente o gráfico, reduza categorias ou mostre os detalhes na tabela.

O processo completo do relatório

Um relatório geralmente é produzido em lote e leva mais tempo que uma única fatura, por isso passa pela fila. Verifique primeiro o gráfico isoladamente, depois coloque o documento na fila e acompanhe-o por webhook ou consultas periódicas.

cURL 
# 1 - Verificar o gráfico isoladamente antes de colocá-lo em um 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": "pt",
        "element": {
          "id": "quarterly-volume",
          "type": "chart",
          "placementMode": "flow",
          "layout": { "width": 100, "widthUnit": "percent", "height": 240 },
          "content": {
            "title": "Documentos produzidos",
            "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 - Colocar o relatório na fila - a resposta é 202 com uma 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": "pt",
        "webhookUrl": "https://example.com/hooks/pdfgine",
        "data": { "document": { "title": "Manutenção trimestral" } }
      }'

# 3 - Acompanhar - consultar este endpoint se nenhum webhook foi definido
curl -s https://api.pdfgine.com/api/v1/async-jobs/queue_fe86ad38402a4909b3b5a7965847924a \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

A fila responde com 202 e uma statusUrl, não com o documento pronto. Informe webhookUrl se preferir ser avisado em vez de consultar; a fila fará uma chamada quando o documento estiver pronto e repetirá chamadas que falharem.

4. Verifique e compartilhe a saída

Após conferir salvamento e publicação, gere PDF e Word. No Visualizador, verifique as páginas e o espaço dos gráficos. Um gráfico Word é imagem, não gráfico nativo editável. Confira expiração e permissões de download ao compartilhar externamente; nunca coloque uma chave de API no link compartilhado.

Gráficos e relatórios →

Os problemas mais comuns

  • A fila responde 202 com statusUrl, não com o relatório. Ler documentId diretamente dessa resposta sempre retorna null.
  • Um mês sem linhas é um caso real. Teste o array vazio antes que o cliente receba um relatório com gráfico em branco e tabela sem cabeçalho.
  • Compare o gráfico com sua tabela. Um gráfico ligado a um array e uma linha de total calculada de outro geram um dos erros numéricos mais silenciosos de um relatório.
  • Valores negativos em um gráfico de pizza ou rosca não podem ser representados de forma honesta. Corrija-os nos dados de origem, não no gráfico.
  • Uma execução em lote encontra dois limites: as páginas da cota e os documentos por minuto do plano. Distribua a execução em vez de acumular erros 429.