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

Yayın tarihi: 2026-09-14

FedEx Ship API'den termal etiket istediğinizde geri gelen şey, gönderi yanıtının JSON'u içinde base64 kodlu ZPL'dir. Hangi ZPL'in geleceğini — etiket boyutu, doc-tab (belge sekmesi) olup olmadığı ve hepsinden önemlisi noktaların hangi baskı yoğunluğu için yazıldığı — bir avuç istek alanı belirler. Bu sayfa o alanları listeler, etiketin yanıtta nerede durduğunu gösterir ve dosya yazıcıya ulaşmadan önce koşturulmaya değer denetimleri sırayla anlatır. Her kargo etiketi için geçerli kurallar (düzenlemeyin, kendi verinizi ayrı basın) kargo ZPL etiketleriyle çalışmak yazısında; bu sayfa onun üstündeki FedEx'e özgü katmandır. UPS karşılığı: UPS ZPL etiketi.

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

ZPL'i biçimlendiren istek alanları

Önemli olan her şey POST /ship/v1/shipments çağrısındaki istenen gönderinin labelSpecification nesnesinde durur:

• imageType — Zebra veri akışı için ZPLII. Diğer değerler EPL2, PDF ve PNG; yalnız ilk ikisi termal biçimdir.
• labelFormatType — COMMON2D tam bir etiket döndürür. LABEL_DATA_ONLY kendiniz çizeceğiniz bir etiket için barkod verisi döndürür; ayrı bir iş akışıdır.
• labelStockType — düz 4×6 inç stok için STOCK_4X6. Doc-tab'lı türevler (STOCK_4X675_LEADING_DOC_TAB, STOCK_4X675_TRAILING_DOC_TAB, STOCK_4X9_LEADING_DOC_TAB, STOCK_4X9_TRAILING_DOC_TAB, STOCK_4X85_TRAILING_DOC_TAB, STOCK_4X105_TRAILING_DOC_TAB) ve uzun düz stoklar (STOCK_4X8, STOCK_4X9) fiziksel olarak 6 inçten uzundur — geri gelen etiket o uzunluk için yazılmıştır.
• resolution — 203 ya da 300. Referans, varsayılanın 203 olduğunu ve 300'e yalnız ZPLII ile izin verildiğini söyler. Dosyadaki her koordinatın nasıl okunacağını bu tek alan belirler.
• İsteğe bağlı: labelRotation (NONE, LEFT, RIGHT, UPSIDE_DOWN) ve labelPrintingOrientation (TOP_EDGE_OF_TEXT_FIRST, BOTTOM_EDGE_OF_TEXT_FIRST) rulo stoklu termal çıktıya uygulanır; labelOrder birden çok belge üretildiğinde sevkiyat etiketini başa ya da sona koyar.

"labelSpecification": {
  "labelFormatType": "COMMON2D",
  "imageType": "ZPLII",
  "labelStockType": "STOCK_4X6",
  "resolution": 203
}

Etiket yanıtın neresinde

Etiket en üst düzeyde değildir. Yol output.transactionShipments[].pieceResponses[].packageDocuments[]: paket başına bir parça yanıtı, içinde bir ya da daha çok paket belgesi; her biri docType, contentType, trackingNumber ve copiesToPrint yanında encodedLabel (base64 yük) taşır. Belgeye bir url alanı eşlik edebilir; encodedLabel'ı kendiniz çözmek ZPL'i sizin denetiminizde tutar.

jq -r '.output.transactionShipments[0].pieceResponses[0].packageDocuments[0].encodedLabel'    response.json | base64 -d > label.zpl
grep -c '\^XA' label.zpl     # tampondaki etiket formati sayisi

Formatları sayın. Referans, bir gönderi için gereken bütün etiketlerin tek bir tamponda üretilip döndürüldüğünü not eder; yani çözülen tek bir belge birden çok ^XA … ^XZ bloğu içerebilir — örneğin sevkiyat etiketinin ardından bir servis etiketi. Yazıcı hepsini basar; önizleme ucu indeks başına bir format döndürür, indeks verilmezse hepsini tek PDF olarak.

İstediğiniz yoğunlukta önizleyin

ZPL'de çözünürlük başlığı yoktur: dosyadaki noktalar yazıcının kendi yoğunluğuyla okunur. resolution: 300 ile istenen bir dosya 8 nokta/mm'de önizlendiğinde yaklaşık bir buçuk kat büyük görünür ve etiketten taşar; aynı dosya 12 nokta/mm'de doğrudur. Önizlemeyi isteğe eşleyin — 203 için 8dpmm, 300 için 12dpmm — ve istediğiniz stok uzunluğunu verin (6, 6.75, 8, 9 …).

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

Saklanan bir dosyanın hangi çözünürlük için üretildiğini artık bilmiyorsanız boyut ve DPI analizi bildirilen genişlik ve uzunluğu dosyadan okur ve onları standart bir etiket ölçüsüne oturtan yoğunluğu bildirir — ya da kestiremediğini söyler.

Basmadan önce koşturulmaya değer denetimler

• Yoğunluk yazıcıyla eşleşiyor. Referans, FedEx 1D barkoduna 203 dpi'da 3 nokta, 300 dpi'da 4 nokta X boyutu verir. 203 dpi için üretilmiş dosyayı 300 dpi kafaya gönderirseniz o 3 noktalık çubuklar amaçlanan genişliğin üçte ikisine iner — etiket kol boyu mesafeden iyi görünür, tarayıcıda düşer.
• Stok medyayla eşleşiyor. Doc-tab'lı stok 6,75 inç ya da daha uzundur; düz 6 inçlik medyada sekme sonraki etikete taşar ya da kesilir. İstenen uzunlukta önizleyin ve gerçekten yüklediğiniz medyayla karşılaştırın.
• "error" düzeyinde bulgu yok. Dosyayı tanılamadan geçirin ve yalnız hata yoksa kuyruğa alın; uyarılar kayda değer.
• Hiçbir şey düzenlenmedi. Takip barkodu, yönlendirme bloğu ve servis işaretleri yazıcıya üretildiği gibi ulaşmalı. Kendi verinizi FedEx'in formatını düzenleyerek değil, ayrı bir etiket olarak ekleyin.

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. Referans ayrıca FedEx'in API için önerdiği termal yazıcıları sayar — ZPL modelleri arasında GK420, ZT410 ve diğer ZT4xx serisi — depo filosu karışıkken yararlı bir akıl kontrolü.

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

• Etiket üçte iki boyutta, geniş kenar boşluğuyla basılıyor. Dosya 203 dpi için üretildi ve 300 dpi kafada basıldı (ya da tersi: taşar ve kırpılır). İsteğin resolution alanını ya da yazıcıyı düzeltin, dosyayı değil.
• Her gönderiden sonra fazladan, çoğu boş bir etiket. Doc-tab'lı ya da 8/9 inçlik stok istendi ve medya 6 inç; ya da tampon beklemediğiniz ikinci bir format içeriyordu. Yukarıdaki format sayısı hangisi olduğunu söyler.
• Çıktı dönük. Kâğıdı önizlemeyle karşılaştırın. Önizleme de dönükse isteğin labelRotation ya da yön alanı yaptı; yalnız kâğıt dönükse sebep yazıcının kendi yön ayarıdır — bkz. etiket ters basılıyor.
• Yalnız sevkiyat etiketi basıldı. Çok paketli gönderiler paket başına bir parça yanıtı döndürür; hepsinin ve her birinin içindeki her paket belgesinin üzerinden geçin.

Sık sorulan sorular

ZPL'in yoğunluğunu hangi FedEx istek alanı belirler?

labelSpecification.resolution — 203 ya da 300. Referans varsayılanı 203 verir ve 300'e yalnız imageType ZPLII ile izin verir. 203 için 8 nokta/mm, 300 için 12 nokta/mm'de önizleyin.

ZPL, FedEx gönderi yanıtının neresinde?

output.transactionShipments[].pieceResponses[].packageDocuments[].encodedLabel içinde, base64 kodlu, paket başına bir parça yanıtı. Çözülen tek belge birden çok ^XA…^XZ formatı içerebilir; bir gönderinin bütün etiketleri tek tamponda döner.

FedEx etiketi neden üçte iki boyutta basılıyor?

Dosya 203 dpi için üretildi ve 300 dpi kafada basıldı (ya da yanlış yoğunlukta önizlendi). İstekteki resolution alanını değiştirin ya da eşleşen yazıcı kullanın; dosyayı düzenlemeyin.

İlgili yazılar

Kendi ZPL kodunuzu deneyin →