Bir e-ticaret sitesi belli bir sipariş hacmine ulaştığında, kargo süreçlerini elle yönetmek en çok zaman kaybettiren ve en çok hata üreten işlerden biri haline gelir. Her siparişi tek tek kargo firmasının panelinden açmak, takip numarasını kopyalayıp müşteriye e-posta atmak, barkodu yazıcıdan çıkarmak günde 30 siparişte bile saatlerinizi alır. İşte tam bu noktada e-ticaret kargo entegrasyonu devreye girer: sipariş onaylandığı anda kargo kaydı otomatik açılır, takip numarası müşteriye gider ve barkod hazır olur.
Bu yazıda Aras, PTT ve MNG kargo firmalarıyla otomatik bağlantının nasıl kurulduğunu, bu entegrasyonun hosting tarafında nelere ihtiyaç duyduğunu ve sahada en sık karşılaşılan sorunları ele alıyoruz.
Kargo Entegrasyonu Tam Olarak Ne İşe Yarar?
Kargo entegrasyonu, e-ticaret sitenizin (WooCommerce, OpenCart, Ticimax, IdeaSoft, özel yazılım vb.) kargo firmasının sistemiyle API üzerinden konuşmasıdır. Manuel süreçle entegre süreç arasındaki fark net:
| İşlem | Manuel Yöntem | Otomatik Entegrasyon |
|---|---|---|
| Kargo kaydı açma | Firma panelinden tek tek | Sipariş onayında otomatik |
| Takip numarası | Elle kopyala-yapıştır | Siparişe anında işlenir |
| Müşteri bildirimi | Manuel e-posta/SMS | Otomatik tetiklenir |
| Barkod/etiket | Tek tek indir | Toplu yazdırma |
| Teslimat durumu | Firma sitesinden sorgula | Webhook ile güncellenir |
Bir API entegrasyonunda iki yön vardır. Giden yön: siteniz kargo firmasına "şu adrese, şu ağırlıkta bir gönderi oluştur" der ve karşılığında bir takip (barkod) numarası alır. Gelen yön: kargo firması "bu gönderi dağıtıma çıktı / teslim edildi" bilgisini sitenize bildirir. İkinci yön genelde periyodik sorgulama (polling) ya da firmanın gönderdiği bildirim (webhook) ile çalışır.
Aras, PTT ve MNG Arasındaki Teknik Farklar
Üç firma da entegrasyon imkânı sunar ama altyapıları ve başvuru süreçleri birbirinden farklıdır.
Aras Kargo
Aras, Türkiye'de e-ticaret entegrasyonu en yaygın firmalardan biridir. Genellikle SOAP tabanlı web servisi sunar; gönderi oluşturma, sorgulama ve iptal işlemleri için ayrı servis adresleri vardır. Entegrasyon için Aras'tan bir müşteri kodu, kullanıcı adı ve şifre almanız gerekir. Bu bilgileri kurumsal müşteri temsilciniz veya entegrasyon ekibi sağlar.
PTT Kargo
PTT, kamu altyapısı olduğu için başvuru süreci biraz daha resmidir ancak entegrasyon servisi mevcuttur. PTT'nin barkod üretimi kendi sisteminden alınan numara aralıklarıyla çalışabildiği için, kurulumda barkod serisi tanımlaması önemlidir. Bazı durumlarda PTT entegrasyonu pazaryeri/altyapı sağlayıcısı üzerinden yapılır.
MNG Kargo
MNG, daha modern bir yaklaşımla REST/JSON API ve token tabanlı kimlik doğrulama sunan firmalardandır. Token alıp her isteğe eklemeniz, ardından gönderi oluşturma uç noktasına JSON göndermeniz gerekir. REST yapısı, özel yazılım geliştirenler için genelde daha kolay test edilir.
Önemli not: Üç firmanın da API dokümanları ve uç noktaları zaman zaman güncellenir. Entegrasyona başlamadan önce mutlaka firmadan güncel teknik dokümanı ve test (sandbox) ortamı bilgilerini isteyin. Canlı ortamda gerçek gönderi oluşturmadan önce test ortamında doğrulama yapmak, yanlış adrese gerçek barkod basılmasını önler.
Entegrasyonu Kurmadan Önce: Hosting Tarafı Gereksinimler
Kargo entegrasyonu "sadece kargo firmasıyla ilgili" sanılır ama büyük kısmı hosting ve sunucu tarafındadır. Çünkü API çağrıları sizin sunucunuzdan çıkar ve gelen bildirimler sizin sunucunuza ulaşır. İhtiyaç duyacaklarınız:
- Giden bağlantı (outbound) izni: Sunucunuzun kargo firmasının API adreslerine 443/80 portundan erişebilmesi gerekir. Bazı paylaşımlı hosting paketlerinde
cURLveyaallow_url_fopenkapalı olabilir; bunlar açık olmalıdır. - Güncel PHP sürümü ve eklentiler: SOAP servisleri için
php-soap, JSON API'ler içinphp-curlvephp-jsoneklentileri kurulu olmalıdır. PHP 8.x, hem performans hem güvenlik açısından önerilir. - Güvenilir SSL: Hem sizin sitenizin hem de API isteklerinin güvenli (HTTPS) çalışması şarttır. Sertifika doğrulamasını "kapatarak" sorun çözmek yerine geçerli bir sertifika kullanın.
- Webhook için erişilebilir URL: Kargo firması teslimat durumunu size bildirecekse, dışarıdan erişilebilen bir uç noktanız (örneğin
siteniz.com/kargo/webhook) olmalı ve bu adresin önünde IP kısıtlaması/imza doğrulaması bulunmalıdır. - Yeterli kaynak: Toplu barkod üretimi ve durum sorgulamaları, yoğun günlerde (kampanya dönemleri) ek CPU ve bellek tüketir. Paylaşımlı pakette kaynak limitine takılıyorsanız, kontrol panelinizden (DirectAdmin veya Plesk) kaynak kullanımınızı izleyin.
API anahtarlarını asla kaynak kodun içine düz metin olarak yazmayın. Bunları sunucudaki ortam değişkenlerinde (.env dosyası gibi) veya yazılımınızın güvenli ayar alanında saklayın ve bu dosyaların web üzerinden erişilemediğinden emin olun.
Adım Adım Otomatik Bağlantı Kurulumu
Hangi firmayı seçerseniz seçin, genel akış birbirine benzer. Tipik bir WooCommerce veya OpenCart kurulumunda süreç şöyle ilerler:
- Sözleşme ve API erişimi alın. Kargo firmasıyla kurumsal/e-ticaret sözleşmesi yapın ve entegrasyon için API bilgilerinizi (kullanıcı adı, şifre, müşteri kodu veya token) edinin.
- Entegrasyon eklentisini/modülünü kurun. WooCommerce için ilgili kargo eklentisini, OpenCart için modülü yükleyin; özel yazılımda firmanın SDK'sını veya kendi API istemcinizi entegre edin.
- Bilgileri test ortamında girin. API bilgilerinizi önce sandbox/test moduna girin. Gerçek bir gönderi yerine test gönderisi oluşturup barkod dönüp dönmediğini doğrulayın.
- Sipariş–kargo eşleştirmesini yapın. Sipariş durumlarını tanımlayın: hangi durumda (ör. "hazırlanıyor" → "kargoya verildi") otomatik kayıt açılacağını belirleyin.
- Barkod ve etiket çıktısını test edin. Termal yazıcı kullanıyorsanız etiket boyutunun (genelde 10x10 cm) doğru bastığından emin olun.
- Müşteri bildirimini bağlayın. Takip numarası siparişe işlendiğinde müşteriye otomatik e-posta/SMS gitmesini sağlayın.
- Canlıya alın ve ilk günleri izleyin. İlk gerçek siparişlerde adres, ağırlık ve desi bilgilerinin doğru gittiğini kontrol edin.
Sık Yapılan Hatalar ve Çözümleri
Sahada en çok karşılaşılan sorunlar genelde küçük ama maliyetli olur:
- Desi/ağırlık bilgisi gönderilmiyor: Ürünlerinizde ağırlık ve boyut tanımlı değilse, kargo firması varsayılan değerle kayıt açar ve fiyatlandırma yanlış çıkar. Ürün kartlarında desi bilgisini eksiksiz girin.
- Adres alanları taşıyor: Bazı API'ler il/ilçe için belirli kodlar bekler. Serbest metin il adı (örneğin "Istanbul" yerine plaka kodu) hata verirse, firmanın il/ilçe kod listesini eşleştirmeniz gerekir.
- Zaman aşımı (timeout) hataları: Sunucunuz API'ye ulaşamıyorsa veya cevap geç geliyorsa istek başarısız olur. Bu çoğunlukla giden bağlantı engeli veya yetersiz
max_execution_timekaynaklıdır. Hosting ortamınızın bu çağrılara izin verdiğinden emin olun. - Mükerrer kayıt: Aynı sipariş için iki kez kayıt açılırsa çift barkod oluşur. Entegrasyonunuzda "bu sipariş için kayıt zaten açıldı mı" kontrolü (idempotency) olmalıdır.
- Token süresinin dolması: REST tabanlı entegrasyonlarda (örneğin MNG) token belirli süre sonra geçersiz olur. Yazılımınız token süresi dolduğunda otomatik yenileme yapmalıdır; aksi halde gönderiler aniden başarısız olur.
Bu hataların büyük çoğunluğu test ortamında 1-2 deneme gönderisiyle yakalanabilir. Doğrudan canlıya geçip ilk hatayı gerçek müşteri siparişinde görmek, hem zaman hem itibar kaybettirir.
Birden Fazla Kargo Firmasını Aynı Anda Kullanmak
Çoğu işletme tek bir firmaya bağlı kalmaz; bölgeye, ağırlığa veya müşteri tercihine göre çoklu kargo sunar. Bu durumda her firma için ayrı API bilgisi tanımlanır ve siparişin hangi firmayla gideceğine dair kurallar belirlenir. Örneğin uzak bölgelere PTT, hızlı teslimat isteyen şehir içi siparişlere MNG, ağır gönderilere Aras gibi. Çoklu yapı, sunucunuzun aynı anda birden fazla servisle konuşması demektir; bu da kaynak yönetimini ve hata günlüklerini (log) takip etmeyi daha da önemli kılar.
Hostmana ile Sağlam Bir E-Ticaret Altyapısı
Kargo entegrasyonu ne kadar iyi yazılmış olursa olsun, altında çalıştığı sunucu giden API çağrılarını engelliyorsa, PHP eklentileri eksikse veya yoğun günlerde kaynak limitine takılıyorsa entegrasyon çalışmaz. Hostmana'nın e-ticaret odaklı hosting paketleri güncel PHP sürümleri, gerekli eklentiler ve giden bağlantı izinleriyle birlikte gelir; daha yüksek hacimli mağazalar için sanal sunucu çözümlerimiz tam kaynak kontrolü sunar. SSL durumunuzu, DNS kayıtlarınızı ve site hızınızı kontrol etmek için ücretsiz web araçlarımızı kullanabilir, kurulum adımları için bilgi bankamıza göz atabilirsiniz. Entegrasyon sırasında sunucu tarafında takıldığınız bir nokta olursa destek ekibimize ulaşmaktan çekinmeyin — kargo entegrasyonunuzun pürüzsüz çalışması için altyapı tarafını birlikte hallederiz.
<!--silo-start-->📚 İlgili Rehberler
Ana rehber: 2026'da Hosting Nasıl Seçilir? Yeni Başlayanlar İçin 7 Adımlı Karar Rehberi
İlgili yazılar:
<!--silo-end-->