سرد القوالب

ما هو القالب

القالب تصميم مستند محفوظ تحت رمز تختاره. له حالتان في الوقت نفسه: مسودة تواصل تعديلها وإصدار منشور تستخدمه عمليات إنشاء الإنتاج. لا يعني الحفظ النشر، فلا يصل تغيير غير مكتمل إلى عملائك.

يعيد قوالب مساحة عملك مع أرقام إصداراتها المنشورة. تستخدم رمز القالب عند الإنشاء.

curl https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

[
  {
    "templateId": "tpl_eca4c9985ad74913902f0469469936a1",
    "code": "invoice",
    "name": "فاتورة شركة",
    "version": 5,
    "publishedVersion": 1,
    "publishedAt": "2026-08-23T08:23:21+00:00"
  }
]

تنسيق رقم الصفحة

محتوى عنصر رقم الصفحة تنسيق: تصبح {{ page }} الصفحة الحالية و{{ pages }} العدد الكلي. اكتب «{{ page }} / {{ pages }}» ليطبع المستند «3 / 12»، بعدادات صفحات في PDF ورموز حقول PAGE/NUMPAGES في Word، فتتحدث تلقائيًا عند إضافة صفحات. إذا خلا المحتوى من عناصر نائبة يُتجاهل ويُطبع رقم الصفحة وحده.

حفظ إصدار

يحمل الحفظ الإصدار الذي تعتقد أنك تعدله. إذا حفظ شخص آخر في هذه الأثناء، تكون الاستجابة 409 وتحدد الإصدار الحالي، فلا يُستبدل شيء بصمت.

curl -X POST https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "code": "invoice",
        "name": "فاتورة شركة",
        "saveMode": "manual",
        "expectedVersion": 5,
        "changeReason": "نُقل الشعار إلى الهامش الأيمن.",
        "definition": {
          "page": { "size": "A4", "orientation": "portrait" },
          "elements": [
            { "type": "text", "text": "فاتورة شركة", "fontSize": 24 }
          ]
        }
      }'

HTTP/1.1 409 Conflict

{
  "type": "https://pdfgine.dev/problems/template-conflict",
  "templateCode": "invoice",
  "currentVersion": 6,
  "currentDraftRevision": 0
}

expectedVersion اختيارية لكن يُنصح بها؛ دونها تسود الكتابة الأخيرة ويختفي التغيير السابق دون أثر.

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

• ليست 409 خطأ يُعالج بإعادة المحاولة عشوائيًا. اقرأ currentVersion وخذ التعريف الأحدث وطبّق تغييرك عليه، ثم احفظ مجددًا.
• الحفظ لا يعني النشر. يستمر إنشاء الإنتاج في استخدام آخر إصدار منشور حتى تنشر المسودة.
• يعيد السرد 200 قالب كحد أقصى. إذا وُجد المزيد تحمل الاستجابة ترويسة Link مع rel="next"؛ اتبعها ولا تفترض أن الصفحة الأولى هي المكتبة كلها.
• تتطلب القراءة templates:read والحفظ templates:write. يجيب مفتاح القراءة فقط بالحالة 403 عند الحفظ، وليس 401.
• تعثر جميع الاستدعاءات الأخرى على القالب عبر رمزه. يمكنك تغيير الاسم بحرية؛ أما تغيير الرمز فيعني قالبًا جديدًا.