Shipping label API untuk label PDF 4x6
Generate PDF label pengiriman 4x6 siap cetak dari JSON pesanan dengan barcode vektor, ukuran halaman label, dan reprint gudang yang deterministik.
/api/v1/pdf/render Merender PDF berukuran label dari data pesanan, penerima, layanan, dan tracking agar backend gudang atau ecommerce dapat mencetak label 4x6 yang sama secara andal saat fulfillment dan mencetak ulang secara deterministik saat diperlukan.
Kapan memakai API ini
- Sistem Anda sudah memiliki tracking number, tujuan, teks layanan, dan payload barcode.
- Anda membutuhkan output PDF untuk workflow printer thermal Zebra, SATO, Honeywell, atau printer serupa.
- Anda menginginkan modul barcode vektor, bukan gambar barcode raster yang ditempel ke PDF.
- Anda membutuhkan payload yang sama menghasilkan label yang sama untuk reprint dan bukti audit.
Apa yang tidak digantikan
- Anda perlu membeli ongkir, menghitung tarif pengiriman, atau membuat label carrier melalui akun carrier.
- Anda membutuhkan endpoint pengganti ZPL. gPdf mengembalikan PDF, bukan bahasa perintah printer.
- Anda membutuhkan sertifikasi carrier dari gPdf. Pengujian scanner dan penerimaan carrier tetap menjadi tanggung jawab Anda.
Endpoint yang dipanggil
/api/v1/pdf/render
JSON Render adalah jalur default untuk workflow ini.
/api/v1/template-render
Gunakan saat workflow butuh jalur API terkait, kontrak template, atau capability lookup.
Request minimal
POST /api/v1/pdf/render - label 4x6 minimal dengan barcode tracking.
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 4,
"y": 6,
"content": "SHIP TO",
"style": { "font_size": 8, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 4,
"y": 13,
"content": "Acme Warehouse\n1200 Logistics Pkwy\nMemphis TN 38116",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "code128",
"content": "1Z999AA10123456784",
"x": 4,
"y": 62,
"width": 92,
"height": 22,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
Yang ditangani gPdf
- Halaman PDF berukuran label seperti workflow 4x6 inci.
- Render barcode vektor untuk konten label carrier dan gudang.
- Teks, blok alamat, service mark, garis, kotak, dan binding template opsional.
- Output PDF deterministik untuk reprint gudang.
Yang dikelola sistem Anda
- Akun carrier, pembelian ongkir, pemilihan layanan, dan pembuatan tracking number.
- Payload barcode yang benar, teks human-readable, alamat, dan data routing.
- Setup printer, label stock, scan testing, dan pemeriksaan penerimaan carrier.
Checklist produksi
- Cetak label uji pada model printer dan label stock yang benar-benar dipakai.
- Verifikasi tingkat scan barcode pada DPI target dan jarak scanner target.
- Simpan data shipment sumber atau PDF yang dikembalikan sesuai kebijakan reprint Anda.
- Gunakan Template Render setelah layout label disetujui dan dipakai ulang lintas sistem.
- Jaga logika spesifik carrier tetap di luar request render.
Batas klaim
- gPdf merender PDF label; gPdf tidak membeli ongkir atau berbicara langsung dengan carrier.
- gPdf bukan otoritas sertifikasi label carrier.
- API menghasilkan output PDF, bukan ZPL, EPL, atau command stream printer thermal lain.
Bentuk shipping label API
Halaman label pengiriman bukan endpoint carrier terpisah. Anda memanggil JSON Render dengan halaman berukuran label, blok teks, garis, gambar opsional, dan elemen barcode. Untuk label berulang, publikasikan layout yang disetujui sebagai template dan panggil Template Render dengan data shipment.
Ini menjaga kepemilikan tetap jelas. gPdf memiliki render PDF dan penggambaran barcode. Sistem Anda memiliki transaksi carrier, status shipment, dan semantik payload.
JSON Render versus Template Render
Gunakan JSON Render ketika sistem fulfillment Anda menghasilkan layout penuh atau ketika tim operasi masih menyetel koordinat. Gunakan Template Render ketika gudang sudah menyetujui layout label yang stabil dan setiap caller harus mengirim field data yang sama.
Kedua jalur mengembalikan output PDF. Perbedaannya adalah apakah caller menjelaskan layout pada setiap request atau mereferensikan template_id yang sudah dipublikasikan.
Print testing tetap penting
Kualitas label thermal bersifat fisik. Validasi output pada label stock, printer, dan scanner asli. Kebenaran payload barcode, quiet zone, kegelapan printer, dan aturan spesifik carrier adalah tanggung jawab production di luar rendering API.
FAQ
- Apakah gPdf membuat label carrier untuk saya?
- Tidak. Carrier atau sistem pengiriman Anda membuat shipment carrier dan payload barcode. gPdf merender data tersebut menjadi label PDF.
- Bisakah saya memakai Template Render untuk label pengiriman?
- Ya. Gunakan JSON Render saat mendesain atau menguji label, lalu gunakan Template Render ketika layout stabil dan caller cukup mengirim data.
- Apakah gPdf menghasilkan ZPL?
- Tidak. Render API publik menghasilkan PDF. Jika jalur cetak Anda membutuhkan ZPL, konversi atau rute PDF di luar gPdf.
- Apa yang harus saya validasi sebelum production?
- Cetak pada printer dan label stock asli, scan barcode dengan scanner production, dan pastikan teks serta payload spesifik carrier berasal dari sistem pengiriman Anda.