E-ticaret ve operasyon yazılımlarında kargo entegrasyonu ödeme kadar kritik bir parçadır. Sipariş alındıktan sonra gönderi oluşturma, etiket basma, takip numarası saklama, teslimat durumunu güncelleme ve iade sürecini yönetme akışları doğru kurulmazsa müşteri deneyimi hızla bozulur.
Bu rehber, API Deposu'ndaki Yurtiçi Kargo API, MNG Kargo API, HepsiJet API ve ShipEntegra kayıtlarını ürün mimarisi ve operasyon riski açısından karşılaştırır.
Hızlı karşılaştırma
| API | En iyi kullanım | Kimlik doğrulama | Not |
|---|---|---|---|
| Yurtiçi Kargo | Kurumsal SOAP kargo entegrasyonu | SOAP kullanıcı/şifre | Kurumsal sözleşme gerekir |
| MNG Kargo | REST tabanlı modern kargo akışları | API Key | Sandbox sinyali var |
| HepsiJet | Hızlı teslimat ve Hepsiburada ekosistemi | Token | Kurumsal erişim gerekebilir |
| ShipEntegra | Çoklu taşıyıcı yönetimi | API Token | Tek arayüzden carrier yönetimi |
Shipment modeli kurun
Kargo entegrasyonunda ilk yapılması gereken şey, sağlayıcıdan bağımsız bir gönderi modeli oluşturmaktır. shipmentId, orderId, carrier, trackingNumber, labelUrl, status, lastStatusAt ve rawCarrierPayload gibi alanlar temel ihtiyaçları karşılar.
Bu model olmadan her taşıyıcı UI'a farklı veri basar. Bir taşıyıcı barkodu farklı döndürür, biri takip numarasını ayrı alanda verir, biri teslimat durumunu Türkçe metinle gönderir. Ortak model, bu farkları backend içinde tutar.
SOAP ve REST farkı
Yurtiçi Kargo gibi SOAP tabanlı akışlarda WSDL, XML ve kurumsal erişim süreçleri modern REST API'lere göre daha fazla operasyon yükü getirir. Bu kötü olduğu anlamına gelmez; sadece adapter katmanının daha dikkatli yazılması gerekir.
MNG Kargo gibi REST tabanlı yaklaşımlar geliştirici deneyimi açısından daha hızlı olabilir. Ancak REST olması tek başına entegrasyonu kolay yapmaz. Adres doğrulama, desi/ağırlık, teslimat şubesi, etiket formatı ve iade kuralları yine iş kuralı olarak modellenmelidir.
Çoklu taşıyıcı ne zaman gerekir?
Tek taşıyıcıyla başlayan ürünler genellikle daha hızlı canlıya çıkar. Ancak sipariş hacmi büyüdükçe bölgeye göre taşıyıcı seçimi, fiyat optimizasyonu, teslimat hızı, iade kolaylığı ve kapasite gibi konular önem kazanır. Bu noktada ShipEntegra gibi çoklu taşıyıcı katmanı veya kendi carrier abstraction'ınız anlamlı hale gelir.
Çoklu taşıyıcı seçerken karar motorunu açık modelleyin. Hangi şehirde hangi taşıyıcı seçilecek, büyük paketler nasıl yönlenecek, aynı gün teslimat hangi koşulda aktif olacak ve başarısız taşıyıcı çağrısında fallback ne olacak sorularına cevap verilmelidir.
Takip ve müşteri iletişimi
Takip durumu kullanıcıya güven verir. Ancak her taşıyıcı durum metinlerini farklı isimlendirebilir. Bu yüzden carrier status değerlerini uygulama içinde created, in_transit, out_for_delivery, delivered, failed, returned gibi sınırlı bir sete çevirmek gerekir.
Kullanıcıya SMS veya e-posta gönderiyorsanız takip linkinin doğru taşıyıcıya ait olduğundan emin olun. Aynı siparişte birden fazla paket varsa kullanıcıya tek takip numarası yerine paket bazlı bilgi göstermek daha doğru olur.
İade ve teslimat dışı durumlar
Kargo entegrasyonlarında sadece başarılı teslimat akışını modellemek eksik kalır. Alıcı adreste bulunamadı, paket şubeye döndü, hasarlı teslimat, iade başlatıldı, barkod üretildi ama teslim edilmedi gibi durumlar ayrı statüler ister. Bu statüler sipariş ekranı, müşteri bildirimi ve muhasebe akışını etkiler.
İade sürecinde carrier response'u ile ürün iade kaydı birbirinden ayrılmalıdır. Kargonun iade hareketi başlamış olması, ürünün depoya kabul edildiği anlamına gelmez. Bu ayrım yapılmazsa stok yanlış artabilir veya kullanıcıya erken iade onayı verilebilir.
SLA ve destek notu
Taşıyıcı API'si çalışmadığında sipariş sevkiyatı durabilir. Bu yüzden manuel fallback planı gerekir: panelden barkod üretme, CSV export, taşıyıcı portalına manuel giriş veya geçici carrier değişimi. Teknik entegrasyon ne kadar iyi olursa olsun operasyonun çalışmaya devam edebilmesi gerekir.
Bu fallback planı yazılı değilse ilk API kesintisinde ekip panikle karar verir. Kargo, müşteri memnuniyetine doğrudan dokunduğu için bu plan ürün dokümantasyonunun parçası olmalıdır.
İlgili API Deposu kayıtları
Kaynaklar
Sık Sorulan Sorular
›Kargo API entegrasyonunda ilk hangi akış yapılmalı?
Önce gönderi oluşturma, barkod/etiket üretimi ve takip numarası eşleştirme akışları kurulmalıdır. Teslimat durumu ve iade akışları sonraki aşamada eklenebilir.
›SOAP tabanlı kargo API'leri hâlâ kullanılmalı mı?
Eğer taşıyıcı sadece SOAP sağlıyorsa kullanılabilir, ancak adapter katmanı şarttır. Uygulama kodu SOAP detaylarını bilmemeli, kendi shipment modeliyle çalışmalıdır.
›Tek taşıyıcı mı çoklu taşıyıcı mı daha iyi?
Düşük hacimde tek taşıyıcı daha basittir. Hacim, bölge ve teslimat seçenekleri arttıkça ShipEntegra gibi çoklu taşıyıcı katmanı veya kendi carrier abstraction'ınız daha değerli olur.
›Kargo takip webhook ile mi polling ile mi yapılmalı?
Taşıyıcı destekliyorsa webhook daha verimlidir. Destek yoksa takip numarası bazlı polling yapılabilir, ancak aralık ve retry politikası dikkatle ayarlanmalıdır.
