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

روابط المعاينة

إعدادات العارض والتضمين

اضبط المظهر وإظهار العنوان والتنقل بين الصفحات في إعدادات العارض المضمن بالحساب. تعتمد إزالة العلامة والتضمين على استحقاقات الخطة؛ تحقق من الإتاحة المعروضة في اللوحة.

المواقع المسموح بها

أضف المواقع التي ستضمّن العارض فيها إلى المواقع المسموح بها. إذن التضمين وصلاحية المشاركة فحصان منفصلان؛ السماح بموقع لا يعيد تفعيل مشاركة منتهية أو ملغاة. لا تضع مفتاح API في كود المتصفح أو عنوان iframe.

تحقق قبل المشاركة

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

ينشئ رابط عرض مؤقتًا يمكن لعميلك فتحه دون حساب. يمكن لاستدعاء واحد إرجاع روابط تنزيل PDF وDOCX معًا.

الطلب 
curl -X POST https://api.pdfgine.com/api/v1/preview \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateCode": "invoice", "formats": ["pdf", "docx"], "data": { } }'
الاستجابة 
{
  "previewId": "prv_481fac83d9f14a4493021eb128d0876b",
  "previewUrl": "/p/prv_481fac83d9f14a4493021eb128d0876b",
  "expiresAt": "2026-08-29T13:23:43+00:00",
  "pageCount": 1,
  "downloads": [
    { "format": "pdf", "downloadUrl": "/api/v1/previews/prv_481f.../download/pdf?expires=...&token=..." },
    { "format": "docx", "downloadUrl": "/api/v1/previews/prv_481f.../download/docx?expires=...&token=..." }
  ]
}

يحمل الرابط توقيعًا لا يمكن تخمينه وينتهي عند expiresAt.

مدة بقاء المستندات متاحة

ينشئ PDFgine المستندات ويسلّمها، والاحتفاظ بالمستند الناتج قرارك. يحتفظ المنتج بمدخلاته فقط (القوالب وموارد الهوية) ومخرجات مؤقتة. يبقى كل ناتج للمدة التي تختارها في الطلب: accessProfile: short لمدة 24 ساعة (افتراضي)، وstandard لمدة 7 أيام، وextended لمدة 30 يومًا (7 و30 يومًا في Go وما فوق)، وquarter لمدة 90 يومًا (في Max). يبقى رابط المشاركة مفتوحًا لتلك المدة، ويمكن إعادة تنزيل مستند الإنتاج (/render و/documents/render) عبر API خلالها. عند انتهائها تعيد التنزيلات 410 ويُحذف الناتج خلال 24 ساعة، بينما يبقى سجل الإنشاء وعدد الصفحات وبيانات الاستخدام. للاحتفاظ الدائم بمستند خزّنه في نظامك بعد الإنشاء مباشرة.

روابط لتسعين يومًا

إلى جانب الملفين standard وextended يوجد ملف quarter الذي يبقي الرابط صالحًا 90 يومًا، لعقد يحتاج الطرف الآخر إلى إعادة فتحه طوال ربع سنة. يتاح في أعلى خطة، وترى كل خطة الملفات المسموح بها ضمن استحقاقاتها.

إغلاق رابط مبكرًا

ينتهي رابط المشاركة عادةً عند expiresAt. إذا أردت إيقاف عرض المستند، ألغِ الرابط: تكون الاستجابة 204 ويتوقف فورًا.

cURL 
curl -i -X POST https://api.pdfgine.com/api/v1/previews/prv_481fac83d9f14a4493021eb128d0876b/revoke \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

HTTP/1.1 204 No Content

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

  • يجيب إنشاء المعاينة بالحالة 201 لا 200، ويجيب الإلغاء بالحالة 204 دون محتوى. يفشل العميل الذي يحلل كل استجابة كـ JSON عند الإلغاء.
  • تحدد accessProfile عمر الرابط وتتطلب الملفات الأطول خطة مناسبة. يُرفض طلب quarter في خطة لا تشمله، ولا تُختصر المدة بصمت.
  • تحمل الروابط داخل downloads توقيعًا وانتهاء صلاحية. احفظ previewId لا تلك العناوين؛ يتوقف العنوان المحفوظ عند انتهاء صلاحيته.
  • يغلق الإلغاء الرابط لا المستند. يظل الملف لك ويمكن تنزيله عبر API حتى نهاية مدة الاحتفاظ.
  • تستهلك المعاينة صفحات معاينة لا حصة الإنتاج. إنتاج المستند نفسه مجددًا عبر /render يُحسب بشكل منفصل كصفحات قابلة للفوترة.