E-Ticarette Kargo ve Lojistik API Entegrasyonu Nedir?

Kargo API entegrasyonu, e-ticaret platformunuz ile lojistik firmalarının sunucuları arasında gerçek zamanlı veri akışı sağlayan sistemdir. Sipariş onaylandığında kargo kodu oluşturma, barkod basımı, kurye çağırma ve kargo takip durum güncellemeleri insan müdahalesi olmadan çalışır.

Adım Adım Kargo ve Lojistik API Entegrasyonu

1. Adım: API Anahtarları ve Servis Seçimi

Lojistik sağlayıcısından (Yurtiçi Kargo, Aras, MNG, UPS vb.) veya çoklu taşıyıcı toplayıcılarından (ShipEntegra, Navlungo vb.) API erişim bilgileri (API Key, Secret Key, Müşteri No) temin edilir. Test (sandbox) ortamı aktif edilir.

2. Adım: Sipariş Veri Modelinin Eşlenmesi

Veritabanındaki sipariş ve müşteri adres alanları, kargo servisinin beklediği JSON veya XML veri şemasına dönüştürülür:

Alıcı Bilgileri: Ad, soyad, telefon, tam adres, ilçe, il, posta kodu.
Paket Detayları: Desi, ağırlık, paket adedi, ürün içeriği.
Ödeme Tipi: Peşin, kapıda nakit, kapıda kredi kartı.

3. Adım: Gönderi Oluşturma (Create Shipment Endpoint)

Sipariş durumu 'Hazırlanıyor' aşamasına geçtiğinde ilgili endpoint'e HTTP POST isteği atılır. Dönen yanıttaki tracking_number (takip no) ve barcode_data veritabanına kaydedilir.

4. Adım: Barkod ve ZPL/PDF Etiket Basımı

Depo süreçlerini hızlandırmak için API'den dönen barkod verisi, doğrudan termal yazıcılara ZPL komutuyla veya PDF formatında otomatik gönderilir.

5. Adım: Webhook ile Canlı Takip Kurulumu

Sürekli sorgu (polling) atmak yerine kargo durum değişikliklerini (Dağıtıma Çıktı, Teslim Edildi, İade) anlık yakalamak için Webhook kullanılır. Gelen webhook bildiriminde sipariş durumu otomatik güncellenir, müşteriye SMS/E-posta bildirimi tetiklenir.

Modern Web Trendleri ve Lojistik Yönetimi

Modern web mimarilerinde headless e-ticaret ve microservice altyapıları öne çıkmaktadır. Kargo süreçleri bağımsız bir kuyruk servisi (Redis, RabbitMQ) üzerinden asenkron yönetilerek ana sitenin checkout performansının düşmesi engellenir.

İpucu: Kargo API çağrılarını doğrudan ödeme anında çalıştırmayın. Sipariş tamamlandıktan sonra arka plan işçisine (Background Worker/Queue) devredin.

Dijital Ajans ve Geliştiriciler İçin En İyi Pratikler

Hata Yönetimi (Retry Mechanism): Kargo API yanıt vermediğinde üstel geri çekilme (exponential backoff) ile yeniden deneme kurgulayın.
Adres Doğrulama: Yanlış adres kaynaklı API hatalarını önlemek için ödeme adımında ilçe/mahalle listelerini dinamik doğrulayın.
Çoklu Kargo Desteği: Sisteminizi tek bir firmaya bağımlı bırakmayın; servis sağlayıcı adaptör deseni (Adapter Pattern) kullanarak geliştirin.