Nextwaves Label - Designer & EZPL Printer

Mô hình tích hợp

Template được thiết kế trực quan trong UI. Khi in, hệ thống khách hàng gửi JSON values theo field contract; local API apply values vào profile và compile trực tiếp thành GoDEX EZPL.

Workflow khuyến nghị là profile-based: template đã duyệt được publish thành profile local, sau đó hệ thống tích hợp chỉ cần gọi profileId với values.

Thành phần	Vai trò
Data Feed columns	Danh sách field động mà hệ thống tích hợp có thể apply value.
Placeholder	Cú pháp {field_name} đặt trong Text, QR, Barcode, Table hoặc RFID data.
API profile	Template đã publish, có profileId ổn định để hệ thống gọi khi in.
Local Print Agent	Service local mở Windows printer queue, ghi RAW EZPL bytes và đóng handle.

Cài đặt local services

Luồng thiết kế template và in COM/RS232 thủ công có thể dùng web public tại label.nextwaves.com.

Nếu hệ thống khách hàng gọi API để in tự động, cần chạy Nextwaves Label API local/on-prem trên PC hoặc server nội bộ có thể truy cập máy in.

Nếu in qua USB-B/Windows printer queue, cần cài GoDEX driver và chạy Nextwaves Local Print Agent trên chính PC đang cắm máy in.

Máy in GoDEX cần được cài driver để Windows expose printer name, ví dụ GoDEX ZX1200i+ trên USB001.

Public designer:
1. Open https://label.nextwaves.com
2. Design and validate the label template

Manual USB-B printing:
1. Download GoDEX driver: /driver/Godex_2025.1.exe
2. Download Local Print Agent: /agent/NextwavesLocalPrintAgent.exe
3. Run the agent on the PC connected to the printer

Customer system integration:
1. Run Nextwaves Label API locally, for example http://localhost:9999
2. Run Local Print Agent locally, for example http://127.0.0.1:17917
3. Publish the approved template as an API profile
4. Customer system calls the profile print endpoint with values

Development build:
npm run build-agent:windows

Thiết kế template và field contract

1Tạo Data Feed columns

Thêm các field động như product_name, qr_code, unit, lot, expired_date, rfid_id. Đây là contract mà customer system phải gửi.

2Bind placeholder vào element

Text, QR, Barcode, Table cell và RFID EPC data có thể dùng {field_name}. Line, rectangle, image/icon là layout cố định, không cần field.

3Dùng row đầu làm sample

Row đầu trong Data Feed là dữ liệu preview/default. Nếu runtime thiếu field, API sẽ fallback về sample value.

4Validate trên máy in thật

Kiểm tra DPI, gap, offset, sensor mode, RFID power/write position và dữ liệu EPC trước khi publish profile.

Publish template thành API profile

Trong Print step có nút Publish API profile. Nút này lưu template vào local profile storage và trả ra endpoint in cho khách hàng.

Có thể publish bằng API nếu deployment tool muốn tự động đăng ký template.

import template from "./product-label.nwl.json";

await axios.post("http://localhost:9999/api/integration/profiles", {
  profileId: "product-label-rfid",
  name: "Product Label RFID",
  overwrite: true,
  template
});

Customer gọi API để in từng item

Đây là flow phổ biến nhất: hệ thống tích hợp lấy dữ liệu từ nguồn nghiệp vụ của họ, map dữ liệu đó thành values, rồi gọi profile print endpoint.

Mỗi request là một job in độc lập. Với batch/Excel, nên queue tuần tự để dễ trace lỗi tem hoặc lỗi RFID.

Ví dụ dưới đây minh họa cách lấy dữ liệu một item từ API nội bộ, sau đó apply vào các field của template.

const productId = "ITEM-0002";

const product = await axios
  .get(`/api/products/${productId}/label-data`)
  .then((res) => res.data);

await axios.post(
  "http://localhost:9999/api/integration/profiles/product-label-rfid/print",
  {
    printerName: "GoDEX ZX1200i+",
    agentUrl: "http://127.0.0.1:17917",
    documentName: `${product.sku} ${product.lot}`,
    copies: 1,
    values: {
      product_name: product.product_name,
      qr_code: product.qr_code,
      unit: product.unit,
      lot: product.lot,
      expired_date: product.expired_date,
      rfid_id: product.rfid_id
    }
  }
);

API reference

Profile endpoints là API chính cho sản phẩm thương mại. One-shot endpoints dùng cho debug, kiểm thử hoặc hệ thống muốn gửi nguyên template trong từng request.

Nhóm	Endpoints
Profile	List, publish, get, delete, compile, print bằng profileId.
One-shot	schema, compile, print với template + values trong body.
Print agent	health, printers, raw print ở 127.0.0.1:17917.

GET    /api/integration/profiles
POST   /api/integration/profiles
GET    /api/integration/profiles/{profileId}
DELETE /api/integration/profiles/{profileId}
POST   /api/integration/profiles/{profileId}/compile
POST   /api/integration/profiles/{profileId}/print

POST /api/integration/schema
POST /api/integration/compile
POST /api/integration/print
POST /print

GET  http://127.0.0.1:17917/health
GET  http://127.0.0.1:17917/printers
POST http://127.0.0.1:17917/print

RFID và kiểm tra dữ liệu

Field encode EPC thường là {rfid_id}.
Hex EPC nên chỉ chứa 0-9 và A-F.
Độ dài hex nên là bội của 4 ký tự vì EZPL ghi theo RFID word 16-bit.
EPC-96 thường là 24 ký tự hex; EPC-128 thường là 32 ký tự hex.
UI Data Feed có highlight/validate column RFID, nhưng production nên validate trong hệ thống khách hàng trước khi gọi print.

Checklist bàn giao

Driver GoDEX/Seagull đã cài và thấy printer trong /printers.
Next.js app chạy đúng port khách hàng gọi.
Python print agent chạy tại 127.0.0.1:17917.
Template đã publish thành API profile và profileId được document.
Field contract đã gửi cho khách hàng: tên field, kiểu dữ liệu, field nào bắt buộc.
Đã test một job đơn và một batch đại diện.
Nếu RFID bật, đã test EPC thực tế, write power, write position và retry policy.

Tích hợp in nhãn GoDEX bằng template profile