Uçtan uca rapor hazırlama

1. Rapor iskeletini oluşturun

Bir rapor şablonu oluşturun; başlık, dönem bilgisi, grafik ve detay tablosu ekleyin. Birden fazla sayfaya uzayacak içerik için akış yerleşimi kullanın. Üstbilgi, altbilgi ve sayfa numarasını raporun ihtiyacına göre ekleyin.

2. Veriyi bir kez tanımlayın

Örneğin monthlyRevenue adlı nesne dizisinde month ve revenue alanlarını kullanın. Grafiği bu diziye bağlayıp kategori alanını month, seri alanını revenue seçin. Detay tablosunu aynı diziye bağlayarak iki görünümün aynı veriyi kullandığından emin olun.

3. Sınır durumlarını deneyin

Boş dizi, tek kategori, uzun kategori adları, eksik alanlar ve çok sayıda satırla deneyin. Grafik toplamlarını tabloyla karşılaştırın. Pasta ve halka için negatif değer kullanmayın. Etiketler üst üste biniyorsa grafiği büyütün, kategorileri azaltın veya ayrıntıları tabloda sunun.

Raporun baştan sona koşusu

Rapor genellikle toplu üretiliyor ve tek bir faturadan uzun sürüyor, o yüzden kuyruktan geçiyor. Önce grafiği tek başına doğrulayın, sonra belgeyi kuyruğa verip izleyin — ya webhook ile ya da yoklayarak.

# 1 - Grafiği belgeye koymadan önce tek başına doğrula
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": "tr",
        "element": {
          "id": "quarterly-volume",
          "type": "chart",
          "placementMode": "flow",
          "layout": { "width": 100, "widthUnit": "percent", "height": 240 },
          "content": {
            "title": "Üretilen belgeler",
            "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": "Belgeler", "color": "#e3232a" }],
            "showLegend": true,
            "showValues": true
          }
        }
      }'

# 2 - Raporu kuyruğa ver - yanıt 202 ve statusUrl döndürür
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": "tr",
        "webhookUrl": "https://example.com/hooks/pdfgine",
        "data": { "document": { "title": "Çeyreklik bakım" } }
      }'

# 3 - Durumu izle - webhook kurmadıysan bu ucu yokla
curl -s https://api.pdfgine.com/api/v1/async-jobs/queue_fe86ad38402a4909b3b5a7965847924a \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

Kuyruk bitmiş belgeyi değil, 202 ve bir statusUrl döndürür. Sormak yerine size söylenmesini istiyorsanız webhookUrl verin; kuyruk belge hazır olunca sizi arar ve düşen bir çağrıyı yeniden dener.

4. Çıktıyı doğrulayın ve paylaşın

Kaydetme ve yayın kontrolünden sonra gerekli PDF ve Word çıktılarını oluşturun. Viewer’da sayfa sayısını ve grafiklerin kullanılabilir alanı doldurduğunu kontrol edin. Word’de grafik bir görseldir; yerel düzenlenebilir grafik değildir. Dış paylaşımda süre ve indirme izinlerini kontrol edin; API anahtarını paylaşım bağlantısına eklemeyin.

Sık takılınan yerler

• Kuyruk raporu değil, statusUrl taşıyan bir 202 döner. documentId'yi o yanıttan okumak her seferinde null verir.
• Satırı olmayan bir ay gerçek bir durumdur. Boş diziyi, rapor boş grafik ve başlıksız tabloyla müşteriye gitmeden önce deneyin.
• Grafiği tablosuyla karşılaştırın. Bir diziye bağlı grafik ile başka bir diziden hesaplanan toplam satırı, rapordaki en sessiz yanlış sayıdır.
• Pasta ve halka grafikte negatif değer dürüstçe çizilemez. Onları grafikte değil kaynak veride düzeltin.
• Toplu koşu iki tavana çarpar: kotanızdaki sayfalar ve planınızdaki dakika başına belge. 429 toplamak yerine koşuyu yayın.