متى أستخدم Template Render بدل JSON Render؟

استخدم Template Render بعد اعتماد التخطيط، وعندما يجب أن يرسل المتصلون بيانات الأعمال فقط.

هل template_id مستقر؟

نعم. تصف وثائق Template API ‏template_id بوصفه المعرّف المستقر المواجه للمتصل.

هل يمكن لطلب واحد عرض عدة عناصر data؟

نعم، يقبل Template Render مصفوفة data ضمن حدود مسار API العامة.

هل يستطيع Template Render إنشاء فواتير إلكترونية؟

لا. يستخدم تغليف Factur-X و ZUGFeRD PDF/A-3b مسار E-Invoice Render.

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

API قوالب PDF لعقود مستندات مستقرة

اعرض ملفات PDF من template_id مستقر ومصفوفة data عندما يجب امتلاك التخطيطات المتكررة مرة واحدة وإعادة استخدامها بواسطة ERP أو OMS أو WMS أو متصلين SaaS.

API الرئيسي Template Render

مسار API /api/v1/template-render

الأنظمة خادم خلفي SaaS / تكامل ERP / OMS / WMS / صف مهام

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

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

عرض ملفات PDF متكررة بإرسال template_id مستقر ومصفوفة بيانات أعمال بدل مطالبة كل متصل بوصف الصفحات والإحداثيات وعناصر التخطيط في كل طلب.

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

تم اعتماد تخطيط المستند ويعاد استخدامه بواسطة عدة متصلين أو مهام.
يجب أن يرسل المتصلون بيانات الأعمال، لا JSON تخطيط على مستوى الإحداثيات.
تحتاج إلى مخرجات فاتورة أو قائمة تعبئة أو ملصق شحن أو قالب مخصص.
تريد التحكم في مراجعات القالب النشطة خارج المتصل.

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

ما زلت تصمم التخطيط. استخدم JSON Render حتى تستقر الإحداثيات والحقول.
تحتاج إلى تحويل HTML عشوائي إلى PDF.
تحتاج إلى تغليف فاتورة إلكترونية PDF/A-3b مع CII XML مضمّن.

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

الرئيسي

/api/v1/template-render

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

ثانوي 1

/api/v1/pdf/render

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

طلب مختصر

POST /api/v1/template-render - عرض فاتورة واحدة من قالب.

{
  "template_id": "invoice",
  "data": [
    {
      "invoice_number": "INV-2026-001",
      "date_of_issue": "2026-05-29",
      "date_due": "2026-06-28",
      "issuer_name": "Acme Cloud Inc.",
      "issuer_address": "88 Harbor Rd, Long Beach, CA",
      "bill_to_name": "Receiver Inc.",
      "bill_to_address": "123 Main St, Los Angeles, CA",
      "subtotal": "$100.00",
      "total": "$100.00",
      "amount_due": "$100.00",
      "items": [
        {
          "description": "Service A",
          "qty": 1,
          "unit_price": "$100.00",
          "amount": "$100.00"
        }
      ]
    }
  ]
}

ما يتولاه gPdf

البحث عن القالب عبر template_id مستقر.
عرض كل عنصر data مقابل القالب النشط.
دمج الصفحات المعروضة في PDF واحد ضمن حدود مسار API العامة.
سلوك مصادقة ومعرّف طلب وغلاف أخطاء مشترك.

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

اختيار القالب وربط الحقول وبيانات الأعمال وتفويض المتصل.
سير نشر القالب والتواصل حول التغييرات وتغطية الاختبارات.
التقسيم والصفوف وإعادة المحاولة عند عرض مستندات كثيرة.

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

عامل template_id كعقد مستقر ومبهم.
تحقق من حقول data قبل استدعاء Template Render.
احتفظ باختبارات golden-PDF للقالب النشط وبيانات تمثيلية.
قسّم الدُفعات الكبيرة وفق حدود Template Render العامة.
سجّل template_id ومعرّف الطلب ومعرّفات كائنات الأعمال للتتبع.

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

Template Render ليس أداة تصميم بذاته؛ يجب أن تكون القوالب منشورة مسبقًا.
لا يستنتج gPdf بيانات أعمال ناقصة من القالب.
لا يستبدل Template Render مسار E-Invoice Render.

Template Render هو طبقة عقد الإنتاج

JSON Render مثالي أثناء تصميم التخطيط. أما Template Render فهو الطبقة المستخدمة بعد أن يصبح التخطيط عقدًا. يرسل المتصلون template_id وdata؛ ويملك القالب النشط بنية المستند.

هذا يجعل المتصلين أصغر ويجعل تغييرات القالب أسهل في المراجعة والاختبار والنشر.

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

متى أستخدم Template Render بدل JSON Render؟: استخدم Template Render بعد اعتماد التخطيط، وعندما يجب أن يرسل المتصلون بيانات الأعمال فقط.
هل template_id مستقر؟: نعم. تصف وثائق Template API ‏template_id بوصفه المعرّف المستقر المواجه للمتصل.
هل يمكن لطلب واحد عرض عدة عناصر data؟: نعم، يقبل Template Render مصفوفة data ضمن حدود مسار API العامة.
هل يستطيع Template Render إنشاء فواتير إلكترونية؟: لا. يستخدم تغليف Factur-X و ZUGFeRD PDF/A-3b مسار E-Invoice Render.