Apakah ini API HTML-ke-PDF?

Tidak. gPdf menerima JSON DocumentRequest terstruktur berisi halaman, elemen, koordinat, dan pengaturan. gPdf tidak menjalankan browser atau mengeksekusi HTML/CSS arbitrer.

Endpoint mana yang sebaiknya saya panggil lebih dulu?

Mulai dari POST /api/v1/pdf/render saat Anda ingin mengontrol layout secara langsung. Pindah ke POST /api/v1/template-render saat layout perlu menjadi kontrak template_id yang stabil.

Apakah API mengembalikan PDF secara langsung?

Ya. Render yang berhasil mengembalikan application/pdf. Error memakai envelope error JSON bersama dengan kode API-XXX dan req_id.

Bisakah saya menguji tanpa membangun integrasi?

Gunakan gPdf Playground untuk menguji payload JSON secara interaktif, lalu pindahkan bentuk DocumentRequest yang sama ke client backend Anda.

Workflow developer

API JSON ke PDF untuk pembuatan dokumen terstruktur

Ubah payload JSON DocumentRequest yang terstruktur menjadi PDF berisi halaman, koordinat, teks, tabel, barcode, metadata, dan pengaturan PDF/A.

API UTAMA JSON Render

ENDPOINT /api/v1/pdf/render

SISTEM backend SaaS / API worker / AI agent / job queue

Coba di Playground Baca dokumentasi

Pekerjaan yang diselesaikan

Mengubah data aplikasi terstruktur menjadi dokumen PDF yang deterministik tanpa menjalankan browser, mengirim HTML/CSS, atau menyimpan file pelanggan. Sistem Anda mengirim halaman, elemen, koordinat, pengaturan, dan konten bisnis; gPdf mengembalikan respons application/pdf.

Kapan memakai API ini

Backend Anda sudah memiliki data terstruktur dan membutuhkan respons PDF.
Anda menginginkan halaman, koordinat, elemen, barcode, dan pengaturan yang eksplisit, bukan layout HTML.
Anda membutuhkan output yang berulang konsisten untuk invoice, label, laporan, statement, atau paket dokumen yang digenerate.
Anda ingin menguji payload di Playground sebelum memasang token di production.

Apa yang tidak digantikan

Anda membutuhkan konversi HTML-ke-PDF arbitrer. gPdf memakai JSON DocumentRequest, bukan browser DOM.
Tim Anda menginginkan kontrak template_id yang stabil. Gunakan Template Render setelah layout dipublikasikan.
Anda membutuhkan packaging e-invoice Factur-X atau ZUGFeRD. Gunakan endpoint E-Invoice Render.

Endpoint yang dipanggil

UTAMA

/api/v1/pdf/render

JSON Render adalah jalur default untuk workflow ini.

SEKUNDER 1

/api/v1/template-render

Gunakan saat workflow butuh jalur API terkait, kontrak template, atau capability lookup.

Request minimal

POST /api/v1/pdf/render - JSON DocumentRequest satu halaman.

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

Yang ditangani gPdf

Render DocumentRequest dari halaman dan elemen.
Teks, tabel, gambar, barcode vektor, garis, bentuk, watermark, metadata, dan pengaturan PDF/A.
Embedding font dan fallback untuk Latin, CJK, emoji-capable, dan skrip lain yang didukung.
Respons PDF biner dengan envelope kode error gPdf yang sama saat gagal.

Yang dikelola sistem Anda

Data bisnis, mapping field, dan semantik dokumen.
Request ID, strategi retry dan idempotensi, penamaan file, dan penyimpanan setelah respons.
Aturan pajak, invoice, carrier, compliance, atau aturan khusus pelanggan sebelum render.

Checklist produksi

Generate dan kirim X-Request-Id untuk traceability.
Validasi payload terhadap OpenAPI atau docs sebelum mengirim traffic live.
Buat API base URL bisa dikonfigurasi dan simpan bearer token di luar source code.
Tentukan apakah output harus memakai mode inline atau attachment.
Tambahkan golden-PDF tests untuk layout penting agar perubahan template atau data terlihat.

Batas klaim

Ini bukan HTML-ke-PDF dan tidak menjalankan Chromium.
API merender dokumen yang Anda jelaskan; API tidak menyimpulkan makna hukum atau bisnis dari data Anda.
Untuk layout yang berulang, Template Render biasanya menjadi kontrak publik yang lebih baik.

Cara workflow JSON Render digunakan

JSON Render adalah jalur render publik paling rendah levelnya. Aplikasi Anda mengirim struktur dokumen secara langsung: ukuran halaman, elemen, koordinat, styling, metadata, mode output, dan pengaturan PDF/A opsional. Lapisan ini tepat ketika layout dokumen digenerate oleh kode atau ketika tim Anda membutuhkan kontrol PDF sampai level piksel.

Kontrak API-nya eksplisit. Jika sistem Anda mengirim elemen teks, gPdf merender elemen teks. Jika sistem mengirim elemen barcode, gPdf menggambar barcode sebagai konten PDF vektor. gPdf tidak membaca niat bisnis dari payload dan tidak memutuskan apakah nomor invoice, nilai tracking carrier, atau field pajak sudah benar.

Kapan beralih ke Template Render

Jika layout yang sama dipakai berulang di beberapa sistem, publikasikan sebagai template dan panggil POST /api/v1/template-render dengan template_id plus data[]. Ini memindahkan kepemilikan layout keluar dari setiap caller dan memberi ERP, OMS, WMS, atau backend SaaS Anda kontrak field yang stabil.

Gunakan JSON Render untuk pembuatan layout, dokumen sekali pakai, dan dokumen programatik. Gunakan Template Render saat layout sudah tetap dan satu-satunya hal yang berubah per request adalah data bisnis.

Bentuk production

Di production, perlakukan request PDF seperti panggilan API penting lainnya: sertakan request ID, tetapkan timeout, buat retry idempotent, log metadata respons, dan simpan PDF yang dikembalikan hanya di sistem Anda sendiri jika retensi diperlukan. Jalur render gPdf bersifat stateless setelah respons render standar.

FAQ

Apakah ini API HTML-ke-PDF?: Tidak. gPdf menerima JSON DocumentRequest terstruktur berisi halaman, elemen, koordinat, dan pengaturan. gPdf tidak menjalankan browser atau mengeksekusi HTML/CSS arbitrer.
Endpoint mana yang sebaiknya saya panggil lebih dulu?: Mulai dari POST /api/v1/pdf/render saat Anda ingin mengontrol layout secara langsung. Pindah ke POST /api/v1/template-render saat layout perlu menjadi kontrak template_id yang stabil.
Apakah API mengembalikan PDF secara langsung?: Ya. Render yang berhasil mengembalikan application/pdf. Error memakai envelope error JSON bersama dengan kode API-XXX dan req_id.
Bisakah saya menguji tanpa membangun integrasi?: Gunakan gPdf Playground untuk menguji payload JSON secara interaktif, lalu pindahkan bentuk DocumentRequest yang sama ke client backend Anda.