API إنشاء PDF على دفعات للصفوف والمهام
أنشئ عددًا كبيرًا من ملفات PDF عبر JSON Render أو Template Render بما يناسب قوائم الانتظار، بينما يدير نظامك التقسيم وإعادة المحاولة والحتمية والتخزين.
/api/v1/template-render عرض عدد كبير من ملفات PDF من صف أو مهمة مجدولة عبر تقسيم العمل إلى طلبات آمنة، وإرسال كل مستند أو عنصر بيانات قالب إلى gPdf، ثم تخزين ملف PDF العائد أو تسليمه داخل نظامك.
متى تستخدم هذه API
- تحتاج إلى إنشاء فواتير أو كشوف أو ملصقات أو تقارير ضمن دفعة مجدولة أو مبنية على الأحداث.
- لديك قالب مستقر ويمكنك إرسال عدة عناصر بيانات ضمن حدود المسار.
- تحتاج إلى عرض مناسب للصفوف دون تشغيل عمال متصفح.
- يمكنك إدارة إزالة التكرار وإعادة المحاولة وتخزين المخرجات.
ما الذي لا تستبدله
- تحتاج إلى أن يكون gPdf مجدول الدُفعات أو الصف أو نظام التخزين أو دفتر الحتمية لديك.
- تحتاج إلى ترويسات حدود معدلات منشورة أو عقد idempotency-key من جهة الخادم.
- تحتاج إلى طلب واحد غير محدود يعرض كل مستند في حملة كاملة.
أي مسار API يجب استدعاؤه
/api/v1/template-render
Template Render هو المسار الافتراضي لسير العمل هذا.
/api/v1/pdf/render
استخدمه عندما يحتاج سير العمل إلى مسار API مرتبط، أو عقد قالب، أو استعلام capabilities.
طلب مختصر
POST /api/v1/template-render - دفعة صغيرة تتضمن عنصرين من بيانات الفواتير.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
ما يتولاه gPdf
- عرض PDF لكل طلب JSON Render أو Template Render.
- مصفوفات بيانات Template Render ضمن الحدود العامة الموثقة.
- استجابات عرض سريعة وعديمة الحالة تناسب عمال الصفوف.
- سلوك مشترك لمعرّف الطلب وغلاف الأخطاء.
ما يبقى ضمن مسؤولية نظامك
- تصميم الصف، والتقسيم، والتوازي، وإعادة المحاولة، وإزالة التكرار، وتخزين المخرجات.
- اختيار كائنات الأعمال واختيار القالب وسير التسليم.
- سياسة التراجع، والتنبيهات، والتعافي بعد الفشل الجزئي.
قائمة فحص الإنتاج
- قسّم العمل بحيث يبقى كل طلب ضمن حدود العناصر وحجم البيانات الموثقة.
- أنشئ X-Request-Id واحدًا لكل طلب واربطه بمعرّف المهمة لديك.
- أعد المحاولة فقط عند فشل الشبكة أو أخطاء 5xx، مع تراجع أسي محدود.
- لا تعِد محاولة أخطاء تحقق 4xx من دون تغيير البيانات المرسلة.
- خزّن ملفات PDF الناتجة أو بيانات المصدر وفق سياسة الاحتفاظ لديك.
حدود الادعاءات
- gPdf هو API العرض، وليس طبقة الصف أو التخزين.
- لا تنشر الواجهة العامة اليوم ترويسات حدود معدلات أو مفاتيح حتمية من جهة الخادم.
- يجب أن يجعل نظامك إعادة المحاولة آمنة.
الإنشاء على دفعات هو نمط تكامل
إنشاء PDF على دفعات ليس مسارًا منفصلًا. إنه الطريقة التي يستخدم بها صفّك واجهات العرض العامة. أبق المهام صغيرة، قابلة للمراقبة، وآمنة عند إعادة المحاولة.
بالنسبة إلى التخطيطات المتكررة، يمنح Template Render عادةً أوضح عقد. أما المستندات البرمجية ذات التخطيطات المخصصة، فيظل JSON Render متاحًا لها.
الأسئلة الشائعة
- هل يوفر gPdf واجهة API خاصة بمهام الدُفعات؟
- لا توجد جدولة دُفعات منفصلة مكشوفة. استخدم JSON Render أو Template Render من نظام الصفوف أو العمال الخاص بك.
- هل يستطيع Template Render قبول عدة عناصر بيانات؟
- نعم، ضمن حدود مسار API العامة. قسّم المهام الأكبر على عدة طلبات.
- من المسؤول عن إعادة المحاولة؟
- نظامك مسؤول عن إعادة المحاولة، والتراجع، وإزالة التكرار، والحتمية. يعيد gPdf معرّفات الطلب لتسهيل التتبع.
- هل يمكنني عرض تخطيطات كثيرة ومختلفة في طلب واحد؟
- استخدم طلبات منفصلة عندما تختلف التخطيطات أو معرّفات القوالب. أبق كل طلب بسيطًا وقابلًا للتتبع.