Kargo ZPL etiketleriyle çalışmak

Yayın tarihi: 2026-08-27

FedEx ya da UPS'ten termal etiket istediğinizde geri gelen şey bir görüntü değil ZPL'dir; genelde bir JSON yanıtının içinde base64 kodlu olarak gelir. Bu iyi haber: metin, tek bir etiket yakılmadan incelenebilir, render edilebilir ve tanılanabilir. Aynı zamanda "etiket yanlış bastı" biletlerinin koca bir sınıfının yazıcıda değil entegrasyon katmanında çözülebileceği anlamına gelir.

Önce çözün, basmayın

Kargo yanıtındaki etiket alanı tipik olarak base64'tür. Çözdüğünüzde ^XA ile başlayan düz ZPL elinizdedir. Herhangi bir yere göndermeden önce dosyaya yazın — bir şey ters gittiğinde kanıtınız o dosyadır ve saklamak hiçbir şeye mal olmaz.

base64 -d label.b64 > label.zpl
head -c 200 label.zpl        # ^XA ile baslamali

Çözülen metin ^XA ile başlamıyorsa ya başka bir biçim istediniz (PNG, PDF, EPL) ya da okuduğunuz alan etiket yükü değil. İstek alan adlarını kargonun GÜNCEL API referansından doğrulayın — FedEx ile UPS'te farklıdır ve API sürümleri arasında değişir; bir blog yazısından kopyalanan değer, boşa giden saatlerin yaygın sebebidir.

Neyi değiştirmemelisiniz

Kargo etiketi bir uyum belgesidir. Barkod içeriği, yönlendirme bloğu ve servis işaretleri kargo tarafından üretilir ve yazıcıya DEĞİŞTİRİLMEDEN ulaşmalıdır: takip barkodunu ya da yönlendirme kodunu kurcalamak koliyi kargonun ağında okunamaz hâle getirebilir ve bu arıza testlerinizde değil, günler sonra bir aktarma merkezinde ortaya çıkar.

Kendi bilginizi eklemek ayrı bir konudur. Kargonun formatını düzenlemek yerine ayrı bir etiket basın — dahili SSCC, toplama kodu, depo lokasyonu. Her biri geçerli kalan iki etiket, kimsenin sorumluluğunu üstlenmeyeceği tek etiketten iyidir.

Çözünürlük tuzağı

Kargo etiketleri neredeyse her zaman 4×6 inçtir ve ZPL belirli bir yoğunluk için nokta cinsinden yazılmıştır. 203 dpi için üretilmiş bir etiketi 300 dpi yazıcıya gönderirseniz yaklaşık üçte iki ölçekte, geniş boşlukla basar; tersi taşar ve kırpılır. Dosyada "yanlış" bir şey yoktur — noktalar iki kafada farklı fiziksel mesafeler demektir, o kadar.

Yazıcıyı suçlamadan önce etiketin hangi yoğunluğu varsaydığını doğrulayın: boyut ve DPI analizi bildirilen ölçüleri dosyadan okur ve onları standart bir etiket ölçüsüne oturtan yoğunluğu bildirir; kestiremiyorsa bunu açıkça söyler.

Kendini amorti eden bir doğrulama kapısı

Etiket metin olduğu için onu, aldığınız kod yolunda denetleyebilirsiniz. En küçük kapı şöyledir: etiketi iste, çöz, tanılamayı koştur ve yalnızca hata yoksa baskı kuyruğuna al. Şiddeti "error" olan bulgular etiketin istendiği gibi render edilmeyeceği anlamına gelir; uyarılar devam etseniz bile kayda değer.

curl -X POST "https://api.labelixa.com/v1/diagnostics?dpmm=8&w=4&h=6"      --data-binary @label.zpl

Aynı denetim CI ya da sevkiyat işçisi için komut satırı adımı olarak da var (npx labelixa validate label.zpl etiket hata taşıyorsa sıfırdan farklı kodla çıkar) ve tek bir koliyi incelerken tarayıcıya yapıştırmak için ZPL önizleyici olarak.

Kargo sorunu gibi görünen ama olmayan arızalar

• Her gönderiden sonra fazladan boş etiket. Genelde etiket uzunluğunun medyayla uyuşmaması ya da sızmış bir kopya adedi — mekanizması fazladan boş etiket yazısında.
• Etiketin altı eksik. Medya, etiketin bildirdiğinden dar ya da kısa; bkz. etiket kırpılıyor.
• Her şey dönük basıyor. Baskı yönü yazıcının içinde uygulanır; önizleme dik görünürken kâğıt öyle olmaz — ters basılıyor yazısı üç anahtarı anlatır.

Bunların hiçbiri kargonun destek masasını gerektirmez. Üçü de dosyada görünür; zaten basmadan önce çözmenin iki satır fazladan koda değmesinin sebebi tam olarak budur.

İlgili yazılar

Kendi ZPL kodunuzu deneyin →