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

الاستجابة

ما يعود في الاستجابة

تستجيب كل عملية إنشاء ناجحة بالكائن نفسه. يستحق حقلان الحفظ: يعرّف documentId الملف طوال مدة الاحتفاظ به، ويحدد pageCount ما تُحسب عليه الفوترة الشهرية.

الاستجابة

{
  "documentId": "doc_5bd26de32c324a4bb8cffad2c80edd01",
  "jobId": "job_00b96f006b034258b00b650d724d0207",
  "fileName": "invoice-doc_5bd26de32c324a4bb8cffad2c80edd01.pdf",
  "format": "pdf",
  "templateCode": "invoice",
  "templateVersion": 5,
  "templateVersionSource": "published",
  "downloadUrl": "/api/v1/documents/doc_5bd2.../download/pdf",
  "previewUrl": null,
  "pageCount": 1,
  "quotaRemaining": 4999,
  "meteringBasis": "pdf-equivalent",
  "createdAt": "2026-08-28T13:23:32+00:00"
}

يبقى الناتج خاصًا ويتطلب تنزيله مفتاح API الخاص بك. استخدم طرف المعاينة فقط عندما تحتاج عمدًا إلى رابط مؤقت للعميل.

ترويسات الاستجابة

تكرر كل استجابة إنشاء أرقام القياس في ترويساتها، لتتابع الحصة دون استدعاء ثانٍ.

`X-PDFgine-Pages`	عدد صفحات هذا المستند
`X-PDFgine-Job`	معرّف مهمة الإنشاء
`X-PDFgine-Quota-Remaining`	الصفحات المتبقية بعد العملية
`X-PDFgine-Metering-Basis`	وحدة القياس

حقلًا بحقل

تعود الحقول نفسها مع pdf وdocx وhtml؛ يتغير fileName فقط.

الحقل	المعنى
`documentId`	معرّف الملف المُنتج. تستخدمه التنزيلات والحالة والمشاركة، لذا فهو القيمة التي تستحق الحفظ.
`downloadUrl`	نسبي إلى عنوان API ويُجلب بالمفتاح نفسه. إنه مسار وليس رابطًا عامًا.
`templateVersion`	إصدار القالب الذي أنتج هذا الملف. احتفظ به لتتمكن من تفسير إعادة الطباعة بعد أشهر.
`templateVersionSource`	published لإنشاء الإنتاج، وdraft عندما تكون purpose هي editor-test.
`pageCount`	عدد الصفحات المُنتجة؛ وهو ما تحسبه الحصة.
`quotaRemaining`	الصفحات المتبقية في الشهر الحالي وقت هذه الاستجابة.
`meteringBasis`	معنى الصفحة لأغراض الفوترة. تحسب pdf-equivalent ناتج docx أو html بعدد الصفحات نفسه الذي سيكون عليه PDF.
`previewUrl`	يُملأ فقط عند مشاركة المستند، ويكون null خلاف ذلك.

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

downloadUrl مسار. لصقه في متصفح دون عنوان API والمفتاح يعيد 404 أو 401 وليس الملف.
احفظ documentId لا الاستجابة كلها. تُحذف الملفات بعد مدة الاحتفاظ المحددة في خطتك، وعندها لا يشير عنوان URL المحفوظ إلى شيء.
quotaRemaining لقطة لتلك اللحظة وليست عدادًا مباشرًا. قد يقرأ استدعاءان متزامنان الرقم نفسه.
pageCount وحدة الفوترة وليست عدد الملفات. يستهلك مستند من عشر صفحات عشر صفحات سواء طلبت pdf أو docx.
كون previewUrl بالقيمة null لا يعني فشل المشاركة، بل يعني أن ناتج الإنشاء لم يُشارك. المشاركة استدعاء منفصل.