Kargo Entegrasyonu

Kargo entegrasyonu nedir ve neden gereklidir?

Kargo entegrasyonu, e-ticaret veya pazaryeri altyapınızdaki siparişlerin kargo firmasının sistemine otomatik iletilmesi; gönderi (barkod) oluşturma, takip, fiyat/desi sorgulama ve etiket üretimi işlemlerinin manuel giriş olmadan yürütülmesidir. Manuel operasyonda her gönderi için kargo paneline tek tek veri girmek yavaş ve hatalıdır; API entegrasyonu bunu saniyeler içinde, sipariş verisiyle birebir eşleşmiş biçimde yapar. Çok satıcılı pazaryerlerinde bu, satıcı başına ölçeklenen bir operasyon zorunluluğuna dönüşür: yüzlerce satıcının binlerce gönderisi tek akışta yönetilmelidir.

Entegrasyonun üç temel çıktısı vardır: (1) sipariş onaylanınca otomatik gönderi/barkod oluşturma, (2) alıcıya ve panele düşen kargo takip numarası, (3) matbaa/termal yazıcıya gönderilecek PDF etiket. Bu üçü otomatikleştiğinde depo hızlanır, kayıp/yanlış adres oranı düşer ve müşteri sorularının büyük kısmı takip linkiyle kendiliğinden yanıtlanır.

Türkiye’deki kargo API’leri ve protokolleri

Türkiye’de yaygın kargo firmalarının teknik entegrasyon biçimi farklıdır; mimariyi bu farklara göre soyutlamak (ortak bir “gönderi” modeli tanımlayıp her firmaya adaptör yazmak) en sağlıklı yaklaşımdır.

Pazaryeri siparişlerinde kargo çoğu zaman anlaşmalı taşıyıcı ile gelir: Trendyol için TrendyolExpress, Hepsiburada için HepsiJet. Bu senaryoda etiket ve takip numarası kargo firmasından değil, Trendyol Marketplace / Hepsiburada Merchant API’sinden alınır. Kendi sitenizden çıkan gönderilerde ise doğrudan kargo firmasının API’si kullanılır.

Desi hesaplama: formül ve örnekler

Kargo ücreti neredeyse her zaman desi üzerinden faturalanır. Hacimsel ağırlık şu formülle bulunur ve ölçüler santimetre girilir:

Hacimsel ağırlık = (En × Boy × Yükseklik) / 3000

Faturalanan desi, hacimsel ağırlık ile gerçek kilogram ağırlığından büyük olanıdır: desi = max(hacimsel ağırlık, gerçek kg). Böylece hafif ama hacimli ürünler (ör. yastık) ile küçük ama ağır ürünler (ör. dövme demir) doğru fiyatlanır.

Desi hesabını sipariş anında yaparak müşteriye doğru kargo ücretini göstermek ve depoda yanlış paket seçiminden doğan ek maliyeti önlemek mümkündür. Ürün kartında en/boy/yükseklik ve ağırlık alanlarını zorunlu tutmak, bu otomasyonun ön koşuludur.

Gönderi oluşturmadan teslimata: API akışı

Firma değişse de akış benzerdir. Aşağıdaki adımlar ortak bir “gönderi” modeliyle her taşıyıcıya uyarlanabilir:

• 1. Kimlik doğrulama: müşteri kodu + kullanıcı/parola (SOAP) ya da API anahtarı / Bearer token (REST).
• 2. Adres ve desi hazırlığı: alıcı ad-adres-telefon, il/ilçe kodu, hesaplanmış desi.
• 3. Gönderi oluşturma: sipariş numarası referansla iletilir, taşıyıcı bir barkod/takip numarası döner.
• 4. Etiket alma: genellikle base64 kodlu PDF döner; A4 veya termal formatta yazdırılır.
• 5. Takip: takip numarasıyla durum sorgulanır ve alıcıya bildirilir.

Yurtiçi Kargo (SOAP + REST)

ShippingOrderDispatchService üzerinden createShipment çağrısı yapılır. Kritik alanlar: cargoKey (müşteri kodu), invoiceKey (sipariş no), receiverCustName/Address/Phone, desiWeight, orgGeoCode (gönderen il), destGeoCode (alıcı il), cargoType, packagingType ve paymentType (gönderici/alıcı öder). Takip için queryCargo, etiket için printShipmentLabel kullanılır.

Aras Kargo (SOAP)

Aras, XML gövdeli SOAP kullanır. CreateShipment çağrısına gönderen/alıcı bilgileri, PIECE_COUNT, DESI, PAYMENT_TYPE ve SERVICE_TYPE alanlarını içeren bir sipariş XML’i verilir; dönen XML’de TRACKING_NUMBER ve durum bilgisi bulunur. Takip QueryShipment ile yapılır. XML yanıtları güvenli biçimde parse edilmeli, hata (STATUS) alanları kontrol edilmelidir.

MNG Kargo (REST)

MNG, JSON tabanlı REST sunar. Authorization: Bearer başlığıyla /shipments uç noktasına senderInfo, receiverInfo ve shipmentInfo (pieceCount, desi, paymentType: SENDER/RECEIVER, serviceType: NORMAL/EXPRESS) gönderilir. Yanıtta trackingNumber ve barkod döner; toplu etiket için labels/bulk uç noktası base64 PDF verir.

Marketplace anlaşmalı kargo (TrendyolExpress, HepsiJet)

Trendyol siparişlerinde gönderi, Trendyol Partner/Marketplace API üzerinden oluşturulur ve etiket bu API’den çekilir; Hepsiburada’da aynı işlem Hepsiburada Merchant APIve HepsiJet üzerinden yürür. Bu yüzden pazaryeri entegrasyonu ile kargo entegrasyonu tek akışta ele alınmalıdır — sipariş çekildiği anda hangi kanaldan hangi taşıyıcının kullanılacağı belirlenir.

Kargo takibi ve etiket üretimi

Takip, taşıyıcının döndürdüğü takip numarası ile periyodik sorgulanır; durum, güncel şube, son hareket ve tahmini teslimat alınır. İyi bir kurguda bu bilgi müşteri paneline ve sipariş durumuna otomatik yansır (ör. “yola çıktı”, “dağıtımda”, “teslim edildi”). Etiketler çoğu firmada base64 PDF olarak gelir; tek tek ya da toplu (bulk) alınıp termal/A4 yazdırılır. Depoda toplu etiket, gün sonunda yüzlerce gönderiyi tek dosyada basmayı sağlar.

Kargo maliyeti ve optimizasyon

Tek gönderinin maliyeti şu şekilde modellenir:

Gönderi maliyeti = desi × desi birim fiyatı + sabit hizmet ücreti

Aşağıdaki desi birim fiyatı aralıkları temsilidir; gerçek fiyat firmanın sizinle yaptığı sözleşmeye, aylık hacme ve destinasyona göre belirlenir. Güncel tarife için ilgili kargo firmasıyla anlaşma yapılmalıdır.

Maliyet optimizasyonu için pratik kaldıraçlar:

• Hacim indirimi: aylık 1.000+ gönderide firmayla oran pazarlığı yapın.
• Çoklu taşıyıcı: 2–3 firmayla çalışıp destinasyona göre en ucuzunu API ile seçin.
• Bölgesel yönlendirme: yakın illerde bir firma, uzak/zor illerde başka firma kuralı tanımlayın.
• Doğru desi: yanlış paketleme kaynaklı fazla desiyi ürün ölçülerini standardize ederek önleyin.

Mevzuat: e-İrsaliye ve KVKK

Sevk belgesi elektronik düzenleniyorsa GİB e-İrsaliye formatına uyum gerekir; e-Fatura/ e-Arşiv süreçleriyle birlikte muhasebe otomasyonuna bağlanır. Alıcının ad, adres ve telefon bilgisi 6698 sayılı KVKK kapsamında kişisel veridir: yalnızca gönderiyi tamamlamak için, amaçla sınırlı işlenmeli, kargo firmasına aktarımı için gerekli aydınlatma ve gizlilik şartları sağlanmalı, saklama süreleri tanımlanmalıdır. Pazaryeri işletiyorsanız aracılık faaliyeti 6563 sayılı Elektronik Ticaretin Düzenlenmesi Hakkında Kanun ve ETBİS kaydı çerçevesinde yürütülür.

Uygulama kontrol listesi

• Ürün kartında en/boy/yükseklik ve ağırlık alanlarını zorunlu yapın (desi için ön koşul).
• Ortak “gönderi” modeli tanımlayıp her taşıyıcıya adaptör yazın; tek firmaya kilitlenmeyin.
• Sipariş onayında otomatik barkod, takip numarası ve toplu etiket üretimini kurun.
• Takip durumunu sipariş durumuna ve müşteri bildirimlerine bağlayın.
• e-İrsaliye ve KVKK uyumunu; pazaryeri kanalında Trendyol/Hepsiburada API kargo akışını kapsayın.

Kargo ile birlikte fatura otomasyonunu tek çözümde birleştirmek için kargo + e-fatura entegrasyon çözümümüze bakın; ihtiyacınıza özel bir kurulum için talep formunu doldurun. Gelir tarafını komisyon yönetimi ve tahsilatı ödeme sistemleri yazılarımızda ele alıyoruz.