E-Ticaret Sitesine Kargo Entegrasyonu Nasıl Yapılır? Sürat Kargo Örneğiyle Adım Adım

Sipariş panelde "hazırlanıyor" diye bekliyor. Depodaki arkadaş kargo firmasının ekranını açıyor, alıcının adını, adresini ve telefonunu tek tek yazıyor, çıkan barkodu yazdırıyor, sonra takip numarasını kopyalayıp müşteriye gönderiyor. Günde birkaç siparişte bu idare eder. Sipariş arttıkça yanlış yazılan ilçeler, aynı siparişe iki kez açılan gönderiler ve "kargom nerede" soruları da artar. Kargo entegrasyonu bu el işini siteye devretmektir.

Bu yazıda kargo entegrasyonu nasıl yapılır sorusunu bir geliştirici gözüyle, adım adım anlatıyoruz. Örnek olarak Sürat Kargo'yu kullanıyoruz, çünkü sitemizde adını verdiğimiz entegrasyonlardan biri. Mantık diğer kargo firmalarında da büyük ölçüde aynıdır. Değişen, firmanın servis yapısı ve alan isimleridir.

Kargo entegrasyonu tam olarak ne yapar?

Kargo entegrasyonu, e-ticaret siteniz ile kargo firmasının sistemi arasında kurulan bir köprüdür. Temelde dört iş yapar:

• Gönderi oluşturma: Sipariş kargoya hazır olduğunda alıcı ve paket bilgileri kargo firmasına otomatik gider.
• Barkod ve etiket: Kargo firmasının verdiği barkod panelden yazdırılır ve pakete yapıştırılır.
• Takip numarası: Gönderinin takip bilgisi siparişe kaydedilir ve müşteriye iletilir.
• Durum güncelleme: "Yolda", "dağıtımda", "teslim edildi" gibi hareketler siteye geri döner.

API kavramına yabancıysanız önce API entegrasyonu nedir yazımıza göz atabilirsiniz.

Adım 1: Sözleşme ve entegrasyon bilgileri

Kod yazmadan önce kargo firmasıyla bir sözleşmeniz ve cari hesabınız olmalı. Sürat Kargo'da entegrasyon bilgileri şube ya da entegrasyon ekibi üzerinden isteniyor. Yayınlanmış entegrasyon notlarına göre bu bilgiler kabaca şunlar:

• Cari kodu ve servis şifresi: Gönderi oluşturmak için kullanılır, kargo firması verir.
• Web servis şifresi: Takip sorgularında kullanılır. Sürat'ın müşteri panelinde profil bölümünden tanımlanıyor.
• Ödeme tipine göre hesaplar: Gönderici ödemeli, alıcı ödemeli ve kapıda tahsilatlı gönderiler ayrı hesap gerektirebilir. Başvururken hangilerini kullanacağınızı belirtin.

Bu bilgiler bir API anahtarı gibidir. Kodun içine, Git deposuna ya da tarayıcıya giden JavaScript'e yazılmaz. Sunucuda ortam değişkeninde ya da şifreli bir ayar alanında tutulur, panelde de yalnızca yetkili kullanıcı görür.

Adım 2: Güncel dokümanı ve test ortamını edinin

Sürat Kargo'nun web servisi SOAP, yani XML tabanlı bir servistir. Canlı ortamdan ayrı bir test (prova) ortamı da vardır. Bu iki bilgi işin nasıl yazılacağını doğrudan etkiler:

• SOAP servislerde istekler XML zarfıyla gider. PHP'de SoapClient ya da benzeri bir kütüphaneyle çalışılır. REST ve JSON alışkanlığıyla yazılmış kod doğrudan işe yaramaz.
• Test ortamında açılan gönderiler gerçek bir kargo süreci başlatmaz. Bütün senaryoları canlıya geçmeden burada denersiniz.

Kargo firmasından güncel dokümanı mutlaka isteyin. İnternette dolaşan eski PDF'ler ve açık kaynak kütüphaneler fikir verir, ama servis adresleri ve alan isimleri zamanla değişebilir. Ezbere değil, dokümana göre yazılan kod sonradan daha az sürpriz çıkarır.

Adım 3: Sipariş verisini kargonun diline çevirin

Entegrasyonun en çok zaman alan kısmı çoğu zaman API çağrısı değil, verinin temizlenmesidir. Sürat'ın gönderi oluşturma servisi alıcı adını, açık adresi, il ve ilçeyi ayrı alanlar olarak, telefon bilgisini, paket adedini, desi ve kilo bilgisini, kapıda ödemeli gönderide de tahsil edilecek tutarı ister. Bu yüzden sitenizin ödeme adımında şunlara dikkat edin:

• İl ve ilçe seçmeli olsun. Serbest metin alanı "Kadıköy/ist" gibi girişlere açıktır. Bu da kargo tarafında hata ya da yanlış şube demektir.
• Telefon tek bir formatta saklansın. Başında 0, +90, boşluk ya da parantez olan numaralar gönderimden önce aynı biçime getirilmeli.
• Ürünlerde desi ve ağırlık alanı olsun. Bu alanlar yoksa her pakete aynı değer gider, sonra faturada fark çıkar.
• Türkçe karakterleri test edin. Ş, ğ ve İ gibi harflerin etikette bozulmadığından emin olun.

Kendi sipariş kodunuzu gönderin

Sürat'ın servisi, gönderiyle birlikte sizin belirlediğiniz özel bir takip ya da sipariş kodunun gönderilmesine izin veriyor. Bu kodu her sipariş için benzersiz tutun. Takip sorgularını sonradan bu kodla yaparsınız, aynı siparişe ikinci bir gönderi açılmasını da bu kodla engellersiniz.

Adım 4: Gönderi oluşturma, barkod ve etiket

Gönderi oluşturmayı bir sipariş durumuna bağlamak en sağlıklısıdır. Örneğin sipariş "kargoya hazır" durumuna alındığında gönderi açılır. Biz şu sırayı izliyoruz:

1. Sipariş kilitlenir, böylece aynı anda ikinci bir gönderi isteği çıkmaz.
2. Veri kargo formatına çevrilir ve zorunlu alanlar kontrol edilir.
3. İstek gönderilir. Giden istek ve dönen yanıt loglanır.
4. Yanıt başarılıysa barkod ve takip bilgisi siparişe yazılır, etiket panelden yazdırılabilir hale gelir.
5. Hata dönerse sipariş "kargo hatası" durumuna alınır ve hata mesajı personelin anlayacağı şekilde panelde gösterilir.

Etiket için yazıcınızı baştan konuşun. Termal etiket yazıcısı mı, A4 mü kullanılacak? Etiket ölçüsü ne? Barkod okutulabiliyor mu? Bunları test aşamasında depodaki gerçek yazıcıyla denemek gerekir.

Adım 5: Sipariş durumlarını eşleyin

Kargo firmasının hareket isimleri ile sitenizdeki sipariş durumları aynı değildir. Bu yüzden bir eşleme tablosu kurulur. Aşağıdaki tablo genel bir örnektir. Sol sütunun birebir karşılığını firmanın dokümanından almanız gerekir.

Adım 6: Takip için webhook mu, periyodik sorgu mu?

Bazı servisler gönderinin durumu değiştiğinde sitenize kendisi haber verir. Buna webhook denir. Sürat Kargo'nun herkese açık servis listesinde ise sorgu tipi takip servisleri görünüyor: sipariş kodu ya da takip numarasıyla hareket detaylarını siz istersiniz. Sözleşmenize özel bir bildirim seçeneği olup olmadığını entegrasyon ekibine sormakta fayda var. Yoksa çözüm periyodik sorgudur:

• Zamanlanmış bir görev (cron) belirli aralıklarla yalnızca açık gönderileri sorgular. Teslim edilen ya da iadesi tamamlanan siparişler listeden çıkar.
• Sorgu sıklığını firmanın kabul ettiği sınırlara göre ayarlayın. Her dakika yüzlerce sorgu atmak hem gereksizdir hem de erişimin kısıtlanmasına yol açabilir.
• Durum değiştiyse sipariş güncellenir, gerekiyorsa müşteriye e-posta ya da SMS gider.

Adım 7: İptal ve iade senaryoları

Müşteri siparişi kargo teslim almadan iptal edebilir, adres değişebilir, paket geri dönebilir. Sürat'ın servis listesinde gönderiyi geri çekme ve iade gönderileri için ayrı işlemler bulunuyor. Panelde "gönderiyi iptal et" butonu olacaksa, hangi aşamaya kadar iptalin mümkün olduğunu firmayla netleştirin. İptal edilen gönderinin barkodunun tekrar kullanılmadığından da emin olun.

Sık yapılan hatalar

• Doğrudan canlıda denemek: Test ortamı varken canlıda deneme gönderisi açmak, iptal etmeyi unuttuğunuzda gereksiz bir gönderi kaydı demektir.
• Hata mesajını yutmak: "Bir hata oluştu" yazan bir ekran depodaki kimseye bir şey söylemez. Kargo firmasından dönen mesaj panelde okunabilmelidir.
• Yeniden deneme kurmamak: Kargo servisi birkaç dakika yanıt vermediğinde sipariş kaybolmamalı. Bir kuyruk ve yeniden deneme mekanizması şarttır.
• Aynı siparişe iki gönderi açmak: Butona iki kez basılması ya da zaman aşımından sonra tekrar denenmesi, kontrol yoksa iki barkod demektir.
• Şifreyi koda gömmek: Şifre değiştiğinde kodu yeniden yüklemek gerekir. Üstelik kaynak koduna erişen herkes şifreyi görür.

Hazır modül mü, özel entegrasyon mu?

Hazır bir e-ticaret altyapısı kullanıyorsanız ve kargo modülü akışınıza uyuyorsa, sıfırdan yazmanın anlamı yok. Özel entegrasyon şu durumlarda mantıklıdır: birden fazla deponuz varsa, kapıda ödeme ya da parçalı gönderi gibi kurallarınız varsa, kargo bilgisinin ERP'ye veya muhasebeye de gitmesi gerekiyorsa ya da siteniz zaten özel yazılımsa.

Biz bu bağlantıları API entegrasyonu hizmeti kapsamında PHP ile kuruyoruz. Önce test ortamında deniyor, her çağrıyı logluyor, sonra canlıya alıyoruz. Giyim mağazalarında beden, stok ve iade tarafının kargoyla nasıl birleştiğini de giyim e-ticaret sitesi sayfasında anlattık.

Siparişlerinizi hâlâ elle kargoya giriyorsanız akışınızı birlikte konuşalım. İletişim sayfasından bize yazın. Hangi adımın otomatikleşebileceğini, hangisine hiç gerek olmadığını açıkça söyleyelim.

Sık Sorulan Sorular

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

Evet. Entegrasyon bilgileri bir cari hesaba bağlıdır. Sözleşme olmadan canlı ortamda gönderi açamazsınız.

Sürat Kargo entegrasyonu ne kadar sürer?

Süre sitenizin altyapısına ve kapsama göre değişir. En çok zamanı genellikle entegrasyon bilgilerinin gelmesi, adres verisinin düzenlenmesi ve depoda etiket testi alır. Kapsam netleşince süreyi yazılı olarak veriyoruz.

Birden fazla kargo firmasıyla çalışabilir miyim?

Evet. İyi kurulmuş bir yapıda her kargo firması ayrı bir modül olarak yazılır, sipariş tarafı aynı kalır. Siparişe hangi firmanın atanacağı bölge, desi ya da ödeme tipi gibi kurallara veya personelin seçimine bağlanabilir.

Müşteri takip numarasını nerede görür?

Gönderi oluşturulduğunda takip bilgisi siparişe yazılır. Müşteri bunu sipariş detay sayfasında görür. İsterseniz kargoya verildiğinde e-posta ya da SMS ile de gönderilir.

Kapıda ödemeli gönderiler entegrasyonla çalışır mı?

Sürat'ın gönderi servisinde kapıda tahsilat tipi ve tutarı için alanlar bulunuyor. Ancak tahsilatlı gönderi genellikle ayrı bir hesap gerektiriyor. Başvururken bunu belirtmeniz gerekir.