API nhãn kho cho quy trình in của WMS và ERP
Tạo PDF nhãn pallet, case, bin, inventory và warehouse-operation từ dữ liệu WMS hoặc ERP với reprint xác định.
/api/v1/pdf/render Kết xuất nhãn kho từ dữ liệu WMS hoặc ERP cho pallet, carton, bin, asset, location và inventory movements, trong khi inventory state, picking rules và warehouse operations vẫn nằm trong hệ thống gọi.
Khi nào dùng API này
- Hệ thống của bạn đã có dữ liệu cần in, payload mã vạch và nội dung hiển thị.
- Bạn cần đầu ra PDF cho quy trình in kho, fulfillment hoặc vận hành.
- Bạn muốn mã vạch vector thay vì ảnh raster dán vào PDF.
- Bạn cần cùng payload kết xuất ra cùng tài liệu để reprint và audit.
Những gì không thay thế
- Bạn cần mua vận chuyển, tính cước hoặc tạo nhãn hãng vận chuyển qua tài khoản hãng vận chuyển.
- Bạn cần endpoint thay thế ZPL/EPL. gPdf trả về PDF, không phải máy in command language.
- Bạn cần gPdf chứng nhận hãng vận chuyển hoặc quy trình vận hành. Kiểm thử scan và acceptance vẫn thuộc về bạn.
Endpoint cần gọi
/api/v1/pdf/render
JSON Render là đường mặc định cho quy trình này.
/api/v1/template-render
Dùng khi quy trình cần API liên quan, hợp đồng mẫu hoặc truy vấn năng lực.
Request tối thiểu
POST /api/v1/pdf/render - nhãn kho.
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 6,
"y": 8,
"content": "PALLET LAX-01-2026-00042",
"style": { "font_size": 12, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "sscc-18",
"content": "012345678901234567",
"x": 6,
"y": 30,
"width": 88,
"height": 26,
"barcode_text": { "enabled": true, "position": "bottom" }
},
{
"type": "text",
"x": 6,
"y": 70,
"content": "SKU: CASE-001\nQTY: 48\nLOCATION: A-14-02",
"style": { "font_size": 10, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf xử lý gì
- Trang PDF cỡ label hoặc tài liệu vận hành theo request.
- Kết xuất mã vạch vector cho nội dung hãng vận chuyển, kho hoặc vận hành.
- Văn bản, block địa chỉ, service marks, đường kẻ, khung và binding template tùy chọn.
- Đầu ra PDF xác định cho reprint trong kho.
Hệ thống của bạn quản lý gì
- Tài khoản hãng vận chuyển hoặc marketplace, lựa chọn dịch vụ và tạo mã tracking nếu có.
- Payload mã vạch đúng, text đọc được, địa chỉ, routing data và dữ liệu vận hành.
- Thiết lập máy in, vật liệu nhãn, kiểm thử scan và kiểm tra acceptance.
Checklist đưa vào production
- In thử trên đúng model máy in và vật liệu nhãn.
- Kiểm tra tỷ lệ scan mã vạch ở DPI và khoảng cách máy quét mục tiêu.
- Lưu dữ liệu nguồn hoặc PDF trả về theo reprint policy.
- Dùng Template Render khi bố cục đã duyệt và được nhiều hệ thống dùng lại.
- Giữ logic hãng vận chuyển hoặc đặc thù marketplace ngoài request kết xuất.
Ranh giới tuyên bố
- gPdf kết xuất PDF tài liệu; gPdf không mua vận chuyển hoặc gọi trực tiếp hãng vận chuyển.
- gPdf không phải cơ quan chứng nhận hãng vận chuyển, marketplace hoặc GS1.
- API tạo đầu ra PDF, không phải ZPL, EPL hoặc command stream của máy in nhiệt.
Nhãn kho là bản ghi vận hành
Nhãn kho là bản ghi vận hành cho pallet, carton, bin, asset, location hoặc inventory movement. gPdf kết xuất PDF nhãn; WMS hoặc ERP vẫn là nguồn sự thật cho trạng thái tồn kho, picking rules và nghiệp vụ kho.
Template Render giúp trạm in đơn giản hơn
Khi bố cục nhãn đã ổn định, Template Render cho phép trạm in hoặc backend chỉ gửi dữ liệu nghiệp vụ theo template_id. Điều này giảm việc lặp lại logic bố cục ở từng hệ thống gọi.
Tính xác định khi in lại
Kho thường cần reprint cùng một nhãn. Hãy log request ID, ID đối tượng nguồn và dữ liệu đã dùng để kết xuất, đồng thời kiểm tra quét mã vạch và vật liệu nhãn trên thiết bị production.
FAQ
- Đây có phải API nhãn kho độc lập không?
- Có. Trang này ánh xạ quy trình nhãn kho vào endpoint công khai POST /api/v1/pdf/render. Hệ thống của bạn vẫn sở hữu dữ liệu nghiệp vụ, còn gPdf chỉ tạo PDF từ request hợp lệ.
- Khi nào nên dùng Template Render?
- Dùng Template Render khi bố cục đã được duyệt và bạn muốn gọi bằng template_id cùng data thay vì gửi toàn bộ tọa độ ở mỗi request.
- API có trả PDF trực tiếp không?
- Có. Khi kết xuất thành công, API trả về application/pdf. Khi lỗi, API dùng JSON error envelope chung với mã API-XXX và req_id.
- Cần kiểm tra gì trước production?
- Hãy in thử bằng máy in thật, kiểm tra scan mã vạch và xác nhận với hãng vận chuyển, marketplace hoặc quy trình kho liên quan.