Kargo Entegrasyonu
Yurtiçi Kargo API Entegrasyonu: Gönderi, Etiket ve Takip
Yurtiçi Kargo API entegrasyonu, siparişi Yurtiçi Kargo'nun web servisine gönderi olarak kaydeder, barkodu basar, takip numarasını ve teslim durumunu sitenize yazar. Shopify uygulamamız yayında; diğer sistemlere özel bağlantı kuruyoruz.
Yurtiçi Kargo API entegrasyonu, hazırlanan siparişi Yurtiçi Kargo sisteminde gönderi olarak açar, barkod etiketini basmanızı sağlar ve kargo hareketlerini siparişinize geri yazar. Gönderi bilgisini kargo ekranına elle girmek, takip bilgisini siparişe kopyalamak ve teslim durumunu tek tek sorgulamak ortadan kalkar.
Yurtiçi Kargo entegrasyonu için iki yol var. Shopify mağazanız varsa App Store'da yayında olan Yurtiçi Kargo Entegrasyonu uygulamamızı kurabilirsiniz. Özel bir site, ERP ya da depo yazılımı kullanıyorsanız Yurtiçi Kargo'nun web servisiyle size özel bağlantı yazarız. Sayfanın sonunda kendi ekibiyle bağlanacak geliştiriciler için istek ve yanıt örnekleri var; tüm kargo firmalarını kapsayan yaklaşımımız kargo entegrasyonu sayfasında.
Yurtiçi Kargo entegrasyonu neleri otomatikleştirir?
- Sipariş, alıcı adı, adres, il, ilçe ve telefon bilgisiyle Yurtiçi Kargo'ya gönderi kaydı olarak bildirilir.
- Gönderiye ait barkod etiketi basılır ve paket şubeye ya da kuryeye bu etiketle verilir.
- İşlem görmedi, teslimatta, teslim edildi gibi durumlar düzenli sorgulanıp siparişe işlenir.
- Kapıda ödemede tahsil edilecek tutar ve tahsilat tipi (nakit ya da kredi kartı) gönderiyle iletilir.
- İşlem görmemiş gönderi iptal edilir. Yurtiçi Kargo'nun iade servisleriyle sipariş için iade kodu da tanımlanabilir.
Shopify için hazır uygulamamız
Yurtiçi Kargo Entegrasyonu uygulamamız Shopify siparişini tek tıkla Yurtiçi Kargo'ya gönderir. Uygulamayı Laravel ile geliştirdik; Shopify tarafında Admin API'nin GraphQL arayüzünü kullanır.
- Siparişten tek tıkla gönderi kaydı ve barkod etiketi
- Takip bilgisinin Shopify siparişine yazılması, kargo hareketlerinin gönderi durumuna işlenmesi
- Siparişteki kargo yönteminin adına göre gönderinin kapıda nakit, kapıda kredi kartı ya da gönderici ödemeli olarak bildirilmesi
- İl ve ilçe adlarının 81 il ve 973 ilçelik referans listeyle eşleştirilip yazım farklarının düzeltilmesi
- Çift tıklama ya da bağlantı kopmasında aynı gönderinin iki kez açılmasını önleyen kilit
Diğer kargo firmaları ve çoklu depo senaryoları için Shopify kargo entegrasyonu, tüm uygulamalarımız için Shopify uygulamalarımız sayfasına bakabilirsiniz.
Özel Yurtiçi Kargo API entegrasyonu ne zaman gerekir?
- Siteniz Shopify dışında, size özel bir altyapıda çalışıyorsa
- Gönderiyi ERP'den ya da depo yazılımından açıyorsanız
- Birden fazla depodan ya da gönderici adresinden çıkış yapıyorsanız
- Pazaryeri ve bayi siparişlerini de aynı ekrandan Yurtiçi Kargo'ya vermek istiyorsanız
Bu durumlarda bağlantıyı uygulamamızdaki mimariyle kurarız: istekler kuyrukta işlenir, her web servis çağrısı kayda geçer, geçici hatalar yeniden denenir. Mimarinin ayrıntısı e-ticaret ve ERP entegrasyonu, ERP tarafındaki belge yapısı ERP entegrasyonu sayfasında. Aras Kargo'yu da kullanıyorsanız Aras Kargo entegrasyonu sayfasına bakın; iki firma aynı ekrandan yönetilebilir.
Yurtiçi Kargo gönderilerinizi siparişe bağlayalım
Siparişlerinizi hangi sistemden yönettiğinizi, günlük gönderi sayınızı ve kapıda ödeme kullanıp kullanmadığınızı yazın; hazır uygulama mı, özel entegrasyon mu gerektiğini söyleyelim.
Yurtiçi Kargo web servisi için geliştirici rehberi
Bu bölüm Yurtiçi Kargo API'sine kendi ekibiyle bağlanacak geliştiriciler için. Alan adları Yurtiçi Kargo'nun web servis dokümanındaki adlardır; sözleşmenize göre ek alanlar tanımlı olabilir. Kavramlara yeniyseniz API nedir yazımız iyi bir başlangıç.
Erişim ve ortamlar
- Servis SOAP tabanlıdır (ShippingOrderDispatcherServices); test ve canlı ortamın WSDL adresleri ayrıdır.
- Kullanıcı adı ve şifre, Yurtiçi Kargo ile yapılan kurumsal sözleşmeye göre verilir. Kapıda ödemeli gönderiler için sözleşmenize bağlı olarak ayrı bir kullanıcı tanımlanabilir.
- İki ortamda da isteğin çıktığı sunucunun IP adresi Yurtiçi Kargo tarafında yetkilendirilmelidir. Sunucu değiştiğinde bağlantı hatası alıyorsanız ilk bakılacak yer burasıdır.
Temel işlemler
| İşlem | Ne yapar | Önemli parametreler |
|---|---|---|
| createShipment | Gönderi kaydı açar | wsUserName, wsPassword, userLanguage, ShippingOrderVO |
| queryShipment | Gönderi durumunu sorgular | keys, keyType, addHistoricalData, onlyTracking, wsLanguage |
| cancelShipment | İşlem görmemiş gönderiyi iptal eder | cargoKeys, userLanguage |
| saveReturnShipmentCode | İade kodu tanımlar | fieldName, returnCode, startDate, endDate |
Dil parametresinin adı createShipment ve cancelShipment'ta userLanguage, queryShipment'ta ise wsLanguage'dır. Dokümanı okurken kolayca gözden kaçar.
Örnek istek ve yanıt
SOAP zarfı ve ad alanları okunabilirlik için çıkarıldı. createShipment isteği:
<createShipment>
<wsUserName>KULLANICI_ADI</wsUserName>
<wsPassword>SIFRE</wsPassword>
<userLanguage>TR</userLanguage>
<ShippingOrderVO>
<cargoKey>1045-1</cargoKey>
<invoiceKey>1045-1</invoiceKey>
<receiverCustName>Örnek Alıcı</receiverCustName>
<receiverAddress>Örnek Mah. Deneme Sok. No 5 Çankaya Ankara</receiverAddress>
<cityName>Ankara</cityName>
<townName>Çankaya</townName>
<receiverPhone1>5321234567</receiverPhone1>
<cargoCount>1</cargoCount>
</ShippingOrderVO>
</createShipment>
Başarılı yanıtın sadeleştirilmiş hali:
<ShippingOrderResultVO>
<outFlag>0</outFlag>
<shippingOrderDetailVO>
<cargoKey>1045-1</cargoKey>
<errCode>0</errCode>
</shippingOrderDetailVO>
</ShippingOrderResultVO>
cargoKey sizin ürettiğiniz, her gönderi için benzersiz anahtardır; sorgu ve iptal bu anahtarla yapılır. Biz sipariş numarasına deneme sırasını ekleriz, böylece iptal edilip yeniden açılan gönderi yeni bir anahtar alır. outFlag 0 olsa da satır bazındaki errCode ayrıca kontrol edilmelidir. Tek kayıt döndüğünde SOAP istemcileri sonucu dizi yerine tek nesne olarak verebilir; ayrıştırıcınız iki durumu da karşılamalıdır.
Durum kodları
queryShipment yanıtı ShippingDeliveryVO içinde, her anahtar için bir shippingDeliveryDetailVO satırı olarak döner. Bulunamayan anahtarlar genel hata olarak değil, satır bazında errCode ile bildirilir.
| operationCode | Kısaltma | Anlamı |
|---|---|---|
| 0 | NOP | Kargo işlem görmemiş |
| 1 | IND | Kargo teslimatta |
| 2 | ISR | İşlem görmüş, faturası düzenlenmemiş |
| 3 | CNL | Kargo çıkışı engellenmiş |
| 4 | ISC | Daha önce iptal edilmiş |
| 5 | DLV | Teslim edilmiş |
| 6 | BI | Fatura şube tarafından iptal edilmiş |
Durumları anahtarları gruplayarak ve aralıklı sorgulayın; aynı gönderiyi çok sık sorgulamak servisin tekrar sorgu kısıtına takılır. Teslim edilen ve iptal olan gönderileri sorgu listesinden çıkarın.
Kapıda ödeme ve sık yapılan hatalar
- Kapıda ödemede ttInvoiceAmount tahsil edilecek tutarı, ttCollectionType tahsilat tipini (0 nakit, 1 kredi kartı) taşır. Kredi kartıyla tahsilatta dcSelectedCredit ve dcCreditRule alanları zorunludur. Değerlerini sözleşmenizdeki taksit kurgusuna göre Yurtiçi Kargo temsilcinizle teyit edin.
- Telefon numarasını +90 ve baştaki 0'ı temizleyerek 10 hane olarak gönderin.
- cityName ve townName ayrı alan olsa da il ve ilçeyi adres metnine de yazın.
- createShipment yanıt vermeden zaman aşımıyla kesilirse gönderi açılmış olabilir. İsteği körlemesine tekrarlamak yerine önce queryShipment ile anahtarı sorgulayın. Aynı cargoKey ile ikinci kayıt 60020 hata koduyla reddedilir.
- cancelShipment'ta genel sonucun yanında satır sonucunu da kontrol edin. Yola çıkmış gönderi iptal edilemez.
Kurulum adımları
- Sözleşme ve kullanıcı. Yurtiçi Kargo'dan web servis kullanıcı bilgileri, gerekiyorsa kapıda ödeme kullanıcısı alınır.
- IP yetkilendirme. Entegrasyonun çalışacağı sunucunun IP adresi test ve canlı ortam için Yurtiçi Kargo'ya bildirilir.
- Eşleme. Kargo yöntemleri, ödeme tipleri, depo ve gönderici bilgileri eşlenir.
- Test. Test ortamında gönderi açma, sorgulama ve iptal senaryoları denenir.
- Pilot. Canlıda sınırlı sayıda gönderiyle etiket, şube teslimi ve durum akışı kontrol edilir.
- İzleme. Durum senkronu, hata kayıtları ve alarmlar düzenli takip edilir.
Maliyeti belirleyen kalemler
- Hazır uygulama mı, özel entegrasyon mu
- Gönderinin açılacağı sistem: site, ERP ya da depo yazılımı
- Depo ve gönderici adresi sayısı
- Kapıda ödeme ve iade akışları
- Etiket tasarımı ve yazıcı kurulumu
- Diğer kargo firmalarıyla birlikte kurala bağlı firma seçimi
Yurtiçi Kargo tarafında canlıda olan işlerimiz
- Shopify App Store'da yayında olan Yurtiçi Kargo Entegrasyonu uygulamamız
- Shopify mağazalarında canlıda çalışan Yurtiçi Kargo gönderimleri
- App Store'da yayında 17 uygulama (geliştirici sayfamız)
SSS