دليل المنتج وAPI

الإنشاء عبر قائمة الانتظار

متى تستخدم قائمة الانتظار

يستجيب الطرف المباشر عند جاهزية المستند، وهو الأبسط ما دام المستدعي يستطيع الانتظار. استخدم القائمة عندما يطول المستند أو تنتج الكثير دفعة واحدة أو يكون المستدعي طلب ويب يجب ألا يبقى مفتوحًا: تعود الاستجابة فورًا مع queueId ويستمر العمل في الخلفية.

ضع طلب المستندات الطويلة والمهام الجماعية في قائمة الانتظار. تعود الاستجابة فورًا وتتابع المهمة عبر statusUrl الخاص بها.

ترتيب قائمة الانتظار

تحدد خطتك أولوية قائمة الانتظار، ولا تعني قائمة منفصلة: تُعامل المهمة كما لو وصلت أبكر بمقدار يتناسب مع أولويتها. ولهذا نتيجتان: تتقدم المهمة الأعلى أولوية على مهمة أُدرجت في اللحظة نفسها، ولا تنتظر أي مهمة إلى الأبد. يمكنك حساب أقصى مدة انتظار؛ بالقيم الحالية تنتظر مهمة Free مدة أقصاها 54 دقيقة، ولا تنتظر مهمة Max إطلاقًا.

الطلب 
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": { } }'
الاستجابة 
{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "queued",
  "statusUrl": "/api/v1/async-jobs/queue_ea464b42...",
  "documentId": null,
  "createdAt": "2026-08-28T13:23:45+00:00"
}
الإنشاء عبر قائمة الانتظار 
curl https://api.pdfgine.com/api/v1/async-jobs/queue_ea464b42... \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

أضف webhookUrl إلى الطلب لتتلقى إشعارًا موقّعًا عند انتهاء المهمة، دون الحاجة إلى الاستعلام المتكرر.

شكل المهمة المكتملة

اقرأ المهمة عبر statusUrl. أثناء التنفيذ تكون status هي queued أو running، وعند الانتهاء تُملأ documentId وresult.

الاستجابة 
{
  "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"
}

تجيب المهمة الفاشلة بـ status قيمتها failed وfailureCode يوضح السبب؛ وتُسرد الرموز نفسها في صفحة الأخطاء.

الأخطاء الشائعة

  • تجيب القائمة بالحالة 202 مع queueId ودون مستند. تبقى documentId بالقيمة null حتى تنتهي المهمة؛ وقراءتها فورًا واعتبار null فشلًا هو الخطأ الأكثر شيوعًا هنا.
  • الاستعلام كل ثانية يهدر حد المعدل. استعلم كل بضع ثوانٍ أو أرسل webhookUrl واستغنِ عن الاستعلام تمامًا.
  • تعني status بالقيمة failed مهمة منتهية لا معلقة. اقرأ failureCode وصحح المدخلات؛ لن تبدأ المهمة مجددًا من تلقاء نفسها.
  • إشعار webhook موقّع. تحقق من توقيعه قبل الوثوق به، كما توضح صفحة webhook، وأجب بالحالة 2xx وإلا أُرسل مجددًا.
  • يستهلك المستند في القائمة الصفحات نفسها التي يستهلكها المستند المباشر. تغير القائمة وقت العمل لا تكلفته.