UPS ZPL etiketi: iste, önizle, düzelt

Yayın tarihi: 2026-09-14

UPS Shipping API, istek öyle diyorsa termal etiketi paket başına bir tane base64 ZPL olarak döndürür. FedEx'e kıyasla istek daha küçüktür — bir görüntü biçim kodu ve bir stok boyutu — ve çözünürlük alanı hiç yoktur; bu da önemli bir soruyu (noktalar hangi yoğunluk için yazıldı?) istekten dosyaya taşır. Bu sayfa alanları, yanıttaki etiket yolunu ve basmadan önce koşturulacak denetimleri listeler. Her kargo etiketi için geçerli kurallar kargo ZPL etiketleriyle çalışmak yazısında; FedEx karşılığı FedEx ZPL etiketi.

Aşağıdaki alan adları ve değerler, UPS'in GitHub'da yayımladığı Shipping API OpenAPI belirtiminden 2026-09-14'te okundu. API sürümleri arasında değişirler; güvenmeden önce güncel belirtimle doğrulayın. Labelixa'nın UPS ile bir bağı yoktur — bu bir iş akışı anlatımıdır, entegrasyon değil.

ZPL'i biçimlendiren istek alanları

Çağrı POST /shipments/{version}/ship — Customer Integration Environment için wwwcie.ups.com, üretim için onlinetools.ups.com. Etiketi ShipmentRequest.Shipment.LabelSpecification yönetir:

• LabelImageFormat.Code — ZPL. Belirtim GIF, ZPL, EPL (EPL2 için) ve SPL sayar; iade etiketi basma servisli gönderilerin aynı dördü kabul ettiğini, UPS Premier Silver gönderilerinin ise yalnız ZPL desteklediğini not eder.
• LabelStockSize.Height ve Width — tam inç, termal biçimlerde zorunlu. Genişlik 4; yükseklik 6 ya da 8. Belirtim iki kez okunmaya değer bir not ekler: etiket görüntüsü 4×8 istense bile en fazla 4×6'ya ölçeklenir.
• CharacterSet — etikette beklenen dil karakter kümesi, üç harfli kod olarak: eng (Latin-1, varsayılan), deu ve fra (Latin-1), tur (Latin-5), pol (Latin-2), rus (Kiril) ve diğerleri. Geri gelen baytları değiştirir; aşağıda önemi var.
• HTTPUserAgent — yalnız GIF çıktısı için anlamlı; ZPL'de yok sayın.

"LabelSpecification": {
  "LabelImageFormat": { "Code": "ZPL" },
  "LabelStockSize": { "Height": "6", "Width": "4" }
}

Çözünürlük alanı yoktur. Belirtim ZPL'in hangi yoğunluk için yazıldığını söylemez; o yüzden varsaymayın, dosyadan okuyun (aşağıda).

Etiket yanıtın neresinde

Yol ShipmentResponse.ShipmentResults.PackageResults[] — paket başına bir giriş; her birinde TrackingNumber ve GraphicImage'ı base64 etiket, ImageFormat.Code'u gerçekten dönen biçimi doğrulayan bir ShippingLabel nesnesi. Belirtim, v2403 sürümünden itibaren paket sonuçlarının her zaman dizi olduğunu, eski sürümlerin ise tek pakette çıplak nesne döndürdüğünü not eder — "tek koliyle çalışıyor, ikiyle bozuluyor"un klasik sebebi.

jq -r '.ShipmentResponse.ShipmentResults.PackageResults[0].ShippingLabel.GraphicImage'    response.json | base64 -d > label.zpl
head -c 40 label.zpl          # ^XA beklenir

Termal çıktı için iki alan daha önemli. InternationalSignatureGraphicImage ABD dışı gönderilerde EPL2, ZPL ve SPL için döner — gönderi başına bir görüntü, ilk paket sonucunda — ve yok sayılacak bir ek değil, basılacak ikinci bir etikettir. HTMLImage yalnız GIF ve PNG'de döner; ZPL'de yokluğu normaldir. Belirtim ayrıca çok parçalı COD gönderilerinde ilk paketin etiketinin, ne istenmiş olursa olsun her zaman GIF olduğunu not eder — varsaymak yerine paket başına ImageFormat.Code okuyun.

Önce yoğunluğu bulun, sonra önizleyin

İstek çözünürlük taşımadığı için tek güvenilir kaynak dosyadır. Boyut ve DPI analizi bildirilen genişlik ve uzunluğu ZPL'den okur ve onları 4×6 (ya da 4×8) etikete oturtan yoğunluğu bildirir; dosya bildirmiyorsa tahmin etmek yerine bunu söyler. Sonra o yoğunluk ve stokta önizleyin:

curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/0"      --data-binary @label.zpl --output label.png

Çözülen baytları olduğu gibi tutun. Varsayılan dışında bir karakter kümesi istediyseniz etiket baytları o kodlamayı izler; dosyayı UTF-8 olarak çözüp yeniden kodlamak her aksanlı ya da Türkçe karakteri değiştirebilir ya da reddedebilir, önizleme de tam o hasarı gösterir. Ham baytları önizlemeye ve değiştirmeden yazıcıya verin.

Basmadan önce koşturulmaya değer denetimler

• Paket başına bir etiket, hepsi. Her paket sonucunun üzerinden geçin; tek kolili test döngüyü sınamaz.
• Biçim istediğiniz biçim. ImageFormat.Code okuyun; ZPL kuyruğuna sızan bir GIF yazıcıya çöp bastırır ya da hiçbir şey bastırmaz.
• Uluslararası imza görüntüsü de basıldı, varsa.
• "error" düzeyinde bulgu yok. Çözülen her dosyada tanılama; yalnız temizse kuyruğa.
• Hiçbir şey düzenlenmedi. Takip barkodu, yönlendirme bloğu ve servis işaretleri üretildiği gibi kalır; kendi veriniz ayrı etikete.

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

Aynı kapı kabuktan ya da CI'dan npx labelixa validate label.zpl olarak koşar; "error" düzeyinde bulguda sıfırdan farklı kodla çıkar.

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

• 4×8 istendi, yerleşim 4×6. Beklenen davranış: belirtim görüntünün en fazla 4×6'ya ölçeklendiğini söyler. Dosyayı gerçekten yüklediğiniz uzunlukta önizleyin.
• Etiket küçük basılıyor ya da taşıyor. Dosya ile yazıcı arasında yoğunluk uyumsuzluğu; analiz dosyanın yoğunluğunu söyler, düzeltilecek olan yazıcıdır, dosya değil.
• Umlaut ya da Türkçe harfler soru işareti çıkıyor. Baytlar yolda yeniden kodlandı ya da etiket varsayılan karakter kümesiyle istendi. İstekteki CharacterSet alanını kontrol edin ve yükü ikili tutun.
• Tek koliyle çalışıyor, ikiyle bozuluyor. Paket sonuçları diziye döndü. İki biçimi de ele alın ya da v2403 ve üstü bir sürüme geçin.
• Yalnız ilk kolinin etiketi farklı görünüyor. Çok parçalı COD: ilk etiket tasarım gereği GIF. Onu termal kuyruk yerine görüntü yoluna yönlendirin.

Sık sorulan sorular

UPS Shipping API'den ZPL etiketi nasıl istenir?

LabelSpecification.LabelImageFormat.Code alanını ZPL yapın ve LabelStockSize'ı tam inç olarak Width 4, Height 6 (ya da 8) verin. Belirtim, 4×8 istense bile görüntünün en fazla 4×6'ya ölçeklendiğini not eder.

ZPL, UPS yanıtının neresinde?

ShipmentResponse.ShipmentResults.PackageResults[].ShippingLabel.GraphicImage içinde, base64 kodlu, paket başına bir giriş; ImageFormat.Code biçimi doğrular. v2403'ten itibaren paket sonuçları her zaman dizidir.

UPS isteği ZPL'in hangi dpi için yazıldığını söyler mi?

Hayır — belirtimde çözünürlük alanı yok. Yoğunluğu boyut ve DPI analiziyle dosyadan okuyun, sonra o yoğunlukta önizleyin ve basın.

İlgili yazılar

Kendi ZPL kodunuzu deneyin →