Shipping label API สำหรับฉลาก PDF ขนาด 4x6
สร้าง PDF ฉลากการจัดส่งขนาด 4x6 ที่พร้อมพิมพ์จาก order JSON พร้อมบาร์โค้ดเวกเตอร์ ขนาดหน้าฉลาก และ reprint ในคลังสินค้าแบบ deterministic
/api/v1/pdf/render เรนเดอร์ PDF ขนาดฉลากจากข้อมูล order, recipient, service และ tracking เพื่อให้ warehouse หรือ ecommerce backend พิมพ์ฉลาก 4x6 เดิมได้อย่างน่าเชื่อถือระหว่าง fulfillment และ reprint ได้ deterministic เมื่อจำเป็น
ควรใช้ API นี้เมื่อใด
- ระบบของคุณมี tracking number, destination, service text และ barcode payload อยู่แล้ว
- คุณต้องการ PDF output สำหรับ workflow ของ thermal printer เช่น Zebra, SATO, Honeywell หรือรุ่นอื่น
- คุณต้องการ barcode modules แบบเวกเตอร์แทนภาพ raster barcode ที่วางใน PDF
- คุณต้องการให้ payload เดิมเรนเดอร์เป็นฉลากเดิมสำหรับ reprints และ audit evidence
สิ่งที่ไม่ได้ทดแทน
- คุณต้องการ buy postage, rate shipment หรือสร้าง carrier label ผ่าน carrier account
- คุณต้องการ ZPL replacement endpoint gPdf ส่งกลับ PDF ไม่ใช่ printer command language
- คุณต้องการ carrier certification จาก gPdf scanner และ carrier acceptance testing ยังเป็นของคุณ
ควรเรียก endpoint ใด
/api/v1/pdf/render
JSON Render คือ path หลักสำหรับเวิร์กโฟลว์นี้.
/api/v1/template-render
ใช้เมื่อเวิร์กโฟลว์ต้องการ API path ที่เกี่ยวข้อง สัญญาเทมเพลต หรือการค้นหา capability.
Minimal request
POST /api/v1/pdf/render - ฉลาก 4x6 ขั้นต่ำพร้อม tracking barcode
{
"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" }
}
]
}
]
}
gPdf จัดการอะไร
- หน้า PDF ขนาดฉลาก เช่น workflow 4x6 นิ้ว
- การเรนเดอร์บาร์โค้ดเวกเตอร์สำหรับ carrier และ warehouse label content
- text, address blocks, service marks, lines, boxes และ optional template binding
- PDF output แบบ deterministic สำหรับ warehouse reprints
ระบบของคุณรับผิดชอบอะไร
- carrier account, postage purchase, service selection และ tracking number creation
- barcode payloads, human-readable text, addresses และ routing data ที่ถูกต้อง
- printer setup, label stock, scan testing และ carrier acceptance checks
Production checklist
- พิมพ์ฉลากทดสอบบน printer model และ label stock จริง
- ตรวจ barcode scan rates ที่ target DPI และ scanner distance
- จัดเก็บ source shipment data หรือ PDF ที่ส่งกลับตาม reprint policy ของคุณ
- ใช้ Template Render เมื่อ layout ฉลากได้รับอนุมัติและใช้ซ้ำข้ามระบบแล้ว
- เก็บ carrier-specific logic ไว้นอก rendering request
ขอบเขตของ claim
- gPdf เรนเดอร์ label PDF แต่ไม่ได้ buy postage หรือคุยกับ carriers โดยตรง
- gPdf ไม่ใช่ carrier-label certification authority
- API ให้ output เป็น PDF ไม่ใช่ ZPL, EPL หรือ thermal-printer command stream อื่น
รูปแบบของ shipping label API
หน้า shipping label ไม่ใช่ carrier endpoint แยกต่างหาก คุณเรียก JSON Render ด้วยหน้าขนาดฉลาก text blocks, lines, optional images และ barcode elements สำหรับฉลากที่ใช้ซ้ำ ให้ publish layout ที่อนุมัติแล้วเป็นเทมเพลตและเรียก Template Render พร้อม shipment data
วิธีนี้ทำให้ ownership ชัดเจน gPdf เป็นเจ้าของ PDF rendering และ barcode drawing ระบบของคุณเป็นเจ้าของ carrier transaction, shipment state และ payload semantics
JSON Render เทียบกับ Template Render
ใช้ JSON Render เมื่อ fulfillment system ของคุณสร้าง layout ทั้งหมด หรือเมื่อทีม operations ยังปรับพิกัดอยู่ ใช้ Template Render เมื่อคลังสินค้าอนุมัติ layout ฉลากที่เสถียรแล้ว และ caller ทุกตัวควรส่ง data fields ชุดเดียวกัน
ทั้งสองเส้นทางส่งกลับ PDF output ความแตกต่างคือ caller อธิบาย layout ทุก request หรืออ้างถึง template_id ที่ publish แล้ว
การทดสอบการพิมพ์สำคัญ
คุณภาพของ thermal label เป็นเรื่องกายภาพ ตรวจ output บน label stock, printer และ scanner จริง ความถูกต้องของ barcode payload, quiet zones, printer darkness และกฎเฉพาะ carrier เป็น production responsibilities ที่อยู่นอก rendering API
FAQ
- gPdf สร้าง carrier labels ให้หรือไม่
- ไม่ carrier หรือ shipping system ของคุณสร้าง carrier shipment และ barcode payload ส่วน gPdf เรนเดอร์ข้อมูลนั้นเป็นฉลาก PDF
- ใช้ Template Render สำหรับ shipping labels ได้หรือไม่
- ได้ ใช้ JSON Render ระหว่างออกแบบหรือทดสอบฉลาก แล้วใช้ Template Render เมื่อ layout เสถียรและ caller ควรส่งเฉพาะ data
- gPdf output ZPL หรือไม่
- ไม่ public render APIs ให้ output เป็น PDF หาก print path ของคุณต้องการ ZPL ให้แปลงหรือ route PDF ภายนอก gPdf
- ต้อง validate อะไรก่อน production
- พิมพ์บน printer และ label stock จริง สแกนบาร์โค้ดด้วย production scanners และยืนยันว่า text กับ payload เฉพาะ carrier มาจาก shipping system ของคุณ