سير عمل التقرير من البداية إلى النهاية

1. أنشئ بنية التقرير

أنشئ قالب تقرير بعنوان وفترة تقرير ومخطط وجدول تفاصيل. استخدم موضع flow للمحتوى الممتد عبر الصفحات. أضف ترويسة وتذييلًا ورقم صفحة حسب الحاجة.

2. عرّف البيانات مرة واحدة

استخدم مثلًا خاصيتي month وrevenue في مصفوفة باسم monthlyRevenue. اربط المخطط بها واختر month لحقل الفئة وrevenue لحقل السلسلة. اربط جدول التفاصيل بالمصفوفة نفسها ليستخدم العرضان البيانات نفسها.

3. اختبر الحالات الحدية

اختبر مصفوفة فارغة وفئة واحدة وأسماء فئات طويلة وحقولًا مفقودة وصفوفًا كثيرة. قارن مجاميع المخطط بالجدول. لا تستخدم قيمًا سالبة للدائري أو الحلقي. إذا ازدحمت التسميات فكبّر المخطط أو قلل الفئات أو اعرض التفاصيل في الجدول.

دورة إنشاء التقرير الكاملة

تُنتج التقارير عادةً على دفعات وتستغرق وقتًا أطول من فاتورة واحدة، لذا تمر بقائمة الانتظار. تحقق أولًا من المخطط منفردًا، ثم أدرج المستند في القائمة وتابعه عبر webhook أو الاستعلام المتكرر.

# 1 - تحقق من المخطط منفردًا قبل وضعه في مستند
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": "ar",
        "element": {
          "id": "quarterly-volume",
          "type": "chart",
          "placementMode": "flow",
          "layout": { "width": 100, "widthUnit": "percent", "height": 240 },
          "content": {
            "title": "المستندات المُنتجة",
            "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": "المستندات", "color": "#e3232a" }],
            "showLegend": true,
            "showValues": true
          }
        }
      }'

# 2 - أدرج التقرير في القائمة - الاستجابة 202 مع 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": "ar",
        "webhookUrl": "https://example.com/hooks/pdfgine",
        "data": { "document": { "title": "صيانة ربع سنوية" } }
      }'

# 3 - تابعه - استعلم من هذا الطرف إذا لم تحدد webhook
curl -s https://api.pdfgine.com/api/v1/async-jobs/queue_fe86ad38402a4909b3b5a7965847924a \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

تستجيب القائمة بالحالة 202 مع statusUrl، وليس بالمستند النهائي. قدّم webhookUrl إذا فضلت تلقي إشعار بدل الاستعلام؛ تتصل بك القائمة عند جاهزية المستند وتعيد محاولة الاستدعاء الفاشل.

4. تحقق من الناتج وشاركه

بعد التحقق من الحفظ والنشر أنشئ مخرجات PDF وWord المطلوبة. افحص في العارض عدد الصفحات وملء المخططات للمساحة المتاحة. مخطط Word صورة وليس مخططًا أصليًا قابلًا للتحرير. تحقق من الانتهاء وأذونات التنزيل للمشاركة الخارجية؛ ولا تضع مفتاح API في رابط مشترك.

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

• تجيب القائمة بالحالة 202 مع statusUrl وليس بالتقرير. قراءة documentId مباشرةً من تلك الاستجابة تعطي null دائمًا.
• شهر بلا صفوف حالة فعلية. اختبر المصفوفة الفارغة قبل وصول التقرير إلى العميل بمخطط فارغ وجدول بلا ترويسة.
• قارن المخطط بجدوله. مخطط مرتبط بمصفوفة وصف إجمالي محسوب من أخرى ينتجان رقمًا خاطئًا يصعب ملاحظته في التقرير.
• لا يمكن تمثيل القيم السالبة بأمانة في مخطط دائري أو حلقي. صححها في البيانات المصدرية لا في المخطط.
• تواجه المهمة الجماعية حدين: صفحات حصتك والمستندات في الدقيقة ضمن خطتك. وزّع التنفيذ بدل تجميع استجابات 429.