Kargo entegrasyonu nasıl kurulur?

Kargo entegrasyonu tanıtımlarda tek cümleye indirgenir: “kargonuzu panelden çağırın, takip edin.” İşin zor kısmı bu cümlede görünmez. Zorluk, yedi kargo firmasının aynı işi yedi farklı biçimde yapması ve hatalarını farklı yollarla bildirmesidir. Aşağıdaki başlıklar, iki firmanın kendi test ortamına karşı yapılan ölçümlerden çıkarıldı.

Barkodu kim üretir — simetrik değil

Bir kargo entegrasyonunda ilk kararlaştırılması gereken şey budur. Yurtiçi Kargo modelinde takip anahtarını siz üretirsiniz: gönderiye kendi referansınızı verir, firma onu aynen geri döndürür. Aras Kargo modelinde ise barkodu firma üretir; siz yalnız kendi entegrasyon kodunuzu geçersiniz ve karşılığında firmanın anahtarını alırsınız.

Fark akademik değil: ilk modelde referansı siz saklamazsanız gönderiyi bir daha bulamazsınız; ikinci modelde firmanın döndürdüğü anahtarı kaydetmezseniz takip edemezsiniz. Tek bir koda iki modeli birden sığdırmaya çalışan entegrasyonlar genellikle birinde takip numarasını sessizce kaybeder.

Şema “isteğe bağlı” diyorsa da zorunlu olabilir

Ölçülmüş bir örnek: Yurtiçi Kargo’nun servis tanımında (WSDL) irsaliye anahtarı minOccurs="0" ile isteğe bağlı görünür. Alan gönderilmediğinde servis gönderiyi reddediyor ve yalnızca “Hata Oluştu!!!” diyor — hangi alanın eksik olduğunu söylemiyor.

Bu, entegrasyonlarda en pahalı hata sınıfıdır: şemaya bakarak yazılan kod derlenir, testleri geçer ve canlıda anlaşılmaz bir mesajla durur. Tek çare, şemaya değil gerçek servise sormaktır.

Alan sınırları dokümanda değil, cevapta yazar

Aynı serviste ölçülen kurallar: alıcı adı en az 5 en çok 200 karakter, adres en az 10 en çok 500 karakter, telefon tam 10 hane. Bunların hiçbiri baştan bilinmiyordu; her biri servise geçersiz bir değer gönderilip dönen hata kodu okunarak çıkarıldı.

Doğru davranış, bu kuralları istekten önce uygulamaktır. Aksi hâlde operatör panelde anlamsız bir hata görür ve hatanın hangi alandan geldiğini tahmin etmeye çalışır.

İl ve ilçe doğrulanmıyor

Beklenenin aksine kargo firmaları adres alanlarını doğrulamıyor. Ölçümde uydurma bir il adıyla gönderi oluşturulabildi ve servis başarılı yanıt verdi. Yanlış yazılmış bir ilçe, gönderi oluşturulurken değil, paket yanlış aktarma merkezine gittiğinde fark edilir.

Yani il/ilçe doğrulaması gönderen tarafın işidir. Panelin müşteri kayıtlarındaki adresi serbest metin olarak taşıması bu yüzden yeterli değildir; kargo çağrılırken il ve ilçe ayrı ayrı seçilmelidir.

Hata nereden okunur: HTTP kodu yetmez

Üç firmada üç farklı davranış ölçüldü. Yurtiçi Kargo başarılı bir yanıtın içinde outFlag=1 ile hata bildiriyor — HTTP durumu 200. Aras Kargo kimlik hatasını HTTP 500 ve bir SOAP hata bloğuyla veriyor. PTT ve Sürat Kargo’da kimlik hatası yine HTTP 200 ile, gövdedeki bir bayrakla geliyor.

Sonuç: HTTP durum koduna bakarak karar veren bir entegrasyon, Aras’ta yanlış şifreyi “geçici sunucu hatası” sanıp sonsuza kadar tekrar dener; Yurtiçi’nde ise hiç oluşmamış bir gönderiyi başarılı sayar.

“Gitti mi bilmiyorum” bir cevaptır

İstek gönderildikten sonra bağlantı koparsa gönderi karşı tarafta oluşmuş olabilir. Bu durumu “başarısız” saymak ve yeniden denemek ikinci bir kargo çağırır — ikisi de faturalandırılır.

Doğru davranış belirsizliği saklamaktır: kayıt “belirsiz” işaretlenir, referans numarası gösterilir ve kargo firmasının kendi panelinden teyit edilmesi istenir. Yanlış “gitmedi” kararı para kaybettirir; yanlış “belirsiz” kararı yalnız bir kaydı bekletir. İkincisi ucuzdur.

Etiket formatı yazıcınızı belirler

Aras Kargo tek çağrıda dört formatı birden veriyor: PNG, Zebra ZPL, Zebra EPL ve PDF. Yurtiçi’nde etiket ayrı bir servis çağrısında ve yalnız ZPL. PTT yalnız EPL veriyor. Termal yazıcıların çoğu ZPL ya da EPL konuşur ve ikisi birbirinin yerine geçmez.

Bu yüzden “kargo entegrasyonu var” cümlesi tek başına bir şey söylemez; etiketin hangi formatta geldiği, deponuzdaki yazıcıyla birlikte sorulmalıdır.