Ikhtisar NextPDF Gotenberg

Sekilas pandang

NextPDF Gotenberg adalah jembatan ringan antara NextPDF dan layanan Gotenberg eksternal. Gunakan jembatan ini saat NextPDF tidak dapat merender dokumen Office secara native. Jembatan ini mengirimkan dokumen ke instans Gotenberg melalui Hypertext Transfer Protocol (HTTP), menerima keluaran Portable Document Format (PDF), lalu menyerahkan PDF tersebut ke aplikasi Anda. Setelah itu, NextPDF menangani sisa pascapemrosesan.

Paket ini ringan dan eksplisit. Paket ini tidak menyematkan renderer, tidak menjalankan LibreOffice, dan tidak menjalankan peramban. Setiap konversi menggunakan satu permintaan HTTP multipart ke endpoint Gotenberg. Anda mengoperasikan endpoint tersebut dan mengarahkan jembatan ke endpoint itu melalui konfigurasi.

Gunakan jembatan ini saat Anda memiliki berkas sumber .docx, .xlsx, .pptx, .odt, .ods, atau .odp dan memerlukan keluaran PDF dalam alur NextPDF. Setelah PDF tersedia, NextPDF atau nextpdf/premium menangani penandatanganan, konversi PDF/A, pemberian tanda air, dan penggabungan.

Ketergantungan jembatan

Jembatan ini memiliki satu ketergantungan runtime yang bukan paket PHP: layanan Gotenberg yang sedang berjalan dan dapat dijangkau jembatan melalui Hypertext Transfer Protocol Secure (HTTPS).

• Jembatan ini tidak memasang, mengelola, atau mengawasi Gotenberg. Anda menjalankan Gotenberg sendiri; proyek hulu menerbitkan citra kontainer. Anda bertanggung jawab atas ketersediaan, kapasitas, dan eksposur jaringannya.
• Jembatan ini berkomunikasi dengan rute konversi LibreOffice milik Gotenberg. URL permintaan dibentuk sebagai <apiUrl>/forms/libreoffice/convert, dengan <apiUrl> sebagai URL dasar yang Anda konfigurasikan. Rute inilah yang menentukan kumpulan format yang didukung jembatan.
• Pemeriksaan kesehatan mengirim permintaan HTTP HEAD ke <apiUrl>/health dan menganggap status apa pun di bawah 500 tersedia.

Karena konversi berjalan di layanan yang Anda operasikan, perilakunya bergantung pada versi Gotenberg yang Anda jalankan. Jembatan ini mengirimkan permintaan multipart dengan bentuk tetap, dan hanya bergantung pada dua path Gotenberg: path rute (/forms/libreoffice/convert) dan path kesehatan (/health). Lihat /integrations/gotenberg/install/ untuk dasar penerapan dan /integrations/gotenberg/security-and-operations/ untuk pengerasan layanan.

Format dokumen yang didukung

Jembatan ini hanya mengonversi format yang tercantum dalam tipe OfficeFormat miliknya. Jembatan mendeteksi setiap format dari ekstensi berkas. Pencocokannya tidak peka huruf besar-kecil, dan titik di awal diperbolehkan. Setelah itu, jembatan mengirim setiap berkas ke Gotenberg dengan tipe Multipurpose Internet Mail Extensions (MIME) yang tetap:

Format	Ekstensi	Tipe MIME yang dikirim ke Gotenberg
Word (OOXML)	docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document
Excel (OOXML)	xlsx	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
PowerPoint (OOXML)	pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation
OpenDocument Text	odt	application/vnd.oasis.opendocument.text
OpenDocument Spreadsheet	ods	application/vnd.oasis.opendocument.spreadsheet
OpenDocument Presentation	odp	application/vnd.oasis.opendocument.presentation

Daftar ini lengkap. Ekstensi di luar kumpulan ini memunculkan ValueError sebelum permintaan jaringan apa pun dibuat, sehingga jembatan tidak pernah mencoba konversi yang tidak dapat dijelaskannya. Jembatan ini tidak mengeklaim mendukung “berkas Office apa pun” atau “semua format dokumen.” Jembatan ini mendukung keenam format di atas karena kodenya hanya mengenali keenam format tersebut dan matriks pengujiannya hanya mencakup keenamnya.

Format biner lawas (.doc, .xls, .ppt), rich text (.rtf), teks biasa, comma-separated values (CSV), dan format citra bukan bagian dari kumpulan yang dikenali jembatan. Rute LibreOffice milik Gotenberg sendiri mungkin dapat menerima rentang masukan yang lebih luas. Jembatan ini sengaja membatasi diri pada kumpulan yang tercantum agar deteksi format, tipe MIME, dan metadata hasil tetap konsisten dan dapat diverifikasi.

Bagaimana alur konversi berjalan

Sebuah konversi berjalan sebagai satu lintasan linear. Jembatan memvalidasi setiap langkah sebelum byte apa pun keluar dari proses:

1. Konfigurasi diperiksa. URL Application Programming Interface (API) yang kosong langsung memicu pengecualian konversi.
2. URL API divalidasi. HTTPS diperlukan, dan host diselesaikan serta disaring agar tidak dapat menunjuk ke alamat privat atau alamat yang dicadangkan. Kumpulan alamat hasil resolusi disimpan untuk penyematan di kemudian hari.
3. Masukan dibaca (untuk konversi berkas, path dikanonisasi terlebih dahulu untuk mencegah traversal) dan ekstensinya dipetakan ke sebuah OfficeFormat.
4. Jembatan memeriksa panjang byte terhadap nilai maksimum yang dikonfigurasi dan menyaring nama berkas terhadap urutan traversal, garis miring, byte null, dan karakter kontrol.
5. Kumpulan alamat diperiksa lagi tepat sebelum permintaan dikirim untuk menutup celah antara validasi dan koneksi.
6. Jembatan membentuk badan multipart/form-data dan melakukan POST ke rute LibreOffice, disertai bearer token jika dikonfigurasi.
7. Jembatan mengurai respons. Status harus 200, Content-Type harus mengandung application/pdf, dan badan respons harus diawali dengan tanda tangan %PDF. Baru setelah itu, sebuah hasil dikembalikan.

Setiap kegagalan pada langkah 1–7 memunculkan pengecualian bertipe. Jembatan tidak mengembalikan hasil parsial atau hasil yang belum diperiksa. Jenis pengecualian yang tepat beserta pemicunya dikatalogkan di /integrations/gotenberg/troubleshooting/.

Apa yang Anda dapatkan kembali

Konversi yang berhasil mengembalikan objek hasil. Objek tersebut mencakup byte PDF mentah, format sumber yang dikonversi, dan pengukuran waktu render opsional. Objek ini juga mengekspos pemeriksaan validitas (badan yang tidak kosong dan diawali dengan %PDF) serta pengakses ukuran byte. Byte tersebut merupakan aliran PDF biasa, sehingga Anda dapat menuliskannya ke disk, mengalirkannya ke klien, atau memasukkannya ke dalam dokumen NextPDF untuk pemrosesan lebih lanjut.

Di mana jembatan berhenti

Jembatan mengonversi dan memvalidasi. Jembatan tidak:

• Menandatangani, mengenkripsi, melinearisasi, atau mengonversi keluaran ke PDF/A. NextPDF core atau nextpdf/premium menangani pascapemrosesan tersebut.
• Mencoba ulang permintaan yang gagal, mengantrekan pekerjaan, atau menyimpan hasil dalam cache. Hal-hal itu menjadi tanggung jawab lapisan aplikasi. /integrations/gotenberg/production-usage/ menunjukkan cara menambahkannya di sekitar jembatan.
• Mengelola siklus hidup layanan Gotenberg. Penerapan dan operasi dibahas di /integrations/gotenberg/security-and-operations/.

Edisi dan pascapemrosesan

NextPDF core open source software (OSS) dapat menuliskan PDF hasil konversi apa adanya. Jika Anda perlu menandatangani dokumen hasil konversi, menghasilkan profil pengarsipan PDF/A, atau menerapkan tanda air, paket nextpdf/premium menambahkan kemampuan tersebut. Jembatan ini sendiri netral terhadap edisi: ia menghasilkan PDF. Apa yang Anda lakukan dengan PDF tersebut menentukan apakah Anda memerlukan edisi komersial.

Baseline PDF Advanced Electronic Signatures (PAdES) yang tersedia di edisi Pro hanya B-B. Profil long-term validation (LTV) (B-T, B-LT, B-LTA) bukan bagian dari edisi Pro dan tidak disediakan oleh jembatan ini. Jangan menyimpulkan kemampuan stempel waktu atau LTV dari keberadaan paket ini.

Lihat juga

• /integrations/gotenberg/install/ — pasang paketnya dan terapkan Gotenberg dasar.
• /integrations/gotenberg/configuration/ — setiap opsi konfigurasi, tipenya, nilai standar, dan efeknya.
• /integrations/gotenberg/quickstart/ — jalankan konversi pertama Anda.
• /integrations/gotenberg/production-usage/ — sambungkan jembatan ke aplikasi nyata.
• /integrations/gotenberg/troubleshooting/ — katalog pengecualian dan arti setiap pengecualian.
• /integrations/gotenberg/security-and-operations/ — model keamanan dan cara mengoperasikan layanan dependensi dengan aman.
• /integrations/gotenberg/boot-and-discovery/ — bagaimana framework host menemukan dan menyambungkan jembatan.
• /integrations/gotenberg/integration/ — jalankan rendering NextPDF melalui layanan tersebut.