Barcode GS1-128 presisi 0,1 mm dari JSON

Jika Anda mengirim barang fisik, pada akhirnya Anda harus mencetak GS1-128 yang bisa dibaca scanner gudang sungguhan. Ini terlihat seperti detail kecil, tetapi dalam PDF generation sering menjadi sumber kegagalan paling mahal.

Artikel ini menjelaskan arti “presisi 0,1 mm” untuk GS1-128, mengapa renderer berbasis HTML/CSS sulit menjaganya, dan aturan praktis agar barcode lolos scanner DHL, FedEx, USPS, maupun inbound Amazon.

Arti presisi barcode

GS1-128 (dulu UCC/EAN-128) mengodekan data lewat lebar bar dan gap dengan rasio ketat. Unit dasarnya adalah X-dimension, yaitu lebar bar atau gap paling sempit. Lebar lain adalah kelipatan X.

Scanner mengukur rasio lebar, bukan sekadar melihat gambar. Dua kegagalan paling umum:

1. X-dimension tidak konsisten dalam satu simbol: renderer melakukan sub-pixel rounding berbeda untuk bar yang berdekatan.
2. Panjang total atau scaling salah: simbol dirender lalu diskalakan, sehingga X-dimension turun di bawah minimum GS1, biasanya 0,495 mm pada 1,0×.

Satu sampel bisa terbaca, tetapi batch produksi punya rejection 1 dari 30. Scanner dev biasanya lebih toleran daripada scanner gudang.

Aturan 0,1 mm

Presisi yang relevan adalah panjang total barcode berada dalam toleransi 0,1 mm dari target spesifikasi. Bukan berarti setiap bar lebarnya 0,1 mm; biasanya 0,495 mm atau lebih.

Untuk GS1-128 tipikal berisi 18 digit:

• Simbol berisi sekitar 120 bar dan gap
• Panjang total pada 1,0× sekitar 58 mm
• Toleransi 0,1 mm berarti akurasi total ~0,17%
• Budget per bar sekitar 0,001 mm

Karena itu, bar yang seharusnya 7,4 px tetapi menjadi 7 px bisa merusak hasil. Error sub-pixel menumpuk sepanjang simbol.

Mengapa HTML/CSS sulit

Rute umum adalah membuat SVG, memasukkannya ke HTML, lalu merender PDF lewat Puppeteer atau Prince. Tiap tahap bisa menggeser geometri.

1. Browser melakukan rounding saat rasterisation

SVG di dalam HTML tetap melewati painter browser. Output stabil butuh shape-rendering="crispEdges", batas pixel integer, dan hubungan DPI-ke-bar-width yang rapi.

2. CSS bisa mengubah skala diam-diam

transform: scale(0.95) yang dulu dipakai untuk memperbaiki layout lain akan mendistorsi semua barcode. PDF terlihat benar; scanner membaca geometri yang salah.

3. PDF emitter punya quantization sendiri

Saat browser menulis PDF, beberapa engine mengunci koordinat ke grid internal. Hasilnya hampir benar, tetapi error terkumpul.

4. Font Code 128 lebih berisiko

Font memang vector, tetapi hinting menggeser lebar agar enak dilihat manusia pada ukuran kecil. Itu bertentangan dengan kebutuhan scanner.

Pendekatan structured rendering

gPdf menghitung pola bar/gap dari spesifikasi GS1-128 dan langsung menulis PDF vector primitives: tanpa HTML, tanpa translasi SVG, tanpa font hinting.

{
  "pages": [{
    "size": "label_100_150",
    "elements": [
      {
        "type": "barcode",
        "format": "gs1128",
        "content": "(00)123456789012345678",
        "x": 4,
        "y": 8,
        "width": 58.0,
        "height": 18.0,
        "barcode_text": { "enabled": true, "position": "bottom" }
      }
    ]
  }]
}

Pada elemen barcode, width adalah panjang total simbol dalam mm, nilai yang bisa diukur dengan kaliper pada label cetak. Dengan width: 58.0:

• Renderer menghitung X-dimension dari panjang target dan jumlah bar.
• Setiap bar digambar dengan X-dimension yang sama.
• Lebar ditulis ke PDF sebagai koordinat floating-point.
• Tidak ada CSS pixel rounding, layout scaling, atau font hinting.

Selama printer tidak menambahkan scaling sendiri, panjang total tetap dalam 0,1 mm dari target.

Apa yang perlu dicetak

Aturan 1: tentukan panjang total

width adalah kontrol yang tepat karena bisa diukur. Jika hanya X-dimension yang ditentukan, panjang simbol berubah mengikuti data yang dikodekan.

• Shipping label 4×6 in: lebar 100 mm; GS1-128 biasanya ~58–72 mm
• Compliance label 4×4 in: ~45–58 mm
• Carton label 2×1 in (Amazon UPC): bukan GS1-128; gunakan UPC-A

Aturan 2: quiet zone selalu ada

GS1-128 membutuhkan quiet zone ≥ 10X di kedua sisi. Pada 1,0× (X = 0,495 mm), itu minimal 4,95 mm ruang putih. Menaruh barcode di x: 0 sering membuat scanner gagal menemukan tepi awal. gPdf mencadangkan area ini otomatis.

Aturan 3: uji di scanner target

Kamera ponsel lebih toleran daripada Honeywell atau Zebra industri. Cetak 50 label di printer produksi, pada kecepatan produksi, lalu scan dengan perangkat asli. Read rate di bawah 99% biasanya berarti ada masalah X-dimension.

Realitas multi-format

Label jarang hanya memakai GS1-128:

Symbol	Kegunaan	Sumber spesifikasi
GS1-128	Unit logistik, GTIN + serial + lot	GS1 General Specifications
QR with FNC1	Ecommerce yang bisa dipindai mobile	ISO/IEC 18004
Data Matrix	Farmasi (DSCSA / EU FMD)	ISO/IEC 16022
PDF417	SIM, boarding pass	ISO/IEC 15438
Aztec	Tiket transportasi	ISO/IEC 24778
MaxiCode	Khusus UPS	ISO/IEC 16023

Renderer yang hanya menangani GS1-128 akhirnya memaksa workflow memakai alat kedua. Logistics hampir selalu butuh lebih dari satu format.

Menangani scanner rejection di produksi

1. Ambil label yang gagal, bukan hanya metrik agregat.
2. Ukur dengan kaliper panjang total dan X-dimension.
3. Periksa teks human-readable di bawah barcode.
4. Verifikasi quiet zone di kedua sisi.
5. Coba model scanner lain.
6. Bandingkan dengan label referensi yang sudah benar.

TL;DR

Presisi GS1-128 bukan soal mencetak bar setipis mungkin; ini soal menjaga X-dimension konsisten di seluruh simbol. HTML/CSS menambah sub-pixel drift di beberapa tahap. Structured renderer yang menulis PDF vector primitives langsung menghindari sumber drift tersebut.

Jika stack PDF Anda punya 1–5% scanner rejection, mulai dari sini. Playground dapat merender GS1-128 dengan width sesuai spesifikasi label; cetak dan ukur dengan kaliper.