Template PDF API untuk kontrak dokumen yang stabil
Render PDF dari template_id yang stabil dan array data ketika layout berulang harus dimiliki sekali lalu dipakai ulang oleh caller ERP, OMS, WMS, atau SaaS.
/api/v1/template-render Merender PDF berulang dengan mengirim template_id yang stabil dan array data bisnis, bukan meminta setiap caller menjelaskan halaman, koordinat, dan elemen layout pada setiap request.
Kapan memakai API ini
- Layout dokumen sudah disetujui dan dipakai ulang oleh beberapa caller atau job.
- Caller cukup mengirim data bisnis, bukan JSON layout sampai level koordinat.
- Anda membutuhkan output invoice, packing list, label pengiriman, atau template kustom.
- Anda ingin revisi template aktif dikendalikan di luar caller.
Apa yang tidak digantikan
- Anda masih mendesain layout. Gunakan JSON Render sampai koordinat dan field stabil.
- Anda membutuhkan konversi HTML-ke-PDF arbitrer.
- Anda membutuhkan packaging e-invoice PDF/A-3b dengan CII XML tertanam.
Endpoint yang dipanggil
/api/v1/template-render
Template Render adalah jalur default untuk workflow ini.
/api/v1/pdf/render
Gunakan saat workflow butuh jalur API terkait, kontrak template, atau capability lookup.
Request minimal
POST /api/v1/template-render - render satu invoice dari template.
{
"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"
}
]
}
]
}
Yang ditangani gPdf
- Lookup template berdasarkan template_id yang stabil.
- Render setiap item data terhadap template aktif.
- Menggabungkan halaman hasil render menjadi satu PDF dalam batas endpoint publik.
- Perilaku autentikasi, request ID, dan error envelope yang sama.
Yang dikelola sistem Anda
- Pemilihan template, mapping field, data bisnis, dan otorisasi caller.
- Workflow publikasi template, komunikasi perubahan, dan cakupan test.
- Chunking, queueing, dan retry saat merender banyak dokumen.
Checklist produksi
- Perlakukan template_id sebagai kontrak stabil yang opaque.
- Validasi field data sebelum memanggil Template Render.
- Simpan golden-PDF tests untuk template aktif dan data representatif.
- Pecah batch besar sesuai batas publik Template Render.
- Log template_id, request ID, dan ID objek bisnis untuk traceability.
Batas klaim
- Template Render bukan alat desain dengan sendirinya; template harus sudah dipublikasikan.
- gPdf tidak menyimpulkan data bisnis yang hilang dari template.
- Template Render tidak menggantikan endpoint E-Invoice Render.
Template Render adalah lapisan kontrak production
JSON Render ideal saat layout masih dirancang. Template Render adalah lapisan yang dipakai setelah layout menjadi kontrak. Caller mengirim template_id dan data; template aktif memiliki struktur dokumen.
Ini membuat caller lebih kecil dan membuat perubahan template lebih mudah direview, diuji, dan dirilis.
FAQ
- Kapan saya harus memakai Template Render, bukan JSON Render?
- Gunakan Template Render setelah layout disetujui dan caller hanya perlu mengirim data bisnis.
- Apakah template_id stabil?
- Ya. Docs Template API menjelaskan template_id sebagai identifier stabil yang menghadap caller.
- Bisakah satu request merender beberapa item data?
- Ya, Template Render menerima array data dalam batas endpoint publik.
- Bisakah Template Render membuat e-invoice?
- Tidak. Packaging PDF/A-3b Factur-X dan ZUGFeRD memakai endpoint E-Invoice Render.