Kargo Entegrasyonu Nedir? Kargo API'lerini Bağlamanın 6 Adımı

Sipariş sayısı arttıkça kargo, operasyonun en çok el emeği yiyen halkasına dönüşür: kargo firmasının panelini açmak, alıcı bilgisini kopyalamak, etiketi basmak, takip numarasını sipariş kaydına ve pazaryerine geri yazmak. Günde birkaç siparişte katlanılır bir iştir; sipariş sayısı yüzlere çıktığında bir kişinin gününü yer.

Kargo entegrasyonu, bu zincirin her halkasını kargo firmasının ya da bir kargo entegratörünün API'sine bağlayıp elden çıkarmaktır. Gönderi kaydı API ile açılır, etiket dosya olarak döner, takip numarası siparişe yazılır, durum değişiklikleri kendiliğinden düşer. Bu yazıda kargo entegrasyonunun tam olarak ne olduğunu, iki farklı bağlanma mimarisini ve kargo API'lerini bağlamanın altı adımını anlatıyoruz.

Kargo entegrasyonu nedir?

Kargo entegrasyonu, mağazanızın ya da yönetim panelinizin kargo firmasıyla insan eli olmadan konuşmasıdır. Pratikte dört temel işi kapsar:

• Gönderi oluşturma: alıcı adresi, paket ölçüsü ve içerik bilgisi API'ye gider; karşılığında bir gönderi kaydı ve takip numarası döner.
• Etiket üretme: kargo etiketi PDF, PNG ya da termal yazıcıların anladığı ZPL biçiminde geri gelir.
• Takip numarasını geri yazma: numara sipariş kaydına, müşteri bildirimine ve pazaryeri siparişiyse kanalın kendi sistemine işlenir.
• Durum akışı: kurye aldı, yolda, dağıtımda, teslim edildi, teslim edilemedi — her değişiklik siparişin üstüne düşer.

Bunların yanında sağlayıcıdan sağlayıcıya değişen dört işlev daha vardır: fiyat sorgulama, kurye alım randevusu, gönderi iptali ve iade gönderisi oluşturma. “Kargo entegrasyonu var” cümlesi bu sekiz işlevin hepsinin bulunduğu anlamına gelmez. Kendi kurduğumuz bağlantılarda da durum böyle: bir sağlayıcıda fiyat sorgulama ucu hiç yoktur, bir diğerinde kurye randevusu alınamaz, bir başkasında olay bildirimi yerine yalnızca düzenli sorgulama çalışır. Sözleşmeden önce hangi uçların gerçekten var olduğunu tek tek sormak, sonradan yaşanan sürprizlerin büyük bölümünü baştan keser.

Entegratör mü, kargo firmasının kendi API'si mi?

Kargo API'sine bağlanmanın iki yolu vardır ve bu seçim sonraki bütün adımları belirler.

1. Kargo entegratörü. Tek bir API'ye bağlanırsınız, o API'nin arkasında birden çok kargo firması durur. Avantajı tek bağlantıyla birden çok taşıyıcıya erişmek ve çoğu entegratörde aynı paket için birden çok firmadan fiyat sorgulayıp en uygununu seçebilmektir. Sözleşme ve tarife genellikle entegratörün tarafındadır; kendi kargo anlaşmanız yoksa hızlı başlangıç budur.

2. Kargo firmasının doğrudan API'si. Kendi kargo sözleşmenizle, kendi tarifenizle gönderirsiniz. Bağlantı tek taşıyıcıyla kurulur ve taşıyıcı API'leri genelde entegratörlerden dardır: fiyat sorgulama, kurye randevusu ve olay bildirimi uçlarından biri ya da birkaçı bulunmayabilir, durum çoğu zaman düzenli sorgulamayla öğrenilir. Buna karşılık hacminiz anlaşmalı tarifeye ulaştıysa gönderi başına maliyetiniz düşer.

Karar ölçütü basittir: aylık gönderi adediniz kargo firmasıyla anlaşma yapmaya yetiyor mu? Yetiyorsa doğrudan bağlantı, yetmiyorsa entegratör. İkisi birlikte de kullanılır: mubido tarafında entegratör bağlantıları ile doğrudan taşıyıcı bağlantıları ayrı kategoriler olarak tanımlanır, böylece kendi sitenizden çıkan gönderileri kendi anlaşmanızla, belirli kanalların paketlerini kanalın kargosuyla yollayabilirsiniz. Doğrudan bağlantı her taşıyıcı için hazır değildir; hangi taşıyıcıların desteklendiği zamanla genişleyen bir listedir ve sizinkinin bugün bu listede olup olmadığı kurulum görüşmesinde teyit edilir.

Adım 1: Hangi hesapla göndereceğinize karar verin

İlk adım teknik değil ticaridir: entegratör hesabı mı açacaksınız, kargo firmasıyla kurumsal sözleşme mi yapacaksınız? Bu karar verilmeden API anahtarı istemenin anlamı yok, çünkü ikisinde anahtarı veren taraf da, faturayı kesen taraf da farklıdır.

Anlaşma görüşmesinde netleştirilecek başlıklar: kademe tablosu, aylık adet taahhüdü, iade gönderisinin nasıl faturalandığı, depodan kurye alımının olup olmadığı ve tarifeye dahil olmayan ek kalemler. Bunların satış fiyatına nasıl yansıdığını kargo ücreti hesaplama yazımızda ayrıntılı anlattık. Gönderilerinizin desisini bilmiyorsanız önce desi hesaplama tarafına bakın: paket ölçüsü, entegrasyonun üçüncü adımında zorunlu bir alan olarak karşınıza çıkacak.

Adım 2: API anahtarlarını bağlayın ve bağlantıyı test edin

Her sağlayıcı kendi kimlik bilgisini ister: kiminde tek bir API anahtarı, kiminde kullanıcı adı ve parola, kiminde ayrıca bir entegratör numarası. Üç kural:

• Anahtarlar şifreli saklanmalı. Panel veritabanında düz metin duran bir kargo anahtarı, sızdığında sizin adınıza gönderi açtırır. mubido'da kargo kimlik bilgileri veritabanına şifrelenmiş yazılır ve yalnız çağrı anında çözülür.
• Bağlantı testi süs değil, adımın kendisidir. İyi bir test yalnız “anahtar doğru mu” demez, hesabın gerçekten aktif olduğunu da söyler. Kontörü bitmiş ya da yarı aktif bir entegratör hesabı, anahtarı doğru olduğu hâlde ilk gerçek gönderide hata verir.
• Test ortamı ile canlıyı ayırın. Kurulum ve deneme sırasında sağlayıcının gerçek API'sine gidilmemelidir; deneme gönderileri para harcatır ve kargo firmasının sisteminde iz bırakır.

Ekran görüntüsü alırken, ekran paylaşırken ya da destek talebine dosya eklerken anahtar alanlarını maskeleyin. Kargo anahtarı, ödeme anahtarıyla aynı sınıfta bir sırdır.

Adım 3: Gönderici adresini ve paket varsayılanlarını tanımlayın

Bu adım en çok küçümsenen ve en çok hata üretenidir. Gönderi oluşturma çağrısı, alıcı bilgisi kadar gönderici bilgisini de ister.

• Telefon zorunludur. Kurye teslimden önce arar; telefonsuz gönderi kaydı çoğu API'de hiç açılmaz.
• İl ve ilçe ayrı alanlardır, serbest metin adres satırı bunların yerini tutmaz. Bazı taşıyıcı API'leri ayrıca mahalleyi ayrı bir alan olarak zorunlu tutar — oysa çoğu mağaza yazılımının adres modelinde ayrı bir mahalle alanı yoktur, mahalle-sokak-bina tek satırda durur. Bu uyuşmazlık, kurulumda sessizce reddedilen gönderilerin en sık sebeplerinden biridir.
• Ağırlık her gönderide zorunludur; ölçü çoğu zaman isteğe bağlıdır ama fiyatı belirleyen odur. Kargo firması hacimsel ağırlık ile fiili ağırlığı karşılaştırır ve büyük olanı ücretlendirir. Ürün kartında ölçü ve ağırlık boşsa entegrasyon varsayılan bir değerle gönderi açar; fatura ise varsayılana göre değil, gerçek koliye göre gelir.
• Kapıda ödeme ayrı bir bayraktır. Her taşıyıcı desteklemez; desteklemeyen bir taşıyıcıya kapıda ödemeli gönderi yollandığında çağrı hata döner.

Depolu çalışıyorsanız gönderici adresini elle yazmak yerine depo kaydına bağlayın; depo değiştiğinde tek yerde güncellenir. Sipariş kuyruğunun panelde nasıl ilerlediğini sipariş yönetimi sayfamızda anlatıyoruz.

Adım 4: Etiketin ne zaman üretileceğine karar verin

Bağlantı kurulduktan sonraki ilk gerçek karar, gönderinin hangi olayla açılacağıdır. Üç yaygın tetikleyici vardır:

• Ödeme alındığında otomatik: sipariş ödendiği anda gönderi kaydı açılır, etiket hazır bekler. Hacmi yüksek ve iptali düşük operasyonlar için en hızlısı.
• Siparişi işleme alırken elle: paketi hazırlayan kişi kargoya ver dediğinde gönderi açılır. Kırılgan, özel üretim ya da stok teyidi gereken ürünlerde daha güvenlidir.
• Toplu: günün sonunda seçilen siparişler için etiketler tek seferde basılır.

Hangi tetikleyiciyi seçerseniz seçin, mükerrer gönderi koruması şarttır. Ağ hatası yüzünden yarıda kalan bir çağrının yeniden denenmesi, koruma yoksa aynı sipariş için ikinci bir etiket ve ikinci bir fatura üretir. Doğru kurgu, her gönderi çağrısına siparişin kendi referansını iliştirmek ve aynı referansla gelen ikinci isteği yeni gönderi açmak yerine mevcut gönderiye bağlamaktır.

Bir ayrıntı daha: etiket bağlantıları kalıcı değildir. Sağlayıcılar etiketi kısa ömürlü bir adreste verir, bir süre sonra aynı adres boş döner. Etiketi ürettiğiniz anda kendi tarafınıza kopyalamıyorsanız iki hafta sonra “şu gönderinin etiketini tekrar basalım” dediğinizde elinizde bir şey kalmaz.

Adım 5: Durum takibini kurun — bildirim mi, sorgulama mı?

Gönderi açıldıktan sonra paketin nerede olduğunu iki yoldan öğrenirsiniz.

Olay bildirimi (webhook): sağlayıcı, durum değiştiğinde sizin adresinize istek atar; gecikme neredeyse sıfırdır. Kurarken iki şeye dikkat edin: gelen isteğin gerçekten sağlayıcıdan geldiğini imza doğrulamasıyla kontrol edin ve aynı olayın iki kez gelmesine hazırlıklı olun. Sağlayıcılar yanıt alamadıklarında aynı bildirimi tekrarlar; olay kimliğine bakmayan bir kurulum tek teslimatı iki kez işler.

Düzenli sorgulama: sağlayıcı bildirim göndermiyorsa açık gönderileri belirli aralıklarla siz sorarsınız. Aralığı seçerken iki maliyet dengelenir: çok sık sorgu API sınırlarını zorlar, çok seyrek sorgu müşteriye geciken bilgi verir. mubido'da açık gönderiler düzenli aralıklarla sorgulanır ve bildirimle zaten güncellenmiş gönderiler o turda sorgu dışında bırakılır, aynı bilgi iki kez alınmaz.

Üçüncü ve en çok atlanan parça: durum kodlarının ortak bir dile çevrilmesi. Her kargo firması durumu kendi koduyla söyler. Bunlar tek bir listeye normalize edilmezse sipariş ekranında karşılaştırılabilir bir durum kalmaz, raporlama da imkânsızlaşır.

Bu listede teslim edildi dışındaki dört kapanış — teslim edilemedi, göndericiye iade, iptal ve hata — elle bakmanız gereken satırlardır: kendiliğinden düzelmezler ve müşteri çoğu zaman sizden önce fark eder. Durum değişikliğini müşteriye e-posta ya da mesajla iletmek de bu adımın parçasıdır; kargoya verildi ve teslim edildi bildirimleri, müşteri hizmetlerine gelen “kargom nerede” sorularını azaltır.

Adım 6: İptal ve iade akışını bağlayın

İptal ile iade aynı şey değildir ve entegrasyonda iki ayrı uçtan yürür.

İptal, kurye paketi almadan önce yapılabilir. Paket yola çıktıktan sonra gönderi iptal edilemez; o noktadan sonra yapılabilecek tek şey paketin geri dönmesini beklemektir. Bu yüzden iptal düğmesinin panelde hangi durumlarda etkin olacağı baştan tanımlanmalıdır.

İade, ters yönde açılan yeni bir gönderidir: gönderici müşteri, alıcı sizsiniz. Bazı sağlayıcılar orijinal gönderiye bağlı hazır bir iade ucu sunar; sunmayanlarda gönderici ve alıcı adresleri ters çevrilerek yeni bir gönderi açılır. İkinci yolda dikkat edilecek nokta, iade gönderisine kapıda ödeme iliştirilmemesidir.

İade paketi depoya ulaştığında sipariş teslim edildi sayılmamalıdır; paket müşteriye değil size gitmiştir. İade gönderisinin durumu siparişin durumundan ayrı tutulur ve depo paketi kontrol edip onayladığında iade kapanır.

Pazaryeri siparişlerinde kargo: önce davranışı seçin

Kendi sitenizden gelen sipariş ile pazaryeri siparişi aynı kuralla yönetilemez. Pazaryerinin kendi anlaşmalı kargosu vardır ve çoğu durumda paketin o kargoyla gitmesi beklenir. Entegrasyonu açmadan önce üç davranıştan birini seçmeniz gerekir:

Buradaki en kritik güvenlik kuralı şudur: paketin üzerindeki kargo firması ile sizin taşıyıcınız eşleşmiyorsa gönderi hiç açılmamalıdır. Eşleşme kontrolü olmayan bir kurulum, kanalın A kargosuyla gönder dediği paketi B kargosuna verir; sonuç kanal tarafında ceza puanı, müşteri tarafında kaybolmuş pakettir.

Bazı kanallar kargo etiketini dışarıya yalnız özel bir servisten verir ve bu servis satıcı hesaplarında varsayılan olarak kapalı gelir; yetki bir kez açılır, sonrası ek ayar gerektirmez. Etiketin hangi anda basılabildiği de kanala göre değişir: sipariş işleme alınmadan ve kargo firması bilgisi oluşmadan etiket üretilmez. Pazaryeri siparişinde etiket basma akışının tamamını, kanal tarafında çıkan uyarıların ne anlama geldiği dahil, sipariş ve kargo etiketi yardım sayfamızda adım adım anlattık.

Açmadan önce: yedi maddelik kontrol listesi

1. Sağlayıcının hangi uçları var: fiyat sorgulama, etiket, kurye randevusu, olay bildirimi, iade? Yazılı teyit alın.
2. Kimlik bilgileri şifreli saklanıyor mu ve bağlantı testi hesabın aktifliğini de ölçüyor mu?
3. Gönderici adresi eksiksiz mi: telefon, il, ilçe ve gerekiyorsa mahalle?
4. En çok satan ürünlerinizin ölçü ve ağırlık alanları dolu mu?
5. Aynı sipariş için ikinci etiket üretilmesini engelleyen bir koruma var mı?
6. Etiket dosyası kendi tarafınıza kalıcı olarak kopyalanıyor mu?
7. Durum kodları tek listeye çevriliyor ve değişiklik müşteriye bildiriliyor mu?

Son bir hatırlatma, teknik değil hukuki: mesafeli satışta satıcı, tüketicinin siparişinin kendisine ulaştığı tarihten itibaren taahhüt ettiği süre içinde edimini yerine getirmek zorundadır ve mal satışlarında bu süre her hâlükârda otuz günü geçemez (Mesafeli Sözleşmeler Yönetmeliği, madde 16 — Resmî Gazete, 27 Kasım 2014; erişim: 20 Eylül 2026). Kargo entegrasyonu bu süreyi kısaltmak için değil, ölçülebilir kılmak için vardır: hangi siparişin kaç gündür kargoya verilmediğini panelden görebiliyorsanız bu yükümlülüğü de yönetiyorsunuz demektir.

Kargo, faturadan ve stoktan ayrı düşünülemez

Kargo entegrasyonu tek başına kurulduğunda yarım kalır. Sipariş düştüğünde stoğun düşmesi, faturanın kesilmesi, etiketin basılması ve takip numarasının kanala dönmesi tek bir zincirdir; halkalardan biri ayrı bir programda duruyorsa aradaki veriyi taşıyan yine bir insan olur ve zincir en yoğun günde kopar.

mubido'da sipariş, fatura ve kargo kayıtları aynı panelde durur; kargo tarafında entegratör bağlantıları ve desteklenen taşıyıcılarda kendi kargo sözleşmeniz bağlanabilir. Sizin taşıyıcınızın bugün desteklenip desteklenmediğini kurulum talebinde teyit ediyoruz. Bağlantıları ve kurulumu biz yapıyoruz. Fatura ve kargo akışının tamamını fatura ve kargo sayfamızda görebilirsiniz.

Sıkça Sorulan Sorular

Kargo entegrasyonu nedir?

Kargo entegrasyonu, mağaza ya da yönetim panelinizin kargo firmasının API'siyle doğrudan konuşmasıdır. Gönderi kaydı API ile açılır, etiket dosya olarak döner, takip numarası siparişe ve pazaryerine geri yazılır, durum değişiklikleri otomatik düşer. Amaç, kargo panelinde elle yapılan kopyala-yapıştır işini ortadan kaldırmaktır.

Kargo entegratörü mü, kargo firmasının kendi API'si mi daha uygun?

Aylık gönderi adediniz kargo firmasıyla anlaşma yapmaya yetiyorsa doğrudan bağlantı gönderi başına maliyeti düşürür. Yetmiyorsa entegratör daha mantıklıdır: tek bağlantıyla birden çok taşıyıcıya erişirsiniz ve çoğu entegratörde aynı paket için firmalardan fiyat sorgulayıp en uygununu seçebilirsiniz. İkisi birlikte de kullanılabilir.

Kargo entegrasyonu için kargo firmasıyla sözleşme şart mı?

Doğrudan bağlantıda şarttır, çünkü anahtarı ve tarifeyi kargo firması verir. Entegratör kullanıyorsanız sözleşme genellikle entegratörle yapılır ve kendi kargo anlaşmanız olmadan da gönderi açabilirsiniz; buna karşılık tarife entegratörün tarifesidir.

Takip numarası pazaryerine otomatik iletilir mi?

Kanal buna izin veriyorsa evet. Kritik nokta, paketteki kargo firması ile sizin taşıyıcınızın eşleşmesidir: eşleşme yoksa gönderi hiç açılmamalıdır, aksi hâlde paket yanlış kargoya verilir ve kanal tarafında ceza yazılır. Bazı kanallarda etiket ucunu kullanabilmek için hesabınıza bir kerelik yetki tanımlanması gerekir.

Kargo etiketi hangi biçimde gelir, termal yazıcıda basılır mı?

Sağlayıcıya göre PDF, PNG ya da termal yazıcıların doğrudan anladığı ZPL biçiminde döner; PDF hem A4 çıktıda hem termal etiket yazıcısında kullanılabilir. Etiket bağlantıları kısa ömürlüdür, bu yüzden dosya üretildiği anda kendi tarafınıza kalıcı olarak kopyalanmalıdır.