API فواتير PDF لأنظمة الفوترة والمالية
أنشئ فواتير PDF عادية من بيانات الفوترة عبر JSON Render أو Template Render، مع إبقاء منطق الضرائب والمحاسبة داخل نظامك.
/api/v1/pdf/render تحويل بيانات الفاتورة من نظام فوترة أو ERP أو SaaS إلى فاتورة PDF قابلة للقراءة، مع إبقاء الترقيم والضرائب وحالة الدفع والدلالات المحاسبية داخل نظام المتصل.
متى تستخدم هذه API
- تحتاج إلى فواتير PDF عادية للعملاء أو الإيصالات أو الكشوف أو تصديرات المحاسبة.
- يملك نظامك بالفعل أرقام الفواتير وحساب الضرائب وبنود الفاتورة وحالة الدفع.
- تريد جداول وإجماليات وبيانات وصفية وإعدادات PDF/A اختيارية دون تشغيل متصفح.
- تريد عقد template_id لتخطيطات الفواتير المتكررة.
ما الذي لا تستبدله
- تحتاج إلى حزمة فاتورة إلكترونية قانونية مثل Factur-X أو ZUGFeRD. استخدم E-Invoice Render.
- تتوقع من gPdf حساب الضرائب أو التحقق من قواعد المحاسبة أو تسوية المدفوعات.
- تريد تحويل فواتير HTML عشوائية بدل JSON منظم أو قوالب.
أي مسار API يجب استدعاؤه
/api/v1/pdf/render
JSON Render هو المسار الافتراضي لسير العمل هذا.
/api/v1/template-render
استخدمه عندما يحتاج سير العمل إلى مسار API مرتبط، أو عقد قالب، أو استعلام capabilities.
/api/v1/e-invoice/render
استخدمه عندما يحتاج سير العمل إلى مسار API مرتبط، أو عقد قالب، أو استعلام capabilities.
طلب مختصر
POST /api/v1/pdf/render - ترويسة فاتورة وإجمالي بسيطان.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 20,
"y": 42,
"content": "Bill to: Example Customer\nAmount due: USD 245.00",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "line",
"x1": 20,
"y1": 62,
"x2": 190,
"y2": 62
}
]
}
]
}
ما يتولاه gPdf
- عرض PDF الفاتورة من صفحات JSON أو بيانات القوالب.
- النص والجداول وكتل الإجماليات والترقيم والبيانات الوصفية ومخرجات PDF/A اختيارية.
- Template Render لتخطيطات الفواتير المستقرة التي تستخدمها عدة أنظمة.
- استجابة PDF ثنائية وغلاف أخطاء API متسق.
ما يبقى ضمن مسؤولية نظامك
- أرقام الفواتير وحالة الدفع وحساب الضرائب والخصومات والائتمانات ومعنى دفتر الأستاذ.
- بيانات العميل والمصدر وربط بنود الفاتورة والعملات وقواعد التقريب.
- الاحتفاظ والتسليم والبريد الإلكتروني وروابط الدفع والتسوية مع نظام المحاسبة.
قائمة فحص الإنتاج
- أكد أن كل حقل ظاهر في الفاتورة مرتبط ببيانات فوترة مصدرية.
- اختبر تجاوز بنود الفاتورة والأسماء الطويلة للعملاء والفواتير متعددة الصفحات والإجماليات.
- قرر ما إذا كان التخطيط ينتمي إلى JSON Render أو قالب منشور.
- افصل إنشاء PDF الفاتورة العادي عن تغليف الفاتورة الإلكترونية القانونية.
- خزّن معرّفات الطلب وأسماء ملفات المخرجات مع سجلات الفواتير لديك.
حدود الادعاءات
- فواتير PDF العادية ليست مساوية لتفويضات الفواتير الإلكترونية القانونية.
- يعرض gPdf مستند الفاتورة؛ ولا يحسب الضرائب أو الحالة المحاسبية.
- تنتمي مخرجات Factur-X / ZUGFeRD إلى POST /api/v1/e-invoice/render.
الفواتير العادية مقابل الفواتير الإلكترونية
فاتورة PDF العادية هي المستند الذي يقرأه العميل. يمكن إنشاؤها من JSON Render أو Template Render. يقرر نظامك رقم الفاتورة والضرائب والبنود والعملة وحالة الدفع، ثم يعرض gPdf ملف PDF المرئي.
الفاتورة الإلكترونية القانونية مختلفة. يجمع Factur-X و ZUGFeRD بين فاتورة PDF/A-3b قابلة للقراءة وXML EN 16931 CII مضمّن. استخدم POST /api/v1/e-invoice/render لهذه الحزمة.
Template Render هو عادة مسار الإنتاج
نادرًا ما تريد فرق المالية أن يعيد كل سرويس بناء إحداثيات الفاتورة. المسار الشائع هو تصميم الفاتورة مرة واحدة، ونشرها كقالب، ومنح المتصلين template_id مستقرًا مع schema للبيانات. يظل JSON Render مفيدًا للتخطيطات المخصصة والأدوات الداخلية ونمذجة القوالب.
أبق منطق المحاسبة في المنبع
يجب أن يستقبل gPdf قيم العرض النهائية، لا قرارات محاسبية غير محسومة. احسب الضرائب والخصومات والتقريب وحالة الدفع وأهلية الفاتورة قبل استدعاء API العرض. هذا يجعل مخرجات PDF حتمية ويحافظ على النظام المالي كمصدر معتمد للحقيقة.
الأسئلة الشائعة
- هل فاتورة PDF هي نفسها فاتورة إلكترونية؟
- لا. فاتورة PDF العادية مخرج قابل للقراءة البشرية. أما فاتورة Factur-X أو ZUGFeRD الإلكترونية فتضمّن أيضًا XML EN 16931 CII داخل غلاف PDF/A-3b.
- أي مسار API يجب استخدامه للفواتير المتكررة؟
- استخدم Template Render عندما يكون تخطيط الفاتورة مستقرًا ويجب أن يرسل المتصلون template_id مع data فقط. استخدم JSON Render عندما يملك الكود التخطيط.
- هل يحسب gPdf الضرائب؟
- لا. يحسب نظام الفوترة أو المحاسبة لديك الضرائب والإجماليات والخصومات وحالة الدفع قبل إرسال بيانات العرض.
- هل يمكن لفواتير PDF استخدام PDF/A؟
- نعم، يدعم JSON Render إعدادات PDF/A. استخدم E-Invoice Render تحديدًا عندما يجب تغليف الفاتورة كـ Factur-X أو ZUGFeRD.