UPS entegrasyonu:
kendi sözleşmenizle, siparişten etikete.

UPS entegrasyonu nedir, hangi satıcının işine yarar?

UPS entegrasyonu, siparişteki alıcı, adres ve paket bilgisini UPS ekranına yeniden yazmadan gönderi açmanızı sağlar; UPS'in döndürdüğü takip numarası ve etiket siparişin üzerinde durur. United Parcel Service (UPS) dünya genelinde paket taşıyan bir ekspres kargo firmasıdır ve Türkiye'den yurt dışına gönderi kabul eder. Entegrasyonun asıl kazancı yurt dışı siparişte görülür: adres düzeni ve telefon biçimi ülkeye göre değişir, elle girişte hatalar en çok bu alanlarda yapılır.

Yurt dışına satan satıcı için ne değişir?

Etsy'de atölye ürünü, eBay'de yedek parça ya da kendi sitenizden Avrupa'ya giyim satıyorsanız her sipariş aynı döngüden geçer: adresi kopyala, gönderi aç, etiketi indir, takip numarasını kanala yaz. Entegrasyonla kopyalama kısmı kalkar; siz paketi hazırlar, etiketi basar ve koliyi UPS'e teslim edersiniz.

Yalnız yurt içi pazaryerinde satan satıcı için UPS'in yeri

Yurt içi pazaryeri siparişlerinin çoğu kanalın anlaşmalı kargosuyla gider ve UPS bu listelerde genellikle yer almaz (ayrıntısı aşağıdaki pazaryeri bölümünde). Yalnız yurt içinde satıyorsanız UPS çoğu zaman birincil kargonuz olmaz; kendi siteniz ya da yurt dışı kanallarınız için ikinci bir kargo hesabı olarak anlamlıdır.

UPS kargo API'sine bağlanmak için hangi bilgiler gerekir?

UPS kargo API'sine bağlanmak için bir UPS.com kullanıcı profili, bu profile bağlı altı haneli bir UPS hesap numarası ve UPS Developer Portal'da oluşturulmuş bir uygulamanın Client Id ile Client Secret bilgileri gerekir. UPS'in güncel API'leri OAuth 2.0 ile çalışır: Client Id ve Client Secret karşılığında süreli bir erişim anahtarı (bearer token) alınır, gönderi ve takip istekleri bu anahtarla yapılır. Bu yöntem, entegrasyonu kuranın aynı zamanda UPS göndericisi olduğu durum içindir.

Şubeden verilen kullanıcı adı ve şifre ile Client Id aynı şey mi?

Bazı Türkçe rehberler şubeden alınan müşteri kodu, kullanıcı adı ve şifreyi anlatır; bu bilgiler farklı bir bağlantı yöntemine aittir ve Developer Portal'daki uygulama bilgilerinin yerine geçmez. Yox İş Ortağım sizden UPS.com parolanızı ya da şube şifrenizi istemez; yalnız Client Id ve Client Secret ister. Hangi hesap numarasının uygulamaya bağlanacağından emin değilseniz UPS müşteri temsilcinize sorun.

Hesap numarası ile kargo fiyatınız arasındaki bağ

Uygulamaya bağlanan hesap numarası, gönderi ücretinin hangi hesaba yazılacağını ve sözleşme fiyatınızın uygulanacağı hesabı belirler. Yox İş Ortağım kargo firması değildir, kargo bedeli almaz ve anlaşmalı fiyat vermez. Fiyat, hizmet ve teslim alma koşullarını doğrudan UPS ile konuşursunuz.

UPS Developer Portal'da uygulama oluşturma adım adım

UPS Developer Portal'da uygulama oluşturmak, UPS.com hesabınızla oturum açıp My Apps sayfasından yeni bir uygulama eklemek ve bu uygulamaya hesap numaranızı ile gerekli API ürünlerini bağlamaktan ibarettir. En kritik iki karar, hangi hesabın bağlanacağı ve hangi e-posta adresinin yazılacağıdır.

1. developer.ups.com adresinde UPS.com kullanıcı adınızla oturum açın.
2. My Apps sayfasında Add Apps düğmesine basın; kendi gönderileriniz için entegrasyon kuracağınızı belirten seçeneği işaretleyin.
3. Listeden uygulamaya bağlanacak gönderici hesabını seçin, UPS'in API erişim sözleşmesini okuyup onaylayın.
4. İletişim e-postası olarak ekibin ortak kullandığı bir adres yazın; UPS bu adresin sonradan değiştirilemediğini belirtiyor.
5. Uygulamaya ad verin; gönderi kaydı ve takip için Shipping ile Tracking ürünlerini ekleyin. Authorization (OAuth) ürünü kendiliğinden gelir.
6. Kaydedin; App Info bölümündeki Client Id ve Client Secret bilgilerini Yox İş Ortağım'ın Kargo bölümüne girip bağlantıyı test edin.

Test ortamı (CIE) ile canlı ortam arasındaki fark

UPS her API için iki adres yayımlar: Customer Integration Environment (CIE) adlı test adresi wwwcie.ups.com, canlı adres onlinetools.ups.com. UPS, CIE'nin yük testi için değil temel doğrulama için olduğunu belirtiyor. Gerçek koliler canlı adres üzerinden açılan gönderilerle yola çıkar; pilot kurulumda ilk canlı gönderiyi sizinle birlikte açıp etiketi ve takip numarasını birlikte kontrol ediyoruz.

Hangi UPS API ürünü ne işe yarar?

• Authorization (OAuth Client Credentials): Client Id ve Secret karşılığında erişim anahtarı verir.
• Shipping: gönderiyi oluşturur ve etiketi döndürür; aynı API'de gönderi iptali (Void) ve etiketi yeniden alma (Label Recovery) işlemleri de bulunur.
• Tracking: takip numarasıyla gönderinin hareketlerini ve teslim bilgisini döndürür.
• Paperless Documents: ticari fatura, menşe belgesi gibi gümrük belgelerini UPS'e dijital yüklemek için kullanılır.

UPS kargo API'sinde hizmet kodu, etiket biçimi ve paket ölçüsü

UPS'te bir gönderi açılırken hizmet türü, paketin ağırlığı ve ölçüsü ile etiket biçimi birlikte bildirilir; etiketin doğru çıkması bu üç bilginin sipariş hazırlanmadan önce netleşmesine bağlıdır. UPS'in Shipping API dokümanında uluslararası gönderide geçen başlıca hizmet kodları şunlardır:

Türkiye çıkışlı gönderinizde bu hizmetlerden hangilerinin açık olduğu varış ülkesine ve UPS sözleşmenize bağlıdır; listeyi kurulumdan önce UPS temsilcinizle teyit edin.

Etiket biçimi: görüntü mü, termal yazıcı dili mi?

UPS, gönderi etiketini GIF görüntüsü olarak ya da termal yazıcı dilleri ZPL, EPL ve SPL biçiminde döndürebilir; dokümandaki örneklerde etiket boyutu 4x6 inç (yaklaşık 10x15 cm) olarak geçer. UPS etiketi döndürdüğünde etiket panelden basılır; biçimi pilot kurulumda yazıcınıza göre birlikte belirliyoruz.

Ağırlık ve ölçü: hacim hesabını koliyi kapatmadan yapın

Gönderi isteğinde ağırlık kilogram (KGS) ya da libre, ölçüler santimetre ya da inç olarak gider; dokümana göre uzunluk paketin en uzun kenarıdır. UPS, faturalanacak ağırlıkta paket ölçülerini de dikkate alır ve API'de hacim ağırlığı için ayrı bir alan bulunur; hangi bölenin uygulandığı sözleşmenizde yazar. Koliyi kapatmadan önce desi hesaplama aracıyla hacim ağırlığını görmek, UPS faturasında beklenmedik farkla karşılaşmamanın en kolay yoludur.

Pazaryeri siparişini UPS ile göndermek: anlaşmalı kargo listeleri ve kendi sözleşmeniz

Bir pazaryeri siparişini UPS ile gönderip gönderemeyeceğiniz, pazaryerinin kendi kargo anlaşması dışında gönderime izin verip vermediğine bağlıdır; UPS entegrasyonu bu kuralı değiştirmez. Ekim 2026 itibarıyla kanalların resmî kaynaklarında gördüğümüz durum şöyle:

Kanallara özgü kurallar için Trendyol entegrasyonu, Etsy entegrasyonu ve Amazon entegrasyonu sayfalarına bakabilirsiniz. Bir siparişin UPS ile mi kanalın anlaşmalı kargosuyla mı gideceğine siz karar verirsiniz; birden çok kargo hesabı bağlıysa birincil kargoyu seçersiniz.

Kendi UPS sözleşmenizle göndermenin maliyet tarafı

Pazaryerinin anlaşmalı kargosunda ücret çoğunlukla hakedişinizden kesilir; kendi UPS sözleşmenizde ise fatura UPS'ten doğrudan size gelir. Bu fark fiyatlamayı etkiler: yurt dışı siparişte kargo bedelini ürün fiyatına ya da alıcıdan alınan kargo ücretine baştan yansıtın. Varış ülkesinde alıcıdan vergi istenip istenmeyeceğini ürün sayfanızda açıkça yazın; teslim edilemeyen paket riski azalır.

UPS ile mikro ihracat: basitleştirilmiş gümrük beyannamesi ve 2026 sınırları

UPS ile mikro ihracatta gümrük beyannamesini siz değil UPS verir: UPS, Hızlı İhracat (Express Export) hizmetinde dolaylı temsil yoluyla beyan yapmaya yetkili olduğunu belirtiyor. Sizin işiniz belgeleri hazırlamak ve beyanın doğru işlenmesini takip etmektir.

Eski adıyla ETGB, bugünkü adıyla BGB

Ticaret Bakanlığı'nın e-ihracat beyan kılavuzu, hızlı kargoyla yapılan ihracatta kullanılan belgeyi basitleştirilmiş gümrük beyannamesi (BGB) olarak adlandırır ve ETGB'yi mülga sayar; piyasada hâlâ ETGB denmesi bu yüzdendir. UPS'in Hızlı İhracat sayfasına göre hizmet için İhracat Bilgi Formu, finans onaylı Türkçe fatura ve beyanda kullanılmak üzere İngilizce ya da Almanca fatura istenir. Beyan belgeleri ihracatın ertesi iş günü göndericiye e-postayla iletilir.

2026'da değişen ağırlık ve değer sınırı

UPS'in Hızlı İhracat sayfası bu rehberi hazırlarken eski sınırları gösteriyordu. Sınıra yakın bir gönderiyi hazırlamadan önce güncel uygulamayı UPS'e sorun.

Gönderinin e-ihracat sayılması için kontrol edilecekler

• Beyan türü: BGB'deki beyan türü alanı e-ticaret satışında ET, değilse ETD olarak doldurulur. Desteklerden yararlanmak için ET gerekir; Bakanlık bunu hızlı kargo firmasına hatırlatmanızı istiyor.
• Vergi numarası: BGB ile yapılan ihracatta vergi numaranızın beyan edilmesi gerekir.
• KDV iadesi: UPS, beyan kopyasının vergi dairesine verilerek KDV iadesi istenebileceğini belirtiyor; şartları ve belge listesini mali müşavirinizle netleştirin.

Ticari fatura, Kağıtsız Fatura ve AB'ye giden paketlerde 2026 değişiklikleri

Ticari fatura, belge niteliğindeki gönderiler dışında bütün sınır ötesi UPS gönderilerinde gerekir; varış ülkesinin gümrüğü kıymeti ve vergiyi bu belgeye bakarak hesaplar. Ürün tanımı, adet ve değer siparişle birebir uyuşmalıdır; yalnız hediye gibi genel ifadeler gümrükte bekletme sebebi olabilir.

Kağıtsız Fatura mı, basılı kopya mı?

UPS Türkiye'nin uluslararası formlar sayfasına göre UPS hesabınızla Kağıtsız Fatura (Paperless Invoice) programını kullanıyorsanız fatura dijital iletilir; kullanmıyorsanız tek paketli gönderide faturanın üç kopyası basılıp pakete eklenir. UPS'in Shipping API'sinde ticari fatura, menşe belgesi ve CN22 gibi formlar gönderiyle birlikte üretilebilir, kendi hazırladığınız belgeler ise Paperless Documents API ile yüklenir. Hangi yöntemi kullanacağınızı ilk gönderiden önce UPS hesabınızda netleştirin.

AB'ye küçük paket gönderenler için 1 Temmuz ve 1 Kasım 2026

AB Konseyi'nin 11 Şubat 2026'da son onayı verdiği kurala göre 150 avronun altındaki küçük gönderilerdeki gümrük vergisi muafiyeti kaldırıldı: 1 Temmuz 2026'dan 1 Temmuz 2028'e kadar paketteki her ürün kategorisi için 3 avro sabit gümrük vergisi uygulanıyor. Aynı dönüşüm kapsamında UPS, 1 Kasım 2026'dan itibaren AB'ye giden 150 avro ve altındaki B2C gönderilerde her ürün için satıcı ürün kodu, üretici ürün kodu ve varsa barkod gibi standart bir ürün tanımlayıcısı istendiğini duyurdu.

Yox İş Ortağım'da UPS entegrasyonu: paketler ve pilot kurulum

UPS entegrasyonu Yox İş Ortağım'da Büyüme paketinden itibaren kullanılır; Başlangıç paketinde kargo entegrasyonu yoktur ve takip numarası elle girilir. Panelde 80 satış kanalı (48'i hazır), 57 kargo ve lojistik firması ile 51 muhasebe, e-Fatura ve ERP programı tanımlıdır; tam liste entegrasyonlar sayfasında. UPS, paketinizdeki kargo firması haklarından birini kullanır.

Yıllık ödemede %20 indirim uygulanır; ayrıntılar paketler bölümünde. Yurt dışı için UPS'in yanında ikinci bir ekspres seçenek, örneğin DHL Express entegrasyonu ya da yurt içi bir kargo firması kullanacaksanız en az iki kargo hakkı olan Profesyonel paketi değerlendirin.

Pilot kurulum nasıl ilerler?

UPS entegrasyonu pilot aşamasında: kurulumu sizinle birlikte yapıyor, ilk gönderinizi birlikte doğruluyoruz. Ön görüşmede kanallarınızı, UPS hesabınızı ve yazıcınızı konuşuyor, 3 günlük ücretsiz denemede bağlantıyı kendi siparişinizle deniyoruz. Başlamak için Yox İş Ortağım'a başvurun; sorularınız için iletişim sayfasından bize yazabilirsiniz.

UPS entegrasyonunu canlıya almadan önce kontrol listesi ve sık hatalar

UPS entegrasyonunu canlıya almadan önce tek bir gerçek siparişle etiketin, takip numarasının ve kanala giden bildirimin uçtan uca çalıştığını görün. Pilot kurulumda bu listeyi birlikte geçiyoruz.

İlk gönderiden önce kontrol listesi

• UPS hesap numaranız aktif ve Developer Portal'daki uygulamaya bağlı.
• Uygulamada Shipping ve Tracking ürünleri ekli; Client Id ve Client Secret panele girildi, bağlantı testi başarılı.
• Gönderici adı, adresi ve telefonu UPS hesabınızdaki bilgilerle aynı.
• Ürün kartlarında gümrüğün anlayacağı açık ürün tanımı ve birim değer var; AB'ye satıyorsanız barkod ve üretici kodu dolu.
• Etiket biçimi yazıcınıza uygun ve test baskısı okunaklı.

Kurulumda en sık yapılan hatalar

• Uygulamayı şirket hesabının bağlı olmadığı kişisel bir UPS.com profiliyle açmak: bilgiler yalnız o profile bağlı hesaplarla çalışır.
• Şubeden alınan kullanıcı adı ve şifreyi Client Id ve Client Secret alanlarına yazmak.
• Alıcı adresinde posta kodunu ya da telefonu eksik bırakmak.
• BGB'de beyan türünün ET olarak işlenmesini ve vergi numarasının beyan edilmesini UPS'e hatırlatmamak.
• Pazaryerinin anlaşmalı kargo kuralını kontrol etmeden yurt içi pazaryeri siparişini UPS ile göndermek.