Ürün ve API rehberi

Kuyruklu üretim

Ne zaman kuyruğa alınır

Doğrudan uç, belge hazır olduğunda yanıt verir; çağıran bekleyebildiği sürece en basit yol budur. Belge uzunsa, aynı anda çok sayıda üretiyorsanız ya da çağıran açık kalmaması gereken bir web isteğiyse kuyruğa alın: yanıt hemen bir queueId ile döner, iş arkada devam eder.

Uzun belgeler ve toplu işler için isteği kuyruğa alın. Cevap hemen döner; işin durumunu statusUrl adresinden izlersiniz.

Kuyruk sırası

Kuyruk önceliği plandan gelir ve ayrı bir kuyruk değildir: iş, önceliği kadar erken varmış sayılır. Bunun iki sonucu var — yüksek öncelikli iş aynı anda gelen işin önüne geçer, ve bekleyen iş sonsuza kadar beklemez. Bekleme süresinin üst sınırı hesaplanabilir bir sayıdır; bugünkü değerlerle Ücretsiz bir iş en fazla 54 dakika, Max işi hiç beklemez.

İstek 
curl -X POST https://api.pdfgine.com/api/v1/documents/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateCode": "invoice", "format": "pdf", "data": { } }'
Cevap 
{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "queued",
  "statusUrl": "/api/v1/async-jobs/queue_ea464b42...",
  "documentId": null,
  "createdAt": "2026-08-28T13:23:45+00:00"
}
Kuyruklu üretim 
curl https://api.pdfgine.com/api/v1/async-jobs/queue_ea464b42... \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

İsteğe webhookUrl eklerseniz iş bittiğinde imzalı bir bildirim gönderilir; sürekli sorgulamanız gerekmez.

Biten bir iş neye benzer

İşi statusUrl adresinden okuyun. Sürerken status queued ya da running olur; bitince documentId ve result dolar.

Cevap 
{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "succeeded",
  "attemptCount": 1,
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "result": {
    "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
    "pageCount": 12
  },
  "failureCode": null,
  "createdAt": "2026-08-28T13:23:45+00:00",
  "completedAt": "2026-08-28T13:23:52+00:00"
}

Düşen bir iş status failed ve sebebini söyleyen bir failureCode ile döner; aynı kodlar hatalar sayfasında listelenir.

Sık takılınan yerler

  • Kuyruk, queueId taşıyan ve belge taşımayan bir 202 döner. documentId iş bitene kadar null kalır; hemen okuyup null'ı başarısızlık saymak buradaki en sık hatadır.
  • Saniyede bir yoklamak hız sınırınızı harcar. Birkaç saniye arayla yoklayın ya da webhookUrl gönderip hiç yoklamayın.
  • status failed bekleyen değil bitmiş bir iştir. failureCode'u okuyup girdiyi düzeltin; iş kendiliğinden yeniden başlamaz.
  • Webhook bildirimi imzalıdır. Güvenmeden önce imzayı doğrulayın — webhook sayfası nasıl yapılacağını gösteriyor — ve 2xx dönün, yoksa bildirim yeniden gönderilir.
  • Kuyruğa alınan bir belge doğrudan üretilenle aynı sayfayı harcar. Kuyruk işin ne zaman yapıldığını değiştirir, neye mal olduğunu değil.