E-ticaret operasyonunda sipariş onaylandıktan sonra kargo sürecinin otomatik ilerlemesi, manuel veri girişini azaltır ve müşteriye doğru takip bilgisi sunulmasını kolaylaştırır. Kargo API entegrasyonu, e-ticaret platformu ile taşıyıcı veya lojistik yazılımı arasında veri alışverişini standartlaştıran teknik bağlantıdır.
API nedir?
API (Application Programming Interface), iki yazılım sisteminin birbirleriyle konuşmasını sağlayan arayüzdür. E-ticarette sipariş oluşturma, adres doğrulama, gönderi etiketi üretme ve takip durumu sorgulama gibi işlemler API uç noktaları (endpoint) üzerinden yürütülür.
REST veya SOAP tabanlı HTTP istekleri en yaygın yaklaşımdır. Kimlik doğrulama genelde API anahtarı, OAuth veya imzalı isteklerle yapılır. Entegrasyon tasarımında önce taşıyıcının veya aracı platformun dokümantasyonu okunmalıdır.
E-ticaret → kargo sistemi akışı
Tipik akış şu adımlardan oluşur:
1. Müşteri siparişi e-ticaret platformunda tamamlar 2. Sipariş verisi entegrasyon katmanına iletilir 3. Kargo API'sine gönderi oluşturma isteği gönderilir 4. Takip numarası ve etiket bilgisi döner 5. Durum güncellemeleri periyodik sorgu veya webhook ile alınır 6. Müşteri arayüzünde kargo durumu gösterilir
Bu akış işletmenin kullandığı e-ticaret altyapısına, taşıyıcı sayısına ve entegrasyon mimarisine göre değişir. Her taşıyıcının API şeması, alan adları ve hata kodları farklı olabilir.
Sipariş aktarımı
Sipariş aktarımında alıcı adresi, telefon, ağırlık, paket sayısı, ödeme tipi (kapıda ödeme vb.) ve ürün tanımı gibi alanlar taşıyıcının beklediği formata dönüştürülür. Adres normalizasyonu hatalı gönderileri azaltır; eksik alanlar API reddine yol açabilir.
Entegrasyon katmanında idempotency (aynı siparişin iki kez gönderilmemesi) önemlidir. Ağ kesintisi veya zaman aşımı durumunda tekrar deneme mantığı, mükerrer kargo kaydı oluşturmamalıdır.
Takip numarası
Başarılı gönderi oluşturma yanıtında takip numarası (tracking number) döner. Bu numara e-ticaret sipariş kaydına yazılır ve müşteriye e-posta veya SMS ile iletilebilir. Takip numarası formatı taşıyıcıya özgüdür.
Takip numarası alınamadan sipariş "kargoya verildi" statüsüne geçirilmemelidir. Entegrasyon loglarında başarısız yanıtlar izlenebilir olmalıdır.
Durum kodları
Taşıyıcılar gönderi yaşam döngüsünü durum kodlarıyla bildirir: kabul edildi, transferde, dağıtımda, teslim edildi, iade vb. Bu kodların e-ticaret platformundaki sipariş statüleriyle eşlenmesi (mapping) gerekir.
Aynı mantıksal durum farklı taşıyıcılarda farklı kodlarla gelebilir. Entegrasyon tasarımında taşıyıcı bazlı eşleme tablosu tutmak bakımı kolaylaştırır. Müşteriye gösterilen metinler sade ve tutarlı olmalıdır.
Webhook
Webhook, taşıyıcının durum değişikliğinde sizin belirlediğiniz URL'ye HTTP POST göndermesidir. Periyodik polling'e kıyasla daha güncel bildirim sağlar. Webhook uç noktası imza doğrulaması (signature verification) ile korunmalıdır.
Webhook teslimatında geçici hatalar olabilir; taşıyıcı genelde yeniden deneme yapar. Sizin tarafınızda da idempotent işleme ve kuyruk yapısı düşünülmelidir.
Retry, timeout ve hata yönetimi
Ağ gecikmesi, taşıyıcı bakım penceresi veya rate limit nedeniyle istekler başarısız olabilir. Retry politikası: kaç deneme, hangi aralıkla, hangi HTTP kodlarında tekrar deneneceği tanımlanmalıdır. Timeout süresi çok kısa ise gereksiz hata, çok uzun ise kullanıcı deneyimi olumsuz etkilenir.
Kalıcı hatalar (geçersiz adres, desteklenmeyen bölge) için otomatik retry yerine operasyon ekibine düşen kuyruk oluşturulabilir. Hata mesajları müşteriye ham API yanıtı olarak gösterilmemelidir.
Loglama ve izleme
Entegrasyon katmanında istek/yanıt logları (Kişisel Verilerin Korunması kapsamında maskeleme ile), gecikme metrikleri ve hata oranları izlenmelidir. Anomali tespiti, toplu gönderi günlerinde erken uyarı sağlar.
Merkezi loglama, farklı taşıyıcı entegrasyonlarını karşılaştırmalı analiz etmeyi kolaylaştırır. Üretim ortamında debug seviyesi logların kişisel veri içermemesine dikkat edin.
Güvenlik
API anahtarları kaynak kodda sabitlenmemeli; ortam değişkenleri veya gizli yönetim servisleri kullanılmalıdır. HTTPS zorunludur. Webhook imza doğrulaması atlanmamalıdır. Minimum yetki prensibi: yalnızca gerekli API kapsamları tanımlanmalıdır.
Özel yazılım entegrasyonu perspektifi
Hazır e-ticaret eklentileri her taşıyıcı veya özel iş kuralını karşılamayabilir. Çoklu depo, kısmi sevkiyat, özel fiyatlandırma veya ERP entegrasyonu gibi senaryolarda özel yazılım geliştirme gerekebilir. Bu yazı genel API entegrasyonu bilgisi sunar; belirli bir taşıyıcı ile hazır entegrasyon hizmeti iddiası içermez.
Kargo API entegrasyonu, özel yazılım ve sistem entegrasyonu kapsamında ele alınabilecek bir teknik konudur. Proje kapsamı, kullanılacak taşıyıcı API'leri ve mevcut altyapıya göre belirlenir. Detaylı bilgi için özel yazılım geliştirme hizmetini inceleyin.
Sonuç
E-ticarette kargo API entegrasyonu; sipariş aktarımı, takip numarası, durum kodları, webhook ve sağlam hata yönetimi bileşenlerinden oluşur. Taşıyıcı API'leri farklıdır; entegrasyon tasarımı dokümantasyon okuma, eşleme tabloları ve güvenli retry mantığı gerektirir. Hazır çözümler yeterli olmadığında özel yazılım geliştirme yolu değerlendirilebilir.
E-ticaret ve B2B yazılım projeleri
E-ticaret ve B2B yazılım projeleri →YAZICISOFT Hakkında
YAZICI ETİCARET YAZILIM LİMİTED ŞİRKETİ (YAZICISOFT), 2022'den bu yana hosting, domain, yazılım, sunucu ve veri merkezi altyapısı alanlarında uluslararası hizmet ihracatı yapan Antalya merkezli bir teknoloji şirketidir.