E-Ticaret Kargo Entegrasyonu Nasıl Yapılır? (2026)

Kargo entegrasyonu, e-ticaret sitenizin kargo firmasının sistemine bağlanarak gönderi oluşturma, barkod/etiket üretme, takip numarası alma ve teslimat durumunu müşteriye bildirme adımlarını otomatikleştirmesidir. Türkiye’de üç yolla yapılır: kargo firmasının kendi API’sine doğrudan bağlanmak, birden çok firmayı tek arayüzde toplayan bir kargo entegratörü kullanmak ya da hazır e-ticaret altyapınızın modülünü açmak. Tek kargo firmasıyla çalışan bir mağaza için doğrudan API tipik olarak 3-10 iş günlük bir geliştirme; iki veya daha fazla firmayla çalışıyorsanız entegratör neredeyse her zaman daha ucuza gelir. Aşağıda üç yolun farkını, API’den gerçekte ne aldığınızı, gönderi başına maliyeti ve entegrasyonu bozan klasik hataları bulacaksınız.

Kargo entegrasyonu ne işe yarar?

Entegrasyonsuz bir mağazada sipariş şu şekilde ilerler: sipariş listesi dışa aktarılır, kargo firmasının web paneline elle girilir, barkod yazdırılır, takip numarası kopyalanıp sipariş kaydına yapıştırılır ve müşteriye tek tek e-posta atılır. Günde 10 siparişte bu iş yaklaşık yarım saattir; günde 100 siparişte tam zamanlı bir kişinin işidir ve yazım hatası yüzünden yanlış adrese giden gönderiler kaçınılmaz hale gelir.

Entegrasyon bu zinciri tek tıka indirir. Siparişin durumu “kargoya verilecek” olduğunda sistem gönderiyi otomatik açar, etiketi PDF olarak üretir, takip numarasını sipariş kaydına yazar ve müşteriye bilgilendirme gönderir. Kargo firmasının durum güncellemeleri de geri döndüğü için “kargom nerede” soruları büyük ölçüde ortadan kalkar — bu, çoğu mağazada müşteri hizmetlerine gelen taleplerin en büyük kalemidir.

Üç entegrasyon yolu: hangisi size uygun?

• Kargo firmasının kendi API’si — Yurtiçi, Aras, MNG, Sürat, PTT ve UPS gibi firmaların tamamı sözleşmeli müşterilerine API erişimi verir. En düşük gönderi maliyeti buradadır çünkü araya kimse girmez; buna karşılık her firmanın alan adları, hata kodları ve dokümantasyon kalitesi farklıdır. İkinci firmayı eklediğinizde entegrasyonu baştan yazarsınız.
• Çoklu kargo entegratörü (aggregator) — Tek bir API üzerinden onlarca kargo firmasına gönderi açmanızı sağlar; fiyat karşılaştırma, otomatik firma seçimi ve tek ekrandan takip gibi özellikler getirir. Gönderi başına küçük bir komisyon ya da aylık paket ücreti alır. İki ve üzeri kargo firmasıyla çalışan mağazalar için tartışmasız en verimli yoldur.
• Hazır altyapı modülü — Shopify, WooCommerce, Ticimax, İdeasoft gibi platformlarda kargo entegrasyonu genellikle hazır bir eklentidir; kurulumu birkaç saat sürer. Sınırı özelleştirmedir: kendi kural setinizi (desiye göre firma seçimi, bölgeye göre farklı firma, çok parçalı gönderi) kurmanız gerekiyorsa modül yetmez.

Karar kuralı basittir: tek kargo firması + standart akış varsa doğrudan API ya da hazır modül; çok firma, çok depo ya da kendi iş kurallarınız varsa entegratör. Özel bir e-ticaret altyapısı geliştiriyorsanız bu seçim mimarinin başında yapılmalıdır — kargo katmanını sonradan değiştirmek sipariş modelini de değiştirir. Bu tür kararların bütçeye etkisini e-ticaret sitesi kurma maliyeti yazımızda kalem kalem inceledik.

Kargo API’sinden gerçekte ne alırsınız?

Kargo API’leri pazarlama sayfalarında tek bir servis gibi görünse de pratikte beş ayrı yetenekten oluşur ve firmaların bazılarında bunların hepsi yoktur. Sözleşme imzalamadan önce beşini de tek tek sorun:

• Gönderi oluşturma — Alıcı bilgisi, adres, desi/kg ve ödeme tipiyle bir gönderi kaydı açar; karşılığında takip numarası döner.
• Etiket / barkod üretimi — PDF veya ZPL formatında yazdırılabilir etiket. Termal yazıcı kullanıyorsanız ZPL desteğini mutlaka teyit edin; PDF’i termal yazıcıda düzgün bastırmak ayrı bir uğraştır.
• Takip sorgulama — Takip numarasıyla anlık durum. İki model var: siz düzenli aralıklarla sorarsınız (polling) ya da firma değişiklikte size bildirim gönderir (webhook). Webhook varsa tercih edin; polling hem gecikmeli hem gereksiz yüklüdür.
• İptal ve iade — Açılmış gönderiyi iptal etme ve iade kodu üretme. Bu ikisi genelde en zayıf tarafıdır; iade akışını elle yönetmek zorunda kalabilirsiniz.
• Fiyat sorgulama — Desi/kg ve mesafeye göre gönderi ücretini önceden hesaplama. Sepette gerçek kargo ücreti göstermek istiyorsanız bu uç nokta şarttır.

Tipik bir gönderi oluşturma çağrısı, altyapı fark etmeksizin aşağıdaki gibi görünür. Sunucu tarafında çalıştırın; API anahtarını tarayıcıya asla düşürmeyin:

// app/api/shipments/route.ts — sunucu tarafı, anahtar istemciye gitmez
export async function POST(request: Request) {
  const order = await request.json();

  const response = await fetch('https://api.kargo-firmasi.com/v1/shipments', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CARRIER_API_KEY}`,
      'Content-Type': 'application/json',
      // Aynı siparişin iki kez gönderi açmasını engeller
      'Idempotency-Key': order.id,
    },
    body: JSON.stringify({
      receiver: {
        name: order.customer.fullName,
        phone: order.customer.phone,
        address: order.shippingAddress.line1,
        city: order.shippingAddress.city,
        district: order.shippingAddress.district,
      },
      parcel: { desi: order.desi, pieceCount: order.pieceCount },
      paymentType: order.isCashOnDelivery ? 'RECIPIENT' : 'SENDER',
    }),
  });

  if (!response.ok) {
    // Hata gövdesini logla; kargo API'leri hatayı 200 içinde de dönebilir
    const detail = await response.text();
    return Response.json({ error: 'CARRIER_ERROR', detail }, { status: 502 });
  }

  const { trackingNumber, labelUrl } = await response.json();
  return Response.json({ trackingNumber, labelUrl });
}

Idempotency-Key alanı bu isteğin en kritik satırıdır. Ağ zaman aşımı yüzünden tekrar denenen bir istek, bu anahtar olmadan aynı sipariş için ikinci bir gönderi açar; müşteriye iki kargo çıkar, ikisinin de ücretini siz ödersiniz. Firma bu başlığı desteklemiyorsa aynı korumayı kendi tarafınızda kurun: gönderi kaydını sipariş numarasıyla tekilleştirin.

Maliyet: entegrasyon ve gönderi başına ne ödersiniz?

İki ayrı maliyet kalemi var ve karıştırılmaları bütçeyi yanıltıyor. Birincisi tek seferlik geliştirme maliyeti: tek kargo firmasına doğrudan API entegrasyonu tipik olarak 3-10 iş günü, entegratör entegrasyonu 2-5 iş günü, hazır modül kurulumu birkaç saattir. İkincisi ise sürekli maliyet: kargo firmasının gönderi başına ücreti sözleşmenize bağlıdır, entegratör kullanıyorsanız üstüne gönderi başına küçük bir komisyon ya da aylık paket ücreti biner.

Sözleşme görüşmesinde belirleyici olan tek şey hacimdir. Aylık gönderi adediniz arttıkça desi başına birim fiyat düşer; bu yüzden yılda bir kez sözleşmeyi yenilemek, entegrasyonu optimize etmekten daha çok para kazandırır. Ödeme ve faturalama tarafını da aynı anda kurmak istiyorsanız ödeme entegrasyonu ve e-fatura entegrasyonu yazılarımız bu üçlünün nasıl birlikte çalıştığını anlatıyor.

Entegrasyonu bozan 5 klasik hata

• Adres alanlarını tek satıra sıkıştırmak — Kargo firmaları il ve ilçeyi kendi kodlarıyla eşleştirir. Serbest metin adresten ilçe çıkarmaya çalışan sistemler, “Şişli/İstanbul” ile “Sisli Istanbul” arasındaki farkta takılır. İl ve ilçeyi checkout’ta ayrı ayrı ve seçmeli alın.
• Desi hesabını atlamak — Kargo ücreti ağırlığa değil, çoğu zaman hacimsel ağırlığa (desi) göre hesaplanır. Ürün kaydında en/boy/yükseklik tutmuyorsanız sepette gösterdiğiniz ücret ile faturaya yansıyan ücret tutmaz.
• Hata durumunda sessiz kalmak — Kargo API’leri hatayı bazen HTTP 200 gövdesinde döner. Sadece durum koduna bakan bir entegrasyon, gönderi açılmadığı hâlde siparişi “kargolandı” olarak işaretler ve bunu müşteri şikâyetiyle öğrenirsiniz.
• Takip durumunu senkronize etmemek — Takip numarasını yazıp bırakmak yeterli değil. Teslim edildi, adreste bulunamadı ve iade durumlarını sipariş kaydına geri yazmayan mağazalar iade sürecini elle takip etmek zorunda kalır.
• API anahtarını istemci tarafına koymak — Kargo çağrılarını tarayıcıdan yapan bir kurulum, anahtarı ağ sekmesinde herkese açar. Tüm kargo çağrıları sunucu tarafından yapılmalıdır. Bu ve benzeri kurumsal entegrasyon kalıplarını API entegrasyonu nedir yazımızda topladık.

Entegrasyon öncesi hazırlık listesi

• Kargo firmasıyla sözleşmeyi imzalayın ve API erişimi (test + canlı anahtar) talep edin — bu adım çoğunlukla geliştirmeden uzun sürer.
• Ürün kayıtlarınıza en/boy/yükseklik ve ağırlık alanlarını ekleyin; desi hesabı buna dayanır.
• Checkout’ta il/ilçe/mahalle alanlarını seçmeli hale getirin.
• Test ortamında en az bir gönderi açın, etiketi gerçek yazıcıdan bastırın ve iptal akışını deneyin.
• Takip durumları için webhook varsa açın; yoksa periyodik senkronizasyon işi kurun.

Sonuç

Kargo entegrasyonu teknik olarak zor bir iş değil; zorluk, doğru yolu seçmek ve adres, desi, hata ve iade gibi kenar durumları baştan düşünmekte. Tek firmayla çalışıyorsanız doğrudan API en ucuz, birden çok firmayla çalışıyorsanız entegratör en hızlı yoldur. Aynı siparişi pazaryerlerinden de alıyorsanız kargo etiketinin oradan geldiğini unutmayın; o tarafı pazaryeri entegrasyonu nasıl yapılır yazısında anlattık. Mağazanız için hangi kurulumun uygun olduğunu konuşmak isterseniz web geliştirme hizmetimize göz atabilir ya da teklif alabilirsiniz.