E-Ticarette Kargo ve Lojistik API Entegrasyonu Temelleri

Lojistik API entegrasyonu, e-ticaret platformu ile taşıyıcı firma sistemleri arasında veri akışını otomatikleştirir. Manuel veri girişini sıfırlar. Hatalı adres ve gecikme risklerini önler. Modern web altyapılarında REST API ve JSON standart iletişim protokolüdür. Eski taşıyıcı sistemlerde SOAP/XML protokolü devam eder.

Temel API İşlevleri

Gönderi Oluşturma (Shipment Creation): Sipariş onayında alıcı, adres ve paket verisini kargo servisine iletir. Takip kodu (Tracking ID) ve barkod (ZPL/PDF) üretir.
Canlı Durum Takibi (Status Tracking): Paketin dağıtım merkezi, transfer ve teslimat durumlarını çeker. Polling yerine Webhook mimarisi kaynak tüketimini düşürür.
İptal ve İade Yönetimi (Cancellation & Return): İptal edilen siparişlerde barkod geçersiz kılma ve tersine lojistik kaydı açma adımlarını yürütür.

Adım Adım Kargo API Entegrasyonu

Adım 1: Kimlik Doğrulama ve Ortam Yapılandırması

Kargo sağlayıcıdan API anahtarı (API Key), Müşteri Numarası (Customer ID) ve Gizli Anahtar (Secret Key) alınır. Üretim (Production) öncesi Test/Sandbox ortamında endpoint doğrulaması yapılır.

Güvenlik uyarısı: API kimlik bilgileri istemci tarafında (frontend) tutulmaz. Sunucu tarafı ortam değişkenlerinde (.env) saklanır.

Adım 2: Gönderi Kaydı Oluşturma ve Barkod Alma

Sipariş paketlendiği anda sunucu arka plan işi (background job) kargo API endpointine POST isteği atar.

Alıcı Verisi Doğrulama: İl, ilçe, posta kodu, telefon formatı doğrulanır.
Desi/Ağırlık Hesabı: Paket boyutları (En x Boy x Yükseklik / 3000) hesaplanır.
Barkod Üretimi: Dönen Base64 barkod verisi termal yazıcı formatına (ZPL/PDF) çevrilir.

Adım 3: Süreç Takibi ve Webhook Yapılandırması

Taşıyıcı sistemindeki her durum değişikliği e-ticaret webhook dinleyicisine (webhook listener) push edilir. Polling sorgu yükü engellenir.

SIPARIS_ALINDI: Takip numarası veritabanına işlenir, müşteriye SMS/E-posta iletilir.
DAGITIMDA: Sipariş durumu 'Kargoya Verildi' olarak güncellenir.
TESLIM_EDILDI: Sipariş tamamlandı statüsüne geçer, fatura tetiklenir.
TESLIM_EDILEMEDI: Müşteri hizmetlerine otomatik bildirim açılır.

Modern Web ve Dijital Ajans Trendleri

Dijital ajans ve modern web geliştiricileri tekil kargo entegrasyonları yerine lojistik agregatörleri (Multi-carrier Shipping API) tercih eder. Bu yaklaşım tek arayüz üzerinden birden fazla kargo firmasını dinamik yönetmeyi sağlar.

Dinamik Kargo Atama: Desi, lokasyon ve maliyet bazlı en ucuz/hızlı taşıyıcıyı otomatik seçen algoritmalar.
PWA ve Mobil Takip: Kullanıcıya anlık konum gösteren mikro takip sayfaları.
Headless E-Ticaret Uyumu: Lojistik mantığının çekirdek API katmanında mikroservis olarak ayrılması.

Hata Yönetimi ve En İyi Uygulamalar

Idempotency (Yinelenebilirlik): Ağ hatası nedeniyle tekrarlanan isteklerde mükerrer kargo kaydı açılmasını önlemek için idempotency anahtarı (Idempotency-Key) kullanılır.
Retry Mekanizması: Zaman aşımı durumlarında Exponential Backoff (üstel geri çekilme) stratejisi uygulanır.
Veri Loglama: Kargo sağlayıcıya gönderilen payload ve dönen yanıt ham haliyle (PII verileri maskelenerek) hata ayıklama günlüğüne yazılır.