Shopify Yurtiçi Kargo Entegrasyonu Nasıl Yapılır?

Shopify Yurtiçi Kargo Entegrasyonu Nedir? Shopify yurtiçi kargo entegrasyonu, Yurtiçi Kargo’nun kurumsal API’sini veya Shopify App Store’daki resmi uygulamasını mağaza paneline bağlayarak sipariş onayı sonrası kargo etiketinin ve takip numarasının otomatik oluşturulmasını sağlayan kurulum sürecidir.

Yurtiçi Kargo, Türkiye’nin en geniş şube ağına sahip kargo firmalarından biridir ve Shopify App Store’da doğrudan bir entegrasyon uygulaması bulunur (Shopify App Store, 2025). Bu, diğer bazı yerli kargo firmalarına kıyasla kurulumu geliştirici gerektirmeyen bir sürece indirger. Mağaza sahibi API anahtarını girip adres eşleştirmesini tamamladığında entegrasyon aynı gün devreye alınabilir.

Kurulum sürecinde en çok hata yapılan iki adım API anahtarı yönetimi ve adres formatı eşleştirmesidir. Bu iki noktaya dikkat edilmediğinde kargo kaydı oluşturulur ama teslimat adresi hatalı görünür.

Shopify’a Yurtiçi Kargo Nasıl Bağlanır?

Shopify’a Yurtiçi Kargo bağlama işlemi, Shopify App Store’dan Yurtiçi Kargo uygulamasının kurulup kurumsal API kimlik bilgilerinin girilmesiyle tamamlanır; teknik geliştirme gerekmez.

Bu süreç, önce Yurtiçi Kargo ile kurumsal anlaşma yapılmasını, ardından Shopify tarafında uygulamanın etkinleştirilmesini gerektirir. İki taraf arasındaki bağlantı API anahtarı üzerinden kurulur.

1. Yurtiçi Kargo Kurumsal Müşteri Hizmetleri üzerinden anlaşma başvurusu yapılır ve müşteri kodu alınır.
2. Yurtiçi Kargo’nun kurumsal panelinden API kullanıcı adı, şifre ve müşteri kodu bilgisi edinilir.
3. Shopify Admin → Apps → Shopify App Store üzerinden Yurtiçi Kargo entegrasyon uygulaması aranır ve yüklenir.
4. Uygulama ayarlarına API kimlik bilgileri girilir.
5. Test siparişiyle kargo kaydı oluşturma ve etiket basma işlemi doğrulanır.

İpucu: Kurumsal anlaşma başvurusunda mağazanın tahmini aylık kargo hacmi net beyan edilmelidir. Hacim beyanı, uygulanacak birim kargo ücretini doğrudan etkiler ve düşük beyan sonradan sözleşme revizyonuna neden olabilir.

Bireysel ile Kurumsal Yurtiçi Kargo Hesabı Arasındaki Fark Nedir?

Bireysel Yurtiçi Kargo hesabı, tekil gönderi oluşturmaya izin verir ama API erişimi sunmaz; kurumsal hesap ise mağazaya özel müşteri kodu ve API kimlik bilgisi tanımlayarak otomatik entegrasyona izin verir.

Bu fark, yeni açılan bir mağazanın önce bireysel hesapla test siparişleri gönderip hacim büyüdükçe kurumsal hesaba geçiş yapması pratiğini yaygınlaştırır. Kurumsal hesaba geçiş, genelde aylık 100’ün üzerinde gönderi hacmi öngören mağazalar için önerilir çünkü kurumsal anlaşmanın birim fiyat avantajı bu hacimden sonra belirginleşir.

Şirket türü de sürece etki eder şahıs şirketi statüsündeki mağazalar da kurumsal anlaşma yapabilir, tüzel şirket şartı aranmaz. Vergi levhası ve imza sirküleri belgeleri başvuru için yeterlidir.

Yurtiçi Kargo API Anahtarı Nasıl Alınır?

Yurtiçi Kargo API anahtarı, kurumsal anlaşma imzalandıktan sonra firmanın API entegrasyon ekibi tarafından mağazaya özel olarak tanımlanır; bu anahtar kullanıcı adı, şifre ve müşteri kodundan oluşan üç parçalı bir kimlik doğrulama setidir.

API kimlik bilgileri genelde e-posta yoluyla iletilir ve test ortamı (sandbox) ile canlı ortam (production) için ayrı setler verilir. Sandbox ortamında yapılan testler gerçek kargo kaydı oluşturmaz, bu da geliştirme aşamasında güvenli deneme imkanı sağlar.

Kritik Not: Sandbox API anahtarının canlı ortamda kullanılması, kargo kaydının Yurtiçi Kargo sisteminde “test” statüsünde kalmasına ve fiziksel şubede taranmamasına yol açar. Canlıya geçmeden önce ortam (environment) ayarının production olarak değiştirildiği mutlaka kontrol edilmelidir.

Sandbox ve Production Ortamları Arasında Geçiş Nasıl Yapılır?

Sandbox ve production ortamları arasında geçiş, Shopify uygulama ayarlarındaki “environment” veya “ortam” seçeneğinin production olarak değiştirilip yeni API kimlik bilgilerinin girilmesiyle yapılır; bu iki ortamın API anahtarları birbirinden tamamen farklıdır ve karıştırılmamalıdır.

Sandbox ortamında oluşturulan kargo kayıtları Yurtiçi Kargo’nun gerçek şube sistemine düşmez, yalnızca API bağlantısının doğru çalıştığını test etmek için kullanılır. Bu ortamda oluşturulan barkodlar geçersizdir ve fiziksel bir gönderiye karşılık gelmez.

Peki bu geçiş neden dikkatli yapılmalı? Production anahtarları yanlışlıkla sandbox ortamında test edilirse gerçek kargo ücreti tahakkuk edebilir; tersi durumda ise mağaza canlıya geçtiğini sanıp sandbox anahtarlarıyla çalışmaya devam eder ve hiçbir gerçek kargo kaydı oluşmaz.

Otomatik Kargo Etiketi Nasıl Oluşturulur?

Otomatik kargo etiketi, sipariş Shopify’da “ödeme onaylandı” durumuna geçtiğinde entegrasyon uygulamasının Yurtiçi Kargo API’sine sipariş verisini gönderip PDF formatında etiket üretmesiyle oluşturulur; mağaza sahibi tek tık ile toplu etiket yazdırabilir.

Bu otomasyon, günde 100’ün üzerinde sipariş işleyen mağazalarda manuel etiket yazma süresini önemli ölçüde kısaltan tek adımdır. Toplu etiket oluşturma özelliği çoğu entegrasyon uygulamasında standart olarak sunulur.

Shopify dokümantasyonuna göre bir siparişin fulfillment durumu, kargo etiketi oluşturulduğunda otomatik olarak güncellenir ve müşteri bildirimi bu durum değişikliğine bağlı tetiklenir (Shopify Help Center, 2025). Bu mekanizma sayesinde etiket basımı ile müşteri bilgilendirmesi aynı anda gerçekleşir.

Toplu Etiket Basımı Büyük Hacimli Mağazalarda Nasıl Yönetilir?

Toplu etiket basımı, birden fazla siparişin tek seferde seçilip tek bir PDF dosyasında etiketlerin ardışık sıralanmasıyla yönetilir; bu özellik entegrasyon uygulamasının sipariş listesi ekranında genelde “toplu işlem” veya “bulk fulfillment” adıyla sunulur.

Günde 200’ün üzerinde sipariş işleyen bir mağaza için toplu etiket basımı, her siparişi tek tek açıp etiket indirme sürecini ortadan kaldırır. Bu özellik olmadan yüksek hacimli bir operasyonda paketleme ekibi etiketleri tek tek eşleştirmek zorunda kalır, bu da paketleme hatası riskini artırır.

Kritik Not: Toplu etiket PDF’i oluşturulduğunda etiketlerin sipariş numarası sırasına göre mi yoksa paketleme sırasına göre mi dizildiği kontrol edilmelidir. Sıralama uyumsuzluğu, yanlış ürünün yanlış müşteriye gönderilmesi riskini doğurabilir.

Adres Eşleştirme Sorunları Nasıl Çözülür?

Adres eşleştirme sorunu, Shopify’ın adres alanlarıyla Yurtiçi Kargo API’sinin beklediği alan formatının birebir örtüşmemesinden kaynaklanır; en sık karşılaşılan hata mahalle ve ilçe bilgisinin tek bir alana sıkıştırılmasıdır.

Türkiye adres yapısı il, ilçe, mahalle ve sokak olmak üzere dört katmanlıdır ama Shopify’ın varsayılan checkout adres formu bu katmanları ayrı alanlar olarak sunmaz. Bu uyumsuzluk, kargo firmasının adres doğrulama sisteminde “adres bulunamadı” hatasına yol açabilir.

Peki bu sorun pratikte nasıl çözülür? Checkout adres alanına mahalle/ilçe bilgisini ayrıştırmaya zorlayan bir uygulama eklemek veya sipariş onayı öncesi manuel adres kontrolü yapmak, hatalı teslimat oranını düşüren iki pratik yöntemdir.

Uzak Durulması Gereken Risk: Adres alanı boş bırakılan veya kısaltma içeren siparişlerde (örneğin “Kadıköy” yerine sadece “İst.”) kargo firması adresi otomatik eşleştiremez ve paket şubede bekletilir. Yüksek hacimli mağazalarda checkout adım sırasında adres doğrulama uygulaması kullanmak bu hatayı sipariş anında yakalar.

İade Süreci Yurtiçi Kargo Entegrasyonuna Nasıl Eklenir?

İade süreci, mağazanın Yurtiçi Kargo panelinden “iade kodu” oluşturup bu kodu müşteriye e-posta ile ilettiği veya entegrasyon uygulamasının otomatik iade etiketi ürettiği bir alt akıştır; bu akış olmadan müşteri iade göndermek için kargo ücretini kendi cebinden karşılamak zorunda kalabilir.

Yurtiçi Kargo’nun kurumsal anlaşmalarında iade kargo ücretinin mağaza tarafından karşılanıp karşılanmayacağı ayrı bir madde olarak yer alır. Bu maddenin net olmaması, müşteri memnuniyetsizliğine ve iade sürecinin uzamasına yol açabilir.

Peki bu süreç pratikte nasıl işler? Müşteri iade talebini mağaza panelinden veya e-posta ile bildirdiğinde, entegrasyon uygulaması otomatik olarak bir iade barkodu üretir ve bu barkod müşteriye e-posta ile gönderilir; müşteri paketi en yakın Yurtiçi Kargo şubesine bu barkodla teslim eder.

Yurtiçi Kargo Entegrasyonunda Sipariş Durumu Senkronizasyonu Nasıl Çalışır?

Sipariş durumu senkronizasyonu, Yurtiçi Kargo’nun şube tarama sisteminden dönen her durum güncellemesinin (kargoya verildi, dağıtım merkezine ulaştı, dağıtıma çıktı, teslim edildi) entegrasyon uygulaması üzerinden Shopify sipariş kaydına yazılmasıyla çalışır; bu senkronizasyon gerçek zamanlıya yakın çalışır ama anlık değildir.

Yurtiçi Kargo’nun şube tarama sistemi, paket her şubeden geçtiğinde bir durum kaydı oluşturur ve bu kayıt API üzerinden birkaç dakika içinde entegrasyon uygulamasına iletilir. Büyükşehirler arası gönderilerde bu güncelleme sıklığı günde 3-4 kez gerçekleşirken, kırsal bölgeye giden gönderilerde şube sayısının azlığı nedeniyle güncelleme sıklığı düşebilir.

Bu senkronizasyon, müşteri hizmetlerinin “siparişim nerede” sorularına Yurtiçi Kargo’nun ayrı takip sayfasına bakmadan, doğrudan Shopify panelinden yanıt vermesini sağlar. Senkronizasyon koptuğunda (webhook hatası veya API zaman aşımı gibi nedenlerle) sipariş durumu son bilinen aşamada takılı kalır ve müşteri hizmetleri yanlış bilgi verme riskiyle karşılaşır.

Kritik Not: Senkronizasyon kopmalarını erken tespit etmek için entegrasyon uygulamasının “son güncelleme zamanı” bilgisini düzenli kontrol etmek gerekir. 24 saatten uzun süredir güncellenmeyen bir sipariş kaydı, API bağlantısında bir sorun olduğunun ilk işaretidir.

Yurtiçi Kargo Entegrasyonu Diğer Firmalardan Nasıl Farklılaşır?

Yurtiçi Kargo’yu diğer yerli firmalardan ayıran temel fark, Shopify App Store’da doğrudan resmi bir uygulamanın bulunmasıdır; Aras Kargo ve MNG Kargo gibi firmalar bu düzeyde doğrudan entegrasyon sunmaz.

Bu fark, teknik kaynağı olmayan küçük ve orta ölçekli mağazalar için Yurtiçi Kargo’yu ilk tercih haline getirir. Genel kargo firması seçim kriterleri ve karşılaştırma tablosu Shopify kargo entegrasyonu rehberinde detaylı işlenir.

Entegrasyon tamamlandıktan sonra takip numarasının müşteriye otomatik ulaştırılması ayrı bir kurulum adımı gerektirir; bu sürecin Fulfillment API ve Shopify Flow ile nasıl otomatikleştirileceği kargo takip numarası otomatik oluşturma rehberinde anlatılır.

Yurtiçi Kargo Entegrasyon Uygulaması Seçerken Nelere Dikkat Edilmeli?

Shopify App Store’da Yurtiçi Kargo’ya bağlanan birden fazla uygulama bulunur; seçim yapılırken uygulamanın güncelleme sıklığı, destek yanıt süresi ve toplu işlem kapasitesi karşılaştırılmalıdır çünkü tüm uygulamalar aynı özellik setini sunmaz.

Bazı uygulamalar yalnızca temel etiket oluşturma özelliği sunarken bazıları toplu etiket basımı, iade yönetimi ve çoklu depo desteğini aynı pakette birleştirir. Düşük hacimli bir mağaza için temel özellik yeterliyken, büyüyen bir mağaza altı ay içinde bu sınırlı özellik setinin yetersiz kaldığını fark edebilir.

Uygulama seçiminde göz ardı edilen bir diğer nokta Shopify App Store’daki kullanıcı yorumlarının güncellik tarihidir. İki yıl önce yazılmış olumlu bir yorum, uygulamanın güncel API sürümüyle uyumlu çalıştığının garantisi değildir; son üç ay içindeki yorumlar daha güvenilir bir gösterge sunar.

Uzak Durulması Gereken Risk: Yalnızca en düşük aylık ücrete sahip uygulamayı seçmek, sipariş hacmi büyüdüğünde uygulama değiştirme maliyetine dönüşebilir. Uygulama seçimi, mevcut hacim kadar altı ay sonraki tahmini hacim de göz önünde bulundurularak yapılmalıdır.

Desi Hesaplaması Kargo Ücretini Nasıl Etkiler?

Desi hesaplaması, ürünün gerçek ağırlığı ile hacimsel ağırlığından (en x boy x yükseklik / 3000 formülü) büyük olanının kargo ücretine esas alınmasıyla çalışır; bu, hafif ama kutulu ürünlerin gerçek ağırlığından daha yüksek ücretlendirilmesine neden olabilir.

Bir örnek üzerinden bakıldığında: 1 kilogram ağırlığındaki bir yastık, 40x30x20 santimetre boyutundaki kutusuyla hesaplandığında hacimsel ağırlığı 8 desi çıkar (40x30x20/3000=8). Kargo ücreti bu durumda gerçek ağırlık olan 1 kilogram yerine 8 desi üzerinden hesaplanır. Bu fark, mağaza sahibinin ürün fiyatlandırmasında öngörmediği bir maliyet kalemi yaratabilir.

Shopify ürün sayfasında yalnızca ağırlık alanı bulunur, boyut (en-boy-yükseklik) alanı standart olarak yer almaz. Bu eksiklik, desi hesaplamasının entegrasyon uygulamasında ayrı bir alan üzerinden veya varsayılan paket boyutuyla yapılmasını gerektirir.

İpucu: Ürün kataloğunda farklı boyut aralıklarına giren ürün grupları varsa (küçük aksesuar, orta boy giyim, büyük ev tekstili gibi) her grup için ayrı bir varsayılan paket boyutu tanımlamak, desi hesaplamasının gerçek maliyete daha yakın çıkmasını sağlar.

Sık Sorulan Sorular

Shopify’a Yurtiçi Kargo entegrasyonu için kurumsal anlaşma zorunlu mu? Evet, API erişimi yalnızca kurumsal anlaşma yapan mağazalara açılır. Bireysel gönderi hesabıyla API entegrasyonu kurulamaz.

Yurtiçi Kargo entegrasyonu ne kadar sürede aktif olur? Kurumsal anlaşma onayı 2-5 iş günü, Shopify uygulama kurulumu ise 1 saatten kısa sürer. Toplam süreç genelde bir hafta içinde tamamlanır.

Yurtiçi Kargo Shopify App’i ücretli mi? Çoğu entegrasyon uygulaması aylık abonelik modeliyle çalışır, ücret sipariş hacmine göre değişir. Yurtiçi Kargo’nun kendi kargo ücreti bu abonelik ücretinden ayrıdır.

Adres hatası nedeniyle iade edilen kargo maliyeti kime ait? Genelde mağaza sahibine yansır çünkü adres bilgisi checkout sırasında müşteri tarafından girilir. Adres doğrulama uygulaması kullanmak bu maliyeti sipariş öncesi engelleyen tek etkin yöntemdir.

Yurtiçi Kargo entegrasyonu olmadan manuel kargo yönetimi mümkün mü? Evet, düşük hacimli mağazalar Yurtiçi Kargo panelinden manuel kargo kaydı oluşturabilir. Ancak sipariş sayısı arttıkça bu yöntem zaman kaybına ve hata riskine dönüşür.

API anahtarım çalışmıyor, ne kontrol etmeliyim? İlk kontrol edilecek nokta ortam ayarının (sandbox/production) doğru seçili olup olmadığıdır. İkinci adım, müşteri kodunun API kullanıcı adıyla eşleşip eşleşmediğini Yurtiçi Kargo destek hattından teyit etmektir.

Şahıs şirketi Yurtiçi Kargo kurumsal API’sine başvurabilir mi? Evet, Yurtiçi Kargo kurumsal anlaşma başvurusunda tüzel şirket şartı aramaz. Vergi levhası ve imza sirküleri gibi temel belgelerle şahıs şirketleri de başvuru yapabilir.

Yurtiçi Kargo entegrasyonu sonrası kargo ücreti nasıl hesaplanır? Ücret, ürünün desi değeri (hacimsel ağırlık) ve gönderi mesafesine göre kurumsal anlaşmada belirlenen tarifeye göre hesaplanır. Ürün ağırlık ve boyut bilgisinin Shopify’da eksiksiz girilmesi doğru ücretlendirme için zorunludur.

Yurtiçi Kargo entegrasyon uygulaması değiştirilirse geçmiş kargo kayıtları kaybolur mu? Hayır, geçmiş kargo kayıtları Yurtiçi Kargo’nun kendi sisteminde ve Shopify sipariş geçmişinde saklı kalır. Uygulama değişikliği yalnızca yeni oluşturulacak kargo kayıtlarının hangi arayüzden yönetileceğini etkiler.

Kaç farklı Yurtiçi Kargo entegrasyon uygulaması Shopify App Store’da mevcut? Shopify App Store’da Yurtiçi Kargo’ya bağlanan birden fazla uygulama bulunur; bazıları yalnızca Yurtiçi Kargo’ya özel, bazıları çok kargolu entegratör yapısındadır. Seçim, mağazanın ek olarak başka kargo firması kullanıp kullanmayacağına göre yapılmalıdır.

Yurtiçi Kargo entegrasyonunda sipariş durumu ne sıklıkla güncellenir? Büyükşehirler arası gönderilerde durum güncellemesi günde birkaç kez gerçekleşir çünkü şube tarama sıklığı yüksektir. Kırsal bölgeye giden gönderilerde şube sayısının azlığı nedeniyle güncelleme aralığı uzayabilir.

Sonraki Adım

Yurtiçi Kargo entegrasyonu tamamlandıktan sonra takip numarasının otomatik olarak müşteriye ulaştırılması ayrı bir kurulumu gerektirir. Fulfillment API ve Shopify Flow kullanarak bu bildirim akışının nasıl otomatikleştirileceği kargo takip numarası otomatik oluşturma rehberinde adım adım anlatılır.