Kargo API entegrasyonu, e-ticaret sitenizin sipariş süreçlerini otomatikleştiren, manuel veri girişini ortadan kaldıran ve müşterilere anlık takip imkânı sunan kritik bir altyapı bileşenidir. PTT Kargo, MNG Kargo, Yurtiçi Kargo ve Aras Kargo gibi Türk kargo firmalarının API'leri aracılığıyla; etiket basımından takip bildirimlerine kadar tüm lojistik süreçleri tek bir entegrasyon noktasından yönetebilirsiniz. Bu rehberde başlıca kargo API'lerini ve entegrasyon adımlarını ayrıntılı biçimde ele alacağız.
Kargo API Nedir ve Neden Önemlidir?
Kargo API'si, e-ticaret platformunuzun kargo firmasının sistemleriyle programatik olarak iletişim kurmasını sağlayan bir arayüzdür. API entegrasyonu olmadan her sipariş için manuel olarak kargo firmasının arayüzüne giriş yapmanız, gönderi oluşturmanız ve etiketi indirip yazıcıya göndermeniz gerekir. Bu süreç hem zaman kaybettirir hem de insan hatalarına açık bir iş akışı yaratır. API entegrasyonuyla sipariş tamamlandığı anda otomatik olarak kargo barkodu üretilir, etiket hazırlanır, müşteriye takip numarası gönderilir ve tüm süreç kayıt altına alınır.
- Otomasyon: Sipariş oluşturulduğunda kargo kaydı otomatik açılır, manuel işlem gerekmez.
- Hız: Toplu etiket basımı ile günlük yüzlerce siparişi dakikalar içinde hazırlayabilirsiniz.
- Hata Azaltma: Adres ve ağırlık bilgileri sistemden otomatik aktarıldığı için yazım hataları minimize edilir.
- Müşteri Deneyimi: Anlık takip bildirimleri müşteri memnuniyetini ve güvenini artırır.
- Maliyet Analizi: API üzerinden alınan ücret hesaplama verileriyle en uygun kargo seçeneği belirlenebilir.
PTT Kargo API Entegrasyonu
PTT Kargo, Türkiye Posta'nın e-ticaret işletmelerine yönelik sunduğu kargo hizmetidir. PTT Kargo API'sine erişmek için öncelikle PTT Kargo kurumsal müşteri sözleşmesi imzalamanız ve API erişim bilgilerini (kullanıcı adı, şifre, müşteri kodu) temin etmeniz gerekmektedir. PTT Kargo API'si SOAP (XML tabanlı) ve REST protokollerini desteklemektedir; modern projeler için REST endpoint'leri tercih edilmektedir.
PTT Kargo API ile Gönderi Oluşturma
Gönderi oluşturma isteğinde gönderici bilgileri (isim, adres, telefon), alıcı bilgileri ve paket özellikleri (desi/ağırlık, içerik tipi) gönderilir. Başarılı yanıtta bir barkod numarası ve gönderi referans kodu döner. Bu barkod, ZPL veya PDF formatında etiket oluşturmak için kullanılır. PTT Kargo API entegrasyonunda dikkat edilmesi gereken önemli nokta, adres doğrulama adımının ayrı bir endpoint üzerinden yapılmasıdır; hatalı adresler gönderi oluşturma sırasında değil, adres doğrulama aşamasında tespit edilmelidir.
MNG Kargo API Entegrasyonu
MNG Kargo, Türkiye'nin köklü özel kargo firmalarından biridir ve gelişmiş bir REST API altyapısına sahiptir. MNG Kargo API'si için yetkili bayi veya kurumsal anlaşma gereklidir; sandbox (test) ortamı ayrı kimlik bilgileriyle erişilmektedir. MNG API'si JSON formatında request ve response ile çalışır; OAuth 2.0 tabanlı token kimlik doğrulaması kullanır. Temel endpoint'ler şunlardır: gönderi oluşturma, etiket indirme (PDF veya ZPL), gönderi sorgulama ve iptal işlemi.
Yurtiçi Kargo API Entegrasyonu
Yurtiçi Kargo, Türkiye'nin en geniş dağıtım ağlarından birine sahip kargo firmasıdır. Yurtiçi Kargo API'si; gönderi oluşturma, toplu gönderi (manifesto), barkod sorgulama ve iade gönderi oluşturma işlemlerini destekler. API erişimi için Yurtiçi Kargo kurumsal müşteri temsilcinizden UserName, Password ve CustomerNumber bilgilerini almanız gerekmektedir. Yurtiçi Kargo API'si hem XML/SOAP hem de JSON/REST formatlarını destekler; ancak yeni entegrasyonlar için REST tercih edilmektedir.
Aras Kargo API Entegrasyonu
Aras Kargo, özellikle hızlı teslimat ve kapsamlı iade yönetimi altyapısıyla dikkat çeken bir kargo firmasıdır. Aras Kargo API'si REST mimarisi üzerine kuruludur ve JWT tabanlı kimlik doğrulama kullanır. Aras API'sinin öne çıkan özellikleri arasında gerçek zamanlı konum takibi, çoklu paket desteği ve online iade kargo kodu oluşturma yer almaktadır. Gelişmiş webhook desteğiyle gönderi durum değişikliklerinde (teslim edildi, teslim edilemedi, şubede bekliyor) sisteminize anlık bildirim gönderilebilir.
Çoklu Kargo Seçeneği ve Ücret Karşılaştırma
Birden fazla kargo firmasıyla çalışmak, hem operasyonel esneklik hem de maliyet optimizasyonu açısından avantaj sağlar. Çoklu kargo entegrasyonunda; sipariş ağırlığına, boyutuna, teslimat bölgesine ve hız tercihine göre en uygun kargo firması otomatik olarak seçilebilir. Bu seçim mantığını bir "kargo yönlendirme motoru" ile yönetmek mümkündür. Örneğin, İstanbul içi siparişler için MNG veya Yurtiçi, Anadolu'ya siparişler için PTT Kargo, acil siparişler için motorlu kurye servisi tercih edilebilir.
- Desi Hesaplama: (En x Boy x Yükseklik) / 3000 formülüyle volumetrik ağırlık hesaplanır; gerçek ağırlık ile karşılaştırılarak yüksek olan alınır.
- Bölge Bazlı Fiyatlandırma: Kargo firmaları Türkiye'yi bölgelere ayırır; uzak bölgeler için ek ücret uygulanabilir.
- Kapıda Ödeme: COD (Cash on Delivery) seçeneği için kargo API'sinde ayrı parametre gönderilmesi gerekir.
- Sigorta: Yüksek değerli gönderi için API üzerinden sigorta eklenmesi mümkündür.
Webhook ile Otomatik Takip Bildirimi
Kargo API entegrasyonunun en değerli özelliklerinden biri, gönderi durum güncellemelerini webhook aracılığıyla anlık almaktır. Bunu destekleyen kargo firmalarında (Aras, MNG) endpoint tanımlayarak; gönderi teslim edildiğinde, adreste bulunamadığında veya şubede bekletildiğinde sisteminize POST isteği gönderilmesini sağlarsınız. Bu bilgiyi müşteriye SMS, e-posta veya push notification olarak iletmek, müşteri destek taleplerini ve "kargom nerede?" sorularını dramatik biçimde azaltır. Webhook desteklemeyen kargo firmalarında ise belirli aralıklarla polling (yoklama) yaparak durum güncellemelerini manuel olarak çekebilirsiniz.
Sık Sorulan Sorular
Kargo API entegrasyonu için teknik bilgi gerekli mi?
Temel seviyede REST API entegrasyonu bilgisi yeterlidir. WooCommerce veya Shopify gibi hazır platformlar için bu kargo firmalarının eklentileri mevcuttur; özel geliştirme gerekmez. Özel geliştirilmiş sistemlerde ise bir backend geliştirici ile API entegrasyonu ortalama 3-7 günde tamamlanabilir.
Tüm kargo firmalarını tek API üzerinden yönetmek mümkün mü?
Evet, bu amaçla geliştirilmiş kargo entegrasyon platformları mevcuttur. Türkiye'de Kolay Gönderi, Sendeo gibi çok taşıyıcılı (multi-carrier) platformlar; tek bir API ile PTT, MNG, Yurtiçi ve Aras gibi birden fazla kargo firmasına erişim sağlar. Bu yaklaşım entegrasyon maliyetini düşürür ve yönetimi kolaylaştırır.
Otomatik etiket basımı nasıl çalışır?
Kargo API'sinden dönen barkod numarası kullanılarak etiket endpoint'ine istek gönderilir; yanıt olarak PDF veya ZPL formatında etiket dosyası alınır. PDF etiketler standart yazıcılarda basılırken, ZPL formatı termal etiket yazıcılarında doğrudan basım için tasarlanmıştır. Yüksek sipariş hacminde ZPL + termal yazıcı kombinasyonu hız açısından önemli avantaj sağlar.
Kargo ücretlerini müşteriye göstermek için API kullanılabilir mi?
Birçok kargo firması ücret hesaplama (rate query) endpoint'i sunmaktadır. Bu endpoint'e gönderi ağırlığı, boyutu ve teslimat adresi gönderildiğinde tahmini kargo bedeli döner. Bu özelliği ödeme sayfasında anlık kargo ücreti hesaplama için kullanabilirsiniz.
Sonuç
Kargo API entegrasyonu, e-ticaret operasyonlarınızı ölçeklendirmenin ve müşteri deneyimini iyileştirmenin en etkili yollarından biridir. PTT, MNG, Yurtiçi ve Aras API'lerini doğru entegre ederek otomatik etiket basımı, anlık takip bildirimi ve çoklu kargo karşılaştırması gibi güçlü özelliklerden yararlanabilirsiniz. Toserof Tech. olarak e-ticaret entegrasyon projeleriniz için iletişime geçin.