Trendyol Kargo Etiketi API: Ortak Etiket ve Takip Numarası

İki adımlı etiket akışı

Adım	İstek	Gövde ve yanıt
1. Barkod talebi	POST /integration/sellers/{sellerId}/common-label/{cargoTrackingNumber}	Gövde: format: ZPL (zorunlu), boxQuantity, volumetricHeight. Yanıt: 200, gövde yok
2. Etiketi alma	GET /integration/sellers/{sellerId}/common-label/{cargoTrackingNumber}	Yanıt: data dizisi; her elemanda label (^XA ... ^XZ) ve format: ZPL

Çok koli gönderiyorsanız boxQuantity alanına koli sayısını yazın. Çoklu kolide her koli için ayrı etiket döner; tek kolide tek ZPL gelir. İki servisin limiti de dakikada 100 istektir.

Kimler ortak etiket kullanır?

Ortak etiket yalnız TEX (Trendyol Express) ve Aras Kargo ile, kargo bedelini Trendyol'un ödediği gönderilerde kullanılır. Diğer kargo firmalarında ya da satıcının kendi anlaşmasıyla gönderdiği paketlerde etiket ilgili kargo firmasından alınır.

Sipariş akışında sıra şöyledir: paket Picking (ve isteğe bağlı Invoiced) statüsüne alınır, kargo firması TEX ya da Aras ise ortak etiket istenir, etiket alınır ve gönderim mevcut shipmentPackageId ile cargoTrackingNumber kullanılarak yapılır.

Mikro ihracat ve Trendyol Yurt Dışı Aracılığı paketlerinde fatura kontrolü Invoiced statüsüne geçmeden kargo etiketi entegrasyon servisinden dönmez. Önce fatura gönderimini tamamlayın.

ZPL etiketini yazdırmak

ZPL, termal etiket yazıcılarının doğrudan anladığı bir komut dilidir. ZPL destekleyen bir yazıcınız varsa label alanındaki metni yazıcıya olduğu gibi gönderebilirsiniz. Ofis yazıcısında basmak için ZPL'i önce PDF ya da görüntüye çevirmeniz gerekir.

Yanıttaki etiketi kaydetmeden önce metnin ^XA ile başlayıp ^XZ ile bittiğini kontrol edin. Boş yanıt, talebin henüz işlenmediğini gösterebilir; kısa bir süre bekleyip GET isteğini tekrarlayın. Aynı paket için tekrar talep göndermek yerine önce mevcut etiketi çekmeyi deneyin.

Kargo takip numarası

Her paketin takip numarası sipariş paketindeki cargoTrackingNumber alanında gelir; satıcı panelinde CODE128 barkod olarak basılır. Takip bağlantısı cargoTrackingLink alanındadır. Aras Kargo satıcı öder modelinde takip kodu bildirme servisi Mayıs 2025'te kapatıldı; paketler bu cargoTrackingNumber ile kargoya teslim edilir.

Kendi kargo linkinizle ya da kurye ile gönderim yapıyorsanız alternatif teslimat servisleri kullanılır:

PUT .../shipment-packages/{packageId}/alternative-delivery: isPhoneNumber, trackingInfo (takip linki ya da telefon), params (boş), isteğe bağlı boxQuantity ve deci. Başarılı istekten sonra paket otomatik Shipped olur.
PUT .../manual-deliver/{cargoTrackingNumber} ya da .../shipment-packages/{packageId}/manual-deliver: teslim bildirimi. Müşteri onaylayınca ya da 3 iş günü içinde dönüş yapmazsa paket Delivered olur.
manual-return servisleri: Shipped olup teslim edilemeyen ve depoya dönen paketler için.
Dijital ürünlerde params içinde 6-120 karakterlik digitalCode gönderilir; kod müşteriye SMS ve e-postayla iletilir.

Sık hatalar

Belirti	Neden	Çözüm
400	cargoTrackingNumber yanlış	Takip numarasını paketin güncel hâlinden alın
401	API bilgileri hatalı	Kimlik bilgilerini kontrol edin
Etiket boş dönüyor	Talep işlenmedi ya da paket ortak etiket kapsamında değil	Bir süre bekleyip tekrar deneyin; kargo firmasının TEX ya da Aras, ödeyenin Trendyol olduğunu doğrulayın
digital.good.business.unit.not.valid	Dijital ürün olmayan pakete dijital kod gönderildi	businessUnit alanı Digital Goods olan paketlerde kullanın

Sık sorulanlar

Trendyol kargo etiketini API ile nasıl alırım?

TEX ve Aras Kargo Trendyol öder gönderilerinde önce createCommonLabel ile barkod talep edin, sonra getCommonLabel ile oluşan ZPL etiketi alın. Diğer firmalarda etiket kargo firmasından alınır.

Ortak etiket PDF olarak alınabilir mi?

Doküman şu an için yalnız ZPL biçiminin bulunduğunu söyler. PDF gerekiyorsa ZPL metnini kendi tarafınızda çevirmeniz gerekir.

Etiket talebini ne zaman yapmalıyım?

Paketi Picking ya da Invoiced statüsüne aldıktan sonra yapmanız önerilir.

Kendi kargo linkimle gönderim yapabilir miyim?

Evet. Alternatif teslimat servisine takip linkini trackingInfo alanında gönderin. İstek başarılı olunca paket otomatik olarak Shipped statüsüne geçer.

Kaynaklar

İlgili Trendyol API konuları

Trendyol paket statüsü güncelleme: Picking ve Invoiced (updatePackage)Paket PUT .../shipment-packages/{packageId} ile önce Picking, sonra isteğe bağlı Invoiced statüsüne alınır. Gövdede lineId, quantity ve status gönderilir.Trendyol kargo firmaları ve kargo sağlayıcı kodlarıKargo sağlayıcı kodları GET /integration/product/lookup/cargo-providers ile alınır. Bu kodlar ürüne barkod bazlı kargo atamada ve paket kargosunu değiştirmede kullanılır.Trendyol paket kargo firması değiştirme, desi-koli ve ek tedarik süresiPaketin kargo firması PUT .../cargo-providers ile değişir; bir paket için 5 dakikada bir kez yapılabilir. Desi-koli ve ek tedarik süresi ayrı servislerdir.

Son güncelleme: 27.10.2026 · Trendyol API rehberinin tamamı

Trendyol kargo etiketi (ortak etiket) ve kargo takip numarası