هل هذه واجهة API لتحويل HTML إلى PDF؟

لا. يقبل gPdf JSON DocumentRequest منظمًا بصفحات وعناصر وإحداثيات وإعدادات. لا يشغّل متصفحًا ولا ينفذ HTML/CSS عشوائيًا.

أي مسار API يجب أن أستدعي أولًا؟

ابدأ بـ POST /api/v1/pdf/render عندما تريد التحكم المباشر في التخطيط. انتقل إلى POST /api/v1/template-render عندما يجب أن يصبح التخطيط عقد template_id مستقرًا.

هل يعيد API ملف PDF مباشرة؟

نعم. العرض الناجح يعيد application/pdf. الأخطاء تستخدم غلاف JSON المشترك مع كود API-XXX و req_id.

هل يمكنني الاختبار دون بناء تكامل؟

استخدم gPdf Playground لاختبار بيانات JSON تفاعليًا، ثم انقل شكل DocumentRequest نفسه إلى عميل الخادم الخلفي لديك.

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

API تحويل JSON إلى PDF لإنشاء مستندات منظمة

حوّل بيانات DocumentRequest المنظمة بصيغة JSON إلى ملفات PDF بصفحات وإحداثيات ونصوص وجداول وباركود وبيانات وصفية وإعدادات PDF/A.

API الرئيسي JSON Render

مسار API /api/v1/pdf/render

الأنظمة خادم خلفي SaaS / عامل API / وكيل AI / صف مهام

جرّب في Playground اقرأ الوثائق

المهمة المطلوبة

تحويل بيانات تطبيق منظمة إلى مستندات PDF حتمية دون تشغيل متصفح أو شحن HTML/CSS أو تخزين ملفات العملاء. يرسل نظامك الصفحات والعناصر والإحداثيات والإعدادات ومحتوى الأعمال؛ ويعيد gPdf استجابة application/pdf.

متى تستخدم هذه API

لدى خادمك الخلفي بيانات منظمة ويحتاج إلى استجابة PDF.
تريد صفحات وإحداثيات وعناصر وباركود وإعدادات صريحة بدل تخطيط HTML.
تحتاج إلى مخرجات قابلة للإعادة للفواتير أو الملصقات أو التقارير أو الكشوف أو حزم المستندات المولدة.
تريد اختبار البيانات في Playground قبل وضع token في الإنتاج.

ما الذي لا تستبدله

تحتاج إلى تحويل HTML عشوائي إلى PDF. يستخدم gPdf JSON DocumentRequest، لا DOM متصفح.
يريد فريقك عقد template_id مستقرًا. استخدم Template Render بعد نشر التخطيط.
تحتاج إلى تغليف فواتير Factur-X أو ZUGFeRD الإلكترونية. استخدم مسار E-Invoice Render.

أي مسار API يجب استدعاؤه

الرئيسي

/api/v1/pdf/render

JSON Render هو المسار الافتراضي لسير العمل هذا.

ثانوي 1

/api/v1/template-render

استخدمه عندما يحتاج سير العمل إلى مسار API مرتبط، أو عقد قالب، أو استعلام capabilities.

طلب مختصر

POST /api/v1/pdf/render - DocumentRequest من صفحة واحدة بصيغة JSON.

{
  "pages": [
    {
      "size": "a4",
      "elements": [
        {
          "type": "text",
          "x": 20,
          "y": 24,
          "content": "Hello from gPdf",
          "style": {
            "font_size": 18,
            "font_family": "NotoSans-Regular"
          }
        }
      ]
    }
  ]
}

ما يتولاه gPdf

عرض DocumentRequest من الصفحات والعناصر.
النص والجداول والصور والباركود المتجهي والخطوط والأشكال والعلامات المائية والبيانات الوصفية وإعدادات PDF/A.
تضمين الخطوط ومسارات بديلة للاتينية وCJK والرموز التعبيرية والكتابات المدعومة الأخرى.
استجابة PDF ثنائية مع غلاف أخطاء gPdf المشترك عند الفشل.

ما يبقى ضمن مسؤولية نظامك

بيانات الأعمال وربط الحقول ودلالات المستند.
معرّفات الطلب، واستراتيجية إعادة المحاولة والحتمية، وتسمية الملفات، والتخزين بعد الاستجابة.
أي قواعد ضرائب أو فواتير أو ناقل أو امتثال أو قواعد خاصة بالعميل قبل العرض.

قائمة فحص الإنتاج

أنشئ X-Request-Id ومرره لتسهيل التتبع.
تحقق من البيانات مقابل OpenAPI أو الوثائق قبل إرسال حركة إنتاج.
اجعل عنوان API الأساسي قابلًا للتهيئة وخزّن bearer token خارج الكود المصدري.
قرر ما إذا كانت المخرجات يجب أن تكون inline أو attachment.
أضف اختبارات golden-PDF للتخطيطات الحرجة حتى تظهر تغييرات القالب أو البيانات.

حدود الادعاءات

هذه ليست HTML-to-PDF ولا تشغّل Chromium.
يعرض API المستند الذي تصفه؛ ولا يستنتج معنى قانونيًا أو تجاريًا من بياناتك.
بالنسبة إلى التخطيطات المتكررة، يكون Template Render عادةً العقد العام الأفضل.

كيف يتناسب سير JSON Render

JSON Render هو أدنى مسار عرض عام في المستوى. يرسل تطبيقك بنية المستند مباشرة: حجم الصفحة، والعناصر، والإحداثيات، والتنسيق، والبيانات الوصفية، ووضع الإخراج، وإعدادات PDF/A الاختيارية. هذا هو المستوى المناسب عندما يولد الكود تخطيط المستند أو عندما يريد فريقك تحكمًا دقيقًا في PDF.

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

متى تنتقل إلى Template Render

إذا كان التخطيط نفسه يُستخدم مرارًا عبر أنظمة متعددة، فانشره كقالب واستدع POST /api/v1/template-render مع template_id و data[]. هذا ينقل مسؤولية التخطيط خارج كل متصل ويمنح ERP أو OMS أو WMS أو خادم SaaS الخلفي عقد حقول مستقرًا.

استخدم JSON Render لإنشاء التخطيط والمستندات الفردية والمستندات البرمجية. واستخدم Template Render عندما يكون التخطيط ثابتًا ولا يتغير في كل طلب إلا بيانات الأعمال.

شكل الإنتاج

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

الأسئلة الشائعة

هل هذه واجهة API لتحويل HTML إلى PDF؟: لا. يقبل gPdf JSON DocumentRequest منظمًا بصفحات وعناصر وإحداثيات وإعدادات. لا يشغّل متصفحًا ولا ينفذ HTML/CSS عشوائيًا.
أي مسار API يجب أن أستدعي أولًا؟: ابدأ بـ POST /api/v1/pdf/render عندما تريد التحكم المباشر في التخطيط. انتقل إلى POST /api/v1/template-render عندما يجب أن يصبح التخطيط عقد template_id مستقرًا.
هل يعيد API ملف PDF مباشرة؟: نعم. العرض الناجح يعيد application/pdf. الأخطاء تستخدم غلاف JSON المشترك مع كود API-XXX و req_id.
هل يمكنني الاختبار دون بناء تكامل؟: استخدم gPdf Playground لاختبار بيانات JSON تفاعليًا، ثم انقل شكل DocumentRequest نفسه إلى عميل الخادم الخلفي لديك.