Buat PDF pertama Anda dengan NextPDF Connect

Sekilas pandang

Resep ini menunjukkan jalur tersingkat dari sesi kosong hingga PDF yang sudah dirender dengan NextPDF Connect. Anda membuat dokumen A4 satu halaman, menambahkan judul dan subjudul, lalu mengembalikan berkas sebagai base64. Pekerjaan ini dilakukan oleh tiga tool Core: create_pdf, add_text, dan output_pdf. Anda tidak memerlukan fon, gambar, atau tingkatan berlisensi.

Transport Connect mengirim setiap pemanggilan tool sebagai permintaan dan mengembalikan hasil tool sebagai respons. Lapisan transport tidak bergantung pada hasil yang dilaporkan oleh tool (PSR-18 §p2).

Pemasangan

Pasang NextPDF Server dan kaitkan sebuah transport:

composer require nextpdf/server

Jalankan server dengan transport yang diharapkan oleh host Anda: Model Context Protocol melalui stdio, REST, atau gRPC. Lihat Ketersediaan transport di bawah. Tool pada resep ini adalah tool Core. Tool tersebut disertakan bersama server, sehingga Anda tidak memerlukan paket Pro atau Enterprise.

Gambaran konseptual

Sesi Connect adalah penyimpanan dokumen di sisi server yang diindeks dengan document_id. create_pdf membuka sesi dan mengembalikan ID. Setiap pemanggilan tool berikutnya menggunakan ID tersebut. Dokumen dimulai dengan satu halaman kosong. Page tree adalah struktur yang digunakan pembaca PDF untuk mengakses setiap halaman (ISO 32000-2 §7.7.3). output_pdf merender sesi menjadi PDF. Secara baku, tool ini kemudian menghapus sesi untuk membebaskan memori.

Ketika Anda memanggil add_text tanpa menentukan x atau y secara eksplisit, teks akan mengalir mengikuti posisinya. Teks dimulai pada posisi kursor saat ini, lalu kursor maju setelah setiap pemanggilan.

Permukaan API

Registri tool menentukan tool ini saat server dimulai. Nama yang ditampilkan di sini adalah nama protokol dari registri. Katalog resmi adalah katalog tool yang sudah digabungkan. Ketersediaan tool bergantung pada tingkatan yang terpasang, tetapi ketiga tool ini selalu tersedia di Core.

Tool	Peran	Tingkat risiko
create_pdf	Membuka sesi dokumen	Aman
add_text	Menulis teks ke dalam dokumen	Hati-hati
output_pdf	Merender dan mengembalikan PDF	Persetujuan Diperlukan (mode berkas) / Peninjauan (base64)

Contoh kode — Memulai cepat

Host melakukan tiga pemanggilan tool. Secara berurutan:

1. Panggil create_pdf dengan page_size: "A4", orientation: "portrait", serta judul dan penulis dokumen. Server mengembalikan sebuah document_id.
2. Panggil add_text dengan document_id tersebut, teks judul, font_size yang besar, width: 0 (lebar konten penuh), dan alignment: "center".
3. Panggil output_pdf dengan document_id tersebut. Tanpa file_path, server mengembalikan PDF sebagai base64 dan menghapus sesi.

Berikut objek argumen minimal untuk create_pdf:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

Respons tersebut mencakup document_id, jumlah halaman, dan geometri halaman. Perlakukan ID tersebut sebagai nilai opaque, dan jangan menyimpulkan makna apa pun darinya.

Contoh kode — Produksi

Pemanggil produksi memeriksa setiap respons sebelum melakukan pemanggilan berikutnya. Pemanggil tidak pernah menggunakan kembali document_id setelah output_pdf menghapus sesi.

1. create_pdf — pastikan respons berisi sebuah document_id. Jika server mengembalikan galat batas sesi, lepaskan sesi yang tidak terpakai lalu coba lagi.
2. add_text (judul) — pastikan respons mengembalikan sebuah position.
3. add_text (subjudul) — gunakan font_size yang lebih kecil; kursor berlanjut di bawah judul.
4. output_pdf — baca bidang base64 dan dekodekan menjadi byte. Flag destroyed mengonfirmasi bahwa sesi telah dihapus.

Berkas dikembalikan secara inline (mode base64), sehingga tidak ada efek samping pada sistem berkas dan tidak ada gerbang persetujuan manusia. Lihat Tingkat risiko HITL.

Kasus tepi & jebakan

• Sesi yang telah dihapus. Setelah output_pdf berjalan dengan nilai baku destroy: true, document_id tidak lagi valid. Setiap pemanggilan berikutnya yang menggunakannya akan mengembalikan galat dokumen tidak dikenal. Sebagai gantinya, buat sesi baru.
• Ukuran halaman tidak dikenal. Server menolak page_size yang tidak dikenali dan mengembalikan galat yang jelas. Gunakan ukuran yang terdokumentasi (A3, A4, A5, A6, Letter, Legal, Tabloid).
• Teks kosong. text yang kosong menghasilkan entri dengan lebar nol, bukan galat. Periksa input Anda sebelum melakukan pemanggilan.
• Batas sesi. Penyimpanan dalam memori membatasi jumlah sesi yang berjalan sekaligus. Segera lepaskan sesi menggunakan output_pdf.

Performa

Satu halaman yang hanya berisi teks dirender jauh di bawah anggaran halaman, dan keluarannya biasanya 1–3 KB. Resep ini menggunakan profil reprodusibilitas render-ganda structural. PDF memuat trailer /ID dan stempel waktu yang berubah dari satu eksekusi ke eksekusi lain, sehingga yang akurat adalah perbandingan struktural (yang dinormalisasi).

Catatan keamanan

Alur base64 tidak memiliki efek samping pada sistem berkas. Alur keluaran berkas memang memilikinya, dan alur itu dibatasi gerbang. Lihat bagian HITL. Perlakukan base64 yang dikembalikan sebagai konten dokumen, bukan sebagai kanal tepercaya. Nilai itu persis byte yang dihasilkan oleh tool tersebut.

Kesesuaian

Pernyataan	Spesifikasi	Klausa	reference_id
Transport mengirim permintaan dan menerima respons, apa pun hasilnya.	PSR-18	§p2
Halaman dicapai melalui page tree dokumen.	ISO 32000-2	§7.7.3

Resep ini menjelaskan cara server menghasilkan keluaran. Resep ini tidak menyatakan kesesuaian terhadap profil apa pun.

Konteks komersial

Tidak berlaku — ketiga tool tersebut adalah Core.

Ketersediaan transport

Transport	Tersedia	Catatan
MCP (stdio)	Ya	Pemanggilan tool dipetakan ke MCP tools/call.
REST	Ya	Setiap tool adalah operasi REST; hasilnya adalah body respons.
gRPC	Ya	Setiap tool adalah pemanggilan unary.

Hasil tool sama di seluruh transport; hanya pembingkaiannya yang berbeda. Hasil yang tidak berhasil tetap merupakan respons normal, bukan kegagalan transport (PSR-18 §p2).

Tingkat risiko HITL

Server menempatkan setiap pemanggilan tool pada jenjang risiko human-in-the-loop (HITL): Aman (0) → Hati-hati (1) → Peninjauan (2) → Persetujuan Diperlukan (3). create_pdf bersifat Aman, dan add_text bersifat Hati-hati. output_pdf bersifat Persetujuan Diperlukan, tetapi dalam mode base64 (tanpa file_path) tool ini turun ke Peninjauan dan berjalan tanpa konfirmasi manusia. Menulis ke berkas membuatnya tetap berada pada Persetujuan Diperlukan. Lihat output-approval dan referensi tingkat risiko HITL.

Amplop JSON gerbang konfirmasi

Resep ini tetap berada dalam mode base64, sehingga gerbang konfirmasi mengembalikan amplop izin:

{ "allowed": true }

Amplop tantangan (allowed: false, dengan string challenge dan token sekali pakai) didokumentasikan di output-approval.

Lihat juga

• Dokumen multihalaman
• Penyematan gambar
• Katalog tool
• Tingkat risiko HITL