إنشاء مستند

ما يفعله هذا الطرف النهائي

يحوّل استدعاء واحد القالب وبياناتك إلى ملف نهائي. يُنتج المستند أثناء انتظارك وتتضمن الاستجابة عنوان تنزيل، دون استعلام متكرر. للمستندات الطويلة أو المعالجة الجماعية، ينفذ طرف قائمة الانتظار العمل نفسه في الخلفية.

أرسل رمز القالب وبياناتك لتحصل على المستند. عنوان URL للتنزيل في الاستجابة نسبي إلى العنوان الأساسي ويُجلب بمفتاح API نفسه.

curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "locale": "ar",
        "purpose": "production",
        "data": {
          "document": { "title": "INV-2026-001" }
        }
      }'

يقبل الحقل format ‏"pdf" أو "docx". تستمر القيم الرقمية بالعمل للعملاء الحاليين: 1 هو PDF و2 هو DOCX. تعيد الاستجابات التنسيق كعدد.

تستهلك purpose بالقيمة production من حصتك. عند تجربة قالب أرسل editor-test؛ لا يستهلك هذا الناتج الحصة ويستخدم مراجعة المسودة غير المنشورة.

دورة الطلب والاستجابة كاملة

هذه استجابة الاستدعاء أعلاه والاستدعاء الذي يجلب الملف. الحالة 202: قُبل الطلب والمستند جاهز.

HTTP/1.1 202 Accepted
X-PDFgine-Pages: 1
X-PDFgine-Quota-Remaining: 4999

{
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "format": "pdf",
  "templateCode": "invoice",
  "templateVersion": 1,
  "templateVersionSource": "published",
  "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
  "pageCount": 1,
  "quotaRemaining": 4999,
  "meteringBasis": "pdf-equivalent"
}

curl https://api.pdfgine.com/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -o invoice.pdf

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

• يستجيب الإنشاء بالحالة 202 لا 200. العميل الذي يعد أي حالة غير 200 فشلًا يبلّغ عن النجاح كخطأ.
• تحدد purpose أمرين معًا: تستخدم production الإصدار المنشور وتستهلك الحصة، وتستخدم editor-test المسودة غير المنشورة دون استهلاك. التجربة باستخدام production هي أغلى طريقة لاختبار قالب.
• ليست 422 عطلًا في الخادم. يسرد المحتوى تحت errors جميع الحقول التي طلبها القالب، لذا يكون الحل في تصحيح البيانات المُرسلة لا إعادة المحاولة.
• تعني 402 نفاد حصة الصفحات الشهرية. وتخبرك ترويسة X-PDFgine-Quota-Remaining قبل بلوغ ذلك.
• تكون downloadUrl نسبية إلى عنوان API. حفظها كعنوان URL مطلق يعطلها عند تغير العنوان؛ احفظ documentId وابنِ العنوان.