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

المسودات والنشر والإصدارات

الحفظ لا يعني النشر

يحدّث الحفظ مسودة القالب التي تعمل عليها. ويختار النشر إصدارًا للإنتاج. قد يكون للقالب إصدار منشور بينما تعمل على مسودة أحدث؛ فلا تفترض أن تغييرات المسودة منشورة بالفعل.

قبل النشر

عاين ببيانات نموذجية وبيانات طويلة واقعية، وافحص تنسيقات الإخراج المطلوبة. قارن الإصدار النشط والمنشور في السجل. انشر عندما يجهز المحتوى الذي تريد استخدامه في الإنتاج.

الاستعادة من السجل

تحفظ استعادة إصدار سابق محتواه كإصدار نشط جديد ولا تمحو السجل القديم. افحص المحتوى مجددًا بعد الاستعادة. انشر بشكل منفصل إذا أردت استبدال الإصدار المنشور أيضًا.

قراءة إصدار واستعادته ونشره

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

cURL 
# قائمة الإصدارات - الأحدث أولًا
curl -s https://api.pdfgine.com/api/v1/templates/invoice/history \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# تعريف إصدار واحد
curl -s https://api.pdfgine.com/api/v1/templates/invoice/history/3 \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# ارجع إلى ذلك الإصدار - يُكتب كإصدار جديد ويُحتفظ بالقديم
curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/history/3/restore \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# انشر المسودة
curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/publish \
  -H "X-PDFgine-Key: $PDFGINE_KEY"
HTTP 409 
{
  "type": "https://pdfgine.dev/problems/template-conflict",
  "title": "تعارض في القالب",
  "status": 409,
  "detail": "عُدّل القالب بواسطة عملية أخرى. حمّل الإصدار الحالي وحاول مجددًا.",
  "templateCode": "invoice",
  "currentVersion": 19,
  "currentDraftRevision": 0
}

تُرفض الكتابة التي تحمل expectedVersion قديمة بدلًا من دمجها. يحدد محتوى الاستجابة 409 القالب وإصداره الحالي ومراجعة المسودة؛ اقرأ التعريف الحالي وأعد تطبيق تغييرك ثم اكتب مجددًا.

التعارضات ورموز الاتصال

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

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

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

  • الحفظ لا يعني النشر. قد تكون المسودة مكتملة منذ أيام بينما يستمر الإنتاج بطباعة آخر إصدار منشور.
  • لا تحذف الاستعادة شيئًا. تكتب التعريف القديم كإصدار جديد، فيبقى السجل ويستمر رقم الإصدار بالارتفاع.
  • يُرفض طلب 409 المتكرر مع expectedVersion نفسها مجددًا. اقرأ الإصدار الحالي وطبّق تغييرك عليه ثم اكتب.
  • يستخدم الإنشاء مع purpose بالقيمة editor-test المسودة، وتستخدم production الإصدار المنشور. قد يأتي ناتجان يبدوان متطابقين من تصميمين مختلفين.
  • طرف السجل مقسم إلى صفحات. دون limit تحصل على أحدث صفحة وترويسة Link؛ واعتبارها السجل كله يخفي المراجعات الأقدم.