Kargo API, e-ticaret sitenizin kargo firmalarıyla yazılımsal olarak konuşmasını sağlayan arayüzdür. Sipariş geldiğinde etiket bas, kargo durumu değiştiğinde müşteriyi bilgilendir, iade talebi geldiğinde iade etiketi oluştur — bunların hepsi API üzerinden otomatikleşir.
Bu rehber, kargo API'lerinin teknik yapısını ve e-ticaret entegrasyonunun pratik tarafını anlatıyor.
Kargo API'sinin 4 Temel Fonksiyonu
1. Fiyat Sorgulama (Rate API)
Checkout sırasında müşteriye gerçek kargo ücretini göstermek veya sipariş sonrası en uygun firmayı seçmek için kullanılır.
Gönderdiğiniz veri:
- Gönderici il/ilçe
- Alıcı il/ilçe
- Paket boyutları ve ağırlık (desi veya kg)
- Hizmet tipi (standart, express, kapıda ödeme)
Dönen veri:
- Taşıma ücreti
- Tahmini teslimat süresi
- Varsa ek hizmet ücretleri (sigorta, kapıda ödeme komisyonu)
Pratik kullanım: Checkout'ta müşteriye "Aras Kargo — 49 TL, 2-3 iş günü" gibi gerçek zamanlı fiyat gösterebilirsiniz. Sabit kargo ücreti koymak yerine bu yöntemi kullanmak hem kârlılığı artırır hem müşteri güvenini sağlar.
2. Gönderi Oluşturma ve Etiket Basımı (Shipment API)
Asıl iş burada döner. Sipariş onaylandıktan sonra kargo gönderisi oluşturup etiket almak için kullanılır.
Gönderdiğiniz veri:
- Gönderici/alıcı bilgileri (ad, adres, telefon)
- Paket detayları (ağırlık, boyut, adet)
- Kapıda ödeme tutarı (varsa)
- Hizmet tipi
Dönen veri:
- Takip numarası (barkod)
- Etiket dosyası (PDF veya termal yazıcılar için ZPL formatı)
Dikkat noktası: Etiket formatı önemlidir. E-ticaret hacminiz düşükse A4 PDF yeterlidir. Günde 50+ gönderi yapıyorsanız termal yazıcı + ZPL formatı ciddi zaman kazandırır — her etiket 2 saniyede basılır.
3. Kargo Takip (Tracking API)
Gönderi oluşturduktan sonra kargonun durumunu sorgulamak için kullanılır.
Gönderdiğiniz veri: Takip numarası
Dönen veri:
- Güncel durum (kabul edildi, aktarmada, dağıtımda, teslim edildi)
- Durum geçmişi (tarih-saat bazlı)
- Teslim bilgisi (teslim alan kişi, imza)
İki yöntem var:
| Polling (Siz sorarsınız) | Webhook (Firma bildirir) | |
|---|---|---|
| Çalışma şekli | Her X dakikada API'ye "durum ne?" diye sorarsınız | Durum değiştiğinde firma sizin endpoint'inize POST atar |
| Gecikme | Sorgu aralığına bağlı (5-30 dk) | Anlık (saniyeler içinde) |
| Sunucu yükü | Yüksek — gereksiz boş sorguların %90'ı | Düşük — sadece gerçek değişikliklerde istek gelir |
| Ölçeklenebilirlik | 1000 aktif gönderi = dakikada 1000 istek | 1000 aktif gönderi = günde ~3000 istek (ortalama 3 durum değişikliği) |
Webhook kesinlikle tercih edilmeli. Ama her kargo firması webhook sunmuyor — bu durumda polling'i akıllı yapın: yeni kargolarda sık sorgulayın (saatlik), 3 gün geçmiş kargolarda seyrek (günde 1).
4. İptal ve İade (Cancel/Return API)
- Henüz teslim alınmamış gönderiyi iptal etme
- İade kargo etiketi oluşturma
- İade kargo takibi
Türkiye'de Kargo API'lerinin Gerçekleri
Her Firmanın API'si Farklı
Bu en büyük baş ağrısı. Türkiye'deki kargo firmaları standart bir API protokolünde buluşmuyor:
| Firma | Protokol | Kimlik Doğrulama | Veri Formatı |
|---|---|---|---|
| Aras Kargo | SOAP (XML) | Kullanıcı adı/şifre | XML |
| MNG Kargo | REST | API Key | JSON |
| Yurtiçi Kargo | SOAP | Kullanıcı adı/şifre | XML |
| HepsiJET | REST | OAuth 2.0 | JSON |
| PTT Kargo | SOAP | Kullanıcı adı/şifre | XML |
Bu tablo neden önemli? Aras'la çalışan kodunuz MNG'de çalışmaz. Her firma için:
- Farklı istek yapısı
- Farklı hata kodları (Aras'ın "102" hatası ile MNG'nin "ERR_ADDRESS" hatası aynı şeyi ifade edebilir)
- Farklı test ortamları (bazılarının sandbox'ı yoktur)
- Farklı dokümantasyon kalitesi (bazıları Swagger sunar, bazıları Word dosyası)
SOAP vs REST: Pratik Fark
Eski firmalar (Aras, Yurtiçi, PTT) genellikle SOAP kullanır. Bu demek ki:
- XML parse etmeniz gerekir
- WSDL dosyasını indirip client generate etmelisiniz
- Hata mesajları XML CDATA içinde gelir, debug etmesi zordur
Yeni nesil firmalar (HepsiJET, bazı yeni servisler) REST + JSON kullanır:
- İstek/yanıt okunabilir
- Postman'da test etmek kolaydır
- Hata yönetimi standart HTTP kodlarıyla gelir
Gerçek Bir Entegrasyon Ne Kadar Sürer?
Dürüst tablo — bir backend developer'ın tek bir kargo firması için harcayacağı süre:
| Aşama | Süre | Not |
|---|---|---|
| Dokümantasyon okuma ve API keşfi | 1-2 gün | Dokümantasyon kötüyse 3-4 gün |
| Temel fonksiyonlar (etiket + takip) | 3-5 gün | SOAP ise daha uzun |
| Hata senaryoları ve edge case'ler | 2-3 gün | Yanlış adres, timeout, karakter encoding |
| Test (sandbox + gerçek gönderi) | 2-3 gün | Sandbox yoksa gerçek gönderi ile test zorunlu |
| Production'a alma ve monitoring | 1-2 gün | Loglama, alert sistemi |
Tek firma için 2-3 hafta gerçekçi bir tahmindir. 5 firma istiyorsanız süreler tam katlanmaz (ortak altyapı paylaşılır) ama yine de 2-3 ay düşünmelisiniz.
Bu sürelere bakım eklenmiyor: API değişiklikleri, sertifika yenilemeleri, yeni hizmet tipleri — bunlar yıllık olarak her firma için birkaç gün bakım gerektirir.
Tek API ile Tüm Firmalar: Aggregator Yaklaşımı
Doğrudan her firmayı kendiniz entegre etmek yerine, bir aggregator (çoklu kargo platformu) kullanabilirsiniz. Bu platformlar tüm firmaların API'lerini tek bir standart API arkasında sunar.
Nasıl çalışır:
- Siz aggregator'un API'sine tek bir formatta istek atarsınız
- Aggregator isteğinizi ilgili kargo firmasının formatına çevirir
- Firmadan gelen yanıtı standart formata dönüştürüp size döner
Ne kazanırsınız:
- SOAP/REST, XML/JSON farkıyla uğraşmazsınız
- Hata kodları standarttır
- Yeni firma eklemek = bir config değişikliği (kod değişikliği değil)
- Fiyat karşılaştırma yerleşiktir — tek istekle 5 firmadan fiyat alırsınız
Ne kaybedersiniz:
- Firma API'si üzerinde tam kontrol yok
- Aggregator'a bağımlılık (onlar çökerse siz de çökersiniz)
- Her istek aggregator üzerinden geçer (milisaniyeler eklenir)
Kendi Entegrasyonunuzu mu Yazmalısınız, Platform mı Kullanmalısınız?
Bu karar iş modelinize bağlı:
Kendiniz yazın eğer:
- Geliştirici ekibiniz varsa ve backend kapasitesi müsaitse
- Sadece 1-2 firma yeterliyse
- Çok özel iş kurallarınız varsa (örneğin firma API'sine özel parametreler göndermeniz gerekiyorsa)
- Tam kontrol ve bağımsızlık istiyorsanız
Platform kullanın eğer:
- 3+ firma ile çalışıyorsanız
- Geliştirici kaynağınız sınırlıysa veya kargo entegrasyonuna vakit ayıramıyorsanız
- Hızlı başlamak istiyorsanız (günler vs. aylar)
- API bakımıyla uğraşmak istemiyorsanız
Shipink'in API'si REST tabanlıdır ve 16 kargo firmasını tek endpoint üzerinden sunar. Kendi anlaşmanızı veya platform anlaşmasını kullanabilirsiniz.
API Entegrasyonunda Teknik Checklist
Production'a çıkmadan önce bu maddeleri kontrol edin:
Güvenlik
- API anahtarları environment variable'da, kodda değil
- HTTPS zorunlu (HTTP isteği yapılmıyor)
- IP whitelist aktif (firma destekliyorsa)
- API anahtarları minimum yetkilendirilmiş (sadece gerekli scope'lar)
Hata Yönetimi
- Timeout ayarı makul (10-30 saniye, işleme göre)
- Geçici hatalar (5xx, timeout) için retry mekanizması (exponential backoff)
- Kalıcı hatalar (4xx) için kullanıcıya anlamlı mesaj
- Tüm API çağrıları loglanıyor
Performans
- Rate limit'e takılmamak için istek kuyruğu var
- Fiyat sorguları cache'leniyor (aynı rota için 15-30 dk geçerli)
- Etiket oluşturma asenkron (müşteri bekletilmiyor)
İzleme
- API yanıt süreleri izleniyor
- Hata oranı alert'i kurulu
- Firma bazlı başarı/başarısızlık oranı dashboard'da
Sonuç
Kargo API entegrasyonu e-ticaret otomasyonunun temelidir. Türkiye'deki en büyük zorluk firmaların API standartlarının farklı olması — SOAP/REST karışımı, farklı hata yapıları ve değişken dokümantasyon kalitesi.
1-2 firma ile çalışıyorsanız ve teknik ekibiniz güçlüyse kendi entegrasyonunuz size tam kontrol sağlar. 3+ firma gerekiyorsa veya hızlı başlamak istiyorsanız aggregator platformu daha pratik bir yoldur.
Hangi yolu seçerseniz seçin, webhook tercih edin, hata yönetimini ciddiye alın ve API anahtarlarınızı güvenli tutun.
