واجهة API لـ الفاتورة الإلكترونية في أنظمة الإنتاج
أنشئ الفاتورة الإلكترونية من بيانات backend منظمة بدون متصفح، مع فصل واضح بين PDF rendering الذي ينفذه gPdf ومنطق العمل في نظامك.
/api/v1/e-invoice/render إنشاء الفاتورة الإلكترونية كملف PDF قابل لإعادة الإنتاج من بيانات منظمة. يتولى gPdf إخراج PDF، بينما يبقى معنى البيانات وحالة workflow في نظامك.
متى تستخدم هذه API
- لدى backend بيانات الفاتورة الإلكترونية بالفعل ويحتاج إلى استجابة PDF ثابتة.
- تريد تجنب Chromium أو HTML-to-PDF في مستندات التشغيل.
- تحتاج إلى output قابل للإعادة للطباعة، التدقيق أو المعالجة الدفعية.
ما الذي لا تستبدله
- gPdf لا يشتري الشحن، لا يقدّم ضرائب، لا ينشئ أوامر خارجية ولا يعمل كنظام ضريبي.
- لا يستبدل data validation أو business rules أو تكاملات marketplace.
أي endpoint يجب استدعاؤه
/api/v1/e-invoice/render
E-Invoice Render هو المسار الافتراضي لهذا workflow.
/api/v1/e-invoice/capabilities
استخدمه عندما يحتاج workflow إلى API مرتبط، عقد template، أو capabilities lookup.
Request مختصر
/api/v1/e-invoice/render - الفاتورة الإلكترونية
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
ما يتولاه gPdf
- PDF rendering لـ الفاتورة الإلكترونية من request منظم.
- النصوص، الجداول، الخطوط، الباركود، الصفحات، metadata وخيارات الإخراج حسب request.
- Output حتمي للـ retry وإعادة الطباعة والتدقيق.
ما يملكه نظامك
- البيانات الصحيحة لـ الفاتورة الإلكترونية، قواعد العمل وحالة العملية.
- Authentication، التخزين، workflows الخارجية والتحقق لدى النظام المستقبل.
Checklist الإنتاج
- اختبر ببيانات حقيقية وبالأنظمة التي ستستهلك PDF.
- احتفظ بـ request IDs وأدلة التحقق للدعم، التدقيق وإعادة الطباعة.
- حوّل layout المعتمد إلى template عندما تعيد عدة أنظمة استخدامه.
حدود الادعاء
- gPdf يستخدم public e-invoice endpoint لـ Factur-X / ZUGFeRD PDF/A-3b.
- Tax portals، PDP، SDI، KSeF، ZATCA، IRP، Peppol والالتزامات القانونية خارج scope.
- Buyer data، tax logic، routing والتفسير القانوني المحلي تبقى في نظامك.
شكل API
واجهة API لـ الفاتورة الإلكترونية هو production workflow مبني على APIs العامة في gPdf. يصف request البيانات، layout، settings وأجزاء PDF المطلوب render لها. ينشئ gPdf ملف PDF؛ ويبقى معنى business event في نظامك.
اختيار endpoint
الـ endpoint الافتراضي لهذا workflow هو /api/v1/e-invoice/render. استخدم Template Render بعد اعتماد layout وإعادة استخدامه بين الأنظمة. استخدم E-Invoice Render فقط عند الحاجة إلى Factur-X / ZUGFeRD PDF/A-3b مع EN 16931 CII XML مدمج.
التحقق قبل الإنتاج
تحقق من الفاتورة الإلكترونية ببيانات حقيقية وبالأنظمة downstream. احتفظ بـ request IDs، output وأدلة validation للدعم، التدقيق وإعادة الطباعة.
FAQ
- هل هذا endpoint منفصل؟
- واجهة API لـ الفاتورة الإلكترونية يستخدم public e-invoice endpoint عند الحاجة إلى Factur-X / ZUGFeRD PDF/A-3b. ليس product surface منفصلًا.
- هل يشمل شبكات clearance المحلية؟
- لا. gPdf يرندر ويغلف PDF/e-invoice؛ tax portals وlegal routing تبقى في نظامك.
- هل يمكن الاستمرار في JSON Render؟
- نعم للـ PDFs العادية. استخدم E-Invoice Render عندما يجب أن يحتوي output على structured e-invoice package.