E-Ticaret Sitesi Kurarken İlk Günden Entegrasyon Planı Neden Yapılmalı?

E-ticaret sitesi kurarken entegrasyon planını ilk günden yapmak, projenin ileride büyüyebilmesi için temel kararlardan biridir. Çünkü e-ticaret sitesi tek başına çalışan bir vitrin değildir. Ödeme sistemi, kargo firması, ERP, muhasebe, stok, pazaryeri, reklam ölçümü, e-posta/SMS otomasyonu ve raporlama yapısı bir noktada mutlaka siteyle konuşmak zorunda kalır.

En sık yapılan hata, entegrasyonları proje sonrasına bırakmaktır. İlk sürüm hızlı çıksın diye ürün veri modeli sade tutulur, SKU yapısı netleşmez, sipariş statüleri yazılmaz, kargo ve ödeme hata senaryoları düşünülmez. Site yayına alınır, satış başlar ve her yeni bağlantı geçici çözümle eklenir. Bu yaklaşım kısa vadede zaman kazandırır gibi görünür; orta vadede veri karmaşası, manuel iş ve yeniden geliştirme maliyeti üretir.

Entegrasyon planı ne demektir?

Entegrasyon planı, e-ticaret sitesinin hangi sistemlerle, hangi verileri, hangi yönde, hangi sıklıkla ve hangi hata kurallarıyla paylaşacağını önceden belirleyen teknik ve operasyonel dokümandır. Bu plan sadece API listesi değildir. Ürün kodu nasıl tutulacak, stokun ana kaynağı hangi sistem olacak, ödeme başarılı olunca sipariş hangi statüye geçecek, kargo takip numarası nereden gelecek, iade stokta nasıl işlenecek gibi kararları içerir.

E-ticaret altyapısı planlanırken entegrasyon haritası ürün veri modelinden önce veya en geç onunla birlikte çıkarılmalıdır. Çünkü entegrasyonlar hangi alanların zorunlu olacağını belirler. ERP barkod istiyorsa ürün kaydında barkod alanı olmalıdır. Pazaryeri kategori kodu gerekiyorsa ürün modeli bunu taşımalıdır. Kargo entegrasyonu desi/ağırlık bilgisi istiyorsa ürün kartında bu alanlar eksik kalmamalıdır.

Trendyol geliştirici dokümanı, API entegrasyonlarıyla ürün, stok/fiyat, sipariş, fatura, kargo ve müşteri soruları gibi farklı süreçlerin yönetilebildiğini belirtir Trendyol Developers. Bu örnek, e-ticaret entegrasyonunun yalnızca ürün aktarmak değil, satıştan satış sonrasına kadar çok aşamalı bir veri akışı olduğunu gösterir.

İlk günden planlanmazsa ne olur?

Entegrasyon planı yapılmadığında sorunlar genellikle site yayına alındıktan sonra görünür. Ürünler eklenmiştir ama SKU formatı ERP ile uyumlu değildir. Siparişler alınır ama muhasebe sistemine aktarılamaz. Kargo barkodu manuel kesilir. Pazaryerine ürün gönderilir ama stok güncellenmez. Reklam kampanyası çalışır ama satın alma eventleri doğru ölçülmez.

Somut bir senaryo düşünelim: Bir mağaza 2.000 ürünle yayına çıkar. Ürün kodları panelde serbest metin olarak girilir. Üç ay sonra ERP entegrasyonu yapılmak istenir. ERP her varyant için tekil SKU bekler; e-ticaret panelinde ise aynı ürünün renk ve beden varyantları farklı standartlarla yazılmıştır. Ekip entegrasyon geliştirmek yerine önce binlerce ürün kodunu temizlemek zorunda kalır.

Bu nedenle entegrasyon planı, gelecekteki yazılım bağlantıları için sigorta işlevi görür. Her entegrasyon hemen canlıya alınmayabilir, fakat veri modeli buna hazır kurulmalıdır.

Hangi entegrasyonlar ilk günden haritalanmalı?

Her projede tüm entegrasyonları aynı anda yapmak şart değildir. Ancak ilk günden hangi entegrasyonların bugün, hangilerinin sonraki fazda, hangilerinin sadece ihtimal olarak planlandığı yazılmalıdır. Böylece bugünkü geliştirme gelecekteki bağlantıları engellemez.

E-ticaret entegrasyon hizmeti bu haritanın uygulama tarafıdır. Ancak iyi uygulama için önce hangi sistemin hangi veriden sorumlu olduğu belirlenmelidir. Örneğin stokun ana kaynağı ERP ise e-ticaret paneli stok düzenleme ekranı sınırlı çalışmalı veya değişiklikleri ERP'ye geri yazmalıdır.

Ürün veri modeli entegrasyonlara göre kurulmalı

Ürün veri modeli sadece site vitrini için tasarlanırsa ileride entegrasyonları taşımakta zorlanır. Ürün adı, açıklama, fiyat ve görsel başlangıç için yeterli görünebilir. Ancak pazaryeri, ERP, kargo, reklam feedi ve analitik sistemleri daha ayrıntılı alanlar ister. Barkod, SKU, marka, kategori ağacı, varyant, ağırlık, desi, tedarikçi kodu, KDV oranı, garanti süresi ve ürün görsel standardı gibi alanlar baştan düşünülmelidir.

Örnek ürün veri kaydı:

sku: AYK-1001-SIYAH-42 | barcode: 8690000000012 | erp_code: STK-45821 | category: Spor Ayakkabı | brand: Nova | color: Siyah | size: 42 | weight: 0.9 kg | desi: 2 | vat_rate: 20 | marketplace_category_code: 12345

Bu örnek gerçek ürün verisi değildir; entegrasyonlara hazır bir ürün kaydında hangi alanların gerekebileceğini göstermek için hazırlanmıştır. Bu alanlar ilk gün kullanılmasa bile sistemin bunları taşıyabilecek şekilde tasarlanması ilerideki bağlantıları kolaylaştırır.

Ödeme entegrasyonu hata senaryolarıyla planlanmalı

Ödeme entegrasyonu yalnızca sanal POS ekranını bağlamak değildir. Müşteri ödeme yaparken bağlantı kopabilir, banka doğrulama isteyebilir, ödeme başarılı olup site yanıtı alamayabilir, müşteri aynı işlemi tekrar deneyebilir. Bu senaryolar planlanmazsa çift sipariş, bekleyen ödeme veya destek yükü oluşur.

Stripe, idempotent request yapısıyla bağlantı hatası gibi durumlarda aynı isteğin güvenle tekrar denenebileceğini ve aynı işlemin ikinci kez oluşturulması riskinin azaltılabileceğini açıklar Stripe Docs. Bu teknik prensip her ödeme sağlayıcıda aynı isimle olmayabilir, ancak e-ticaret ödeme tasarımında aynı mantık aranmalıdır: aynı ödeme denemesi sistemde iki sipariş oluşturmamalıdır.

Sanal POS entegrasyonu için ilk günden şu kararlar yazılmalıdır:

• Ödeme başarılı olana kadar sipariş hangi statüde tutulacak?
• Ödeme başarılı ama siteye dönüş alınamazsa ne yapılacak?
• Aynı sepet için ikinci ödeme denemesi yeni sipariş mi, aynı siparişin denemesi mi olacak?
• Ödeme hatası müşteriye nasıl gösterilecek?
• İade ve kısmi iade hangi sistemden başlatılacak?
• Mutabakat için ödeme referansı sipariş kaydında saklanacak mı?

Kargo ve teslimat entegrasyonu sona bırakılmamalı

Kargo entegrasyonu genellikle site yayına yakın ele alınır. Oysa ürün ölçüleri, desi, ağırlık, teslimat bölgesi, ücretsiz kargo eşiği, taşıyıcı seçimi ve takip bildirimi sipariş akışının temel parçasıdır. Bu alanlar baştan planlanmazsa kargo ücreti yanlış hesaplanabilir veya depo ekibi barkodları manuel üretmek zorunda kalabilir.

Kargo entegrasyonu için örnek veri akışı şöyle olabilir:

1. Müşteri adres girer, sistem il/ilçe ve ürün desisine göre kargo seçeneklerini hesaplar.
2. Sipariş ödeme sonrası hazırlanacak statüsüne geçer.
3. Depo siparişi paketler, sistem kargo barkodu oluşturur.
4. Takip numarası siparişe yazılır ve müşteriye bildirim gider.
5. Kargo teslim edildiğinde sipariş statüsü güncellenir.
6. İade talebinde aynı taşıyıcı veya iade kodu akışı başlar.

Bu akış için ürün desisi, adres standardı ve sipariş statüleri baştan doğru kurulmalıdır. Sonradan eklenen kargo entegrasyonu, eksik ürün ölçüleri nedeniyle doğru çalışmayabilir.

ERP ve stok entegrasyonunda ana kaynak belirlenmeli

ERP veya muhasebe entegrasyonunda en kritik karar veri sahipliğidir. Stokun ana kaynağı ERP mi olacak, e-ticaret paneli mi? Fiyatı kim belirleyecek? Sipariş ERP'ye ne zaman aktarılacak? İptal ve iade stok hareketini nasıl etkileyecek? Bu kararlar net değilse sistemler birbirinin verisini ezebilir.

Stok takip yazılımı ile e-ticaret sitesi arasında iki yönlü veya tek yönlü akış tasarlanabilir. Örneğin ERP ana kaynaksa stok ve fiyat ERP'den siteye akar; sipariş ise siteden ERP'ye gider. İade onaylandığında ERP stok hareketini oluşturur ve siteye güncel stok döner. Bu akış yazılı hale getirilmelidir.

Örnek stok akışı:

ERP stok: 120 | E-ticaret güvenli stok payı: 5 | Satılabilir stok: 115 | Pazaryerine gönderilecek stok: 80 | Web sitesinde gösterilecek stok: 115 | Sipariş geldiğinde düşülecek kaynak: ERP rezervasyon kuyruğu

Bu örnek, stokun yalnızca sayısal değer olmadığını gösterir. Güvenli stok payı, pazaryeri için ayrılan stok, web sitesi stoğu ve ERP rezervasyonu ayrı kurallardır.

Pazaryeri entegrasyonu ilk fazda olmasa bile planlanmalı

Birçok işletme önce kendi sitesini kurar, sonra pazaryerlerine açılmayı planlar. Bu doğru bir fazlama olabilir. Ancak pazaryeri entegrasyonu daha sonra yapılacak diye ürün veri modeli buna kapalı kurulursa geçiş zorlaşır. Pazaryerleri kategori, marka, barkod, görsel, stok, fiyat ve ürün özelliklerinde belirli alanlar bekler.

Pazaryeri entegrasyonu için ürün modelinde şu alanlar baştan düşünülmelidir:

• Tekil SKU ve barkod.
• Marka ve kategori eşleştirme alanı.
• Pazaryeri kategori kodu ve özellik eşleştirmeleri.
• Ürün görsel standardı ve ana görsel URL'si.
• Kanal bazlı fiyat ve kampanya hariç tutma bilgisi.
• Kanal bazlı stok limiti veya güvenli stok payı.
• Pazaryerinden gelen sipariş numarası ve paket ID alanları.

Bu alanlar ilk günden görünür olmayabilir; ancak veritabanı ve panel mantığı bunları destekleyecek şekilde kurulursa pazaryeri fazı geldiğinde yeniden mimari çalışması gerekmez.

Analitik ve reklam ölçümü sonradan yamalanmamalı

Ölçüm entegrasyonu çoğu projede sona bırakılır. Site yayına alınır, reklam kampanyası başlar, sonra "satın alma nereden geldi?" sorusu sorulur. Eğer transaction_id, item_id, value, currency, campaign ve ürün listesi eventleri doğru gönderilmiyorsa dashboard ve reklam optimizasyonu eksik kalır.

Google Analytics e-ticaret dokümanı, ürün görüntüleme, sepete ekleme, checkout başlatma, satın alma, iade ve promosyon gibi alışveriş davranışlarının eventlerle ölçülebileceğini belirtir Google Analytics. Bu eventleri sonradan eklemek mümkündür, ancak en sağlıklı yaklaşım ürün ve sipariş veri modeliyle birlikte planlamaktır.

Dönüşüm takibi kurulumu için örnek ölçüm planı:

Entegrasyon haritası nasıl dokümante edilmeli?

İlk günden entegrasyon planı yapmak için uzun ve karmaşık teknik doküman şart değildir. Ancak sistemler, veri yönü, tetikleyici olaylar, hata davranışı ve sorumlu ekip net yazılmalıdır. Bu doküman yazılım ekibi, işletme sahibi, operasyon, muhasebe ve pazarlama tarafından anlaşılabilecek dilde olmalıdır.

Örnek entegrasyon haritası:

Bu tablo proje boyunca güncellenmelidir. Yeni bir entegrasyon eklendiğinde veri modeli, panel ekranları, hata logları ve raporlama etkisi birlikte değerlendirilmelidir.

Yönetim panelinde entegrasyon kontrolü olmalı

Entegrasyon çalışıyor mu sorusunun cevabı yalnızca teknik loglarda kalmamalıdır. Operasyon ekibi panelden son başarılı stok çekimini, son kargo barkodu hatasını, ödeme webhook durumunu, pazaryeri aktarım kuyruğunu ve ERP aktarım hatalarını görebilmelidir. Aksi halde hatalar fark edilene kadar siparişler bekler.

Yönetim paneli geliştirme kapsamında entegrasyon ekranları şu modülleri içerebilir:

• Son başarılı veri alışverişi zamanı.
• Bekleyen ve hata alan entegrasyon görevleri.
• SKU, barkod, kategori veya adres eşleşme hataları.
• Ödeme webhook kontrol listesi.
• Kargo barkodu alınamayan siparişler.
• Pazaryeri ürün aktarım ve sipariş çekme logları.
• Tekrar deneme butonu ve manuel düzeltme ekranı.

Bu ekranlar entegrasyonu yazılım ekibinin görünmeyen konusu olmaktan çıkarır. Operasyon, hangi siparişin neden beklediğini ve hangi verinin düzeltilmesi gerektiğini görebilir.

Güvenlik ve erişim anahtarları plana dahil edilmeli

Entegrasyonlar arttıkça API anahtarları, webhook imzaları, erişim izinleri, IP kısıtları ve loglama gereksinimleri de artar. Bu alanlar sonradan düşünülürse kritik bilgiler geliştirici bilgisayarında, e-posta içinde veya panelde açık metin olarak kalabilir. Entegrasyon planı güvenlik ve erişim yönetimini de kapsamalıdır.

Shopify Admin API dokümanı, REST Admin API'nin mağaza verilerine programatik erişim sağladığını ve ürün, sipariş, envanter gibi birçok kaynağın API üzerinden yönetilebildiğini gösterir Shopify Developers. Böyle yetkiler güçlüdür; bu yüzden hangi uygulamanın hangi veriye erişebileceği ve anahtarların nasıl saklanacağı baştan belirlenmelidir.

Pratik güvenlik kuralları:

• API anahtarları kod içine yazılmamalı, güvenli ortam değişkenlerinde tutulmalıdır.
• Webhook istekleri imza veya doğrulama mekanizmasıyla kontrol edilmelidir.
• Her entegrasyon için ayrı yetki kapsamı tanımlanmalıdır.
• Hata loglarında kart, şifre veya kişisel hassas veri tutulmamalıdır.
• Panelde entegrasyon ayarlarına erişim rol bazlı sınırlandırılmalıdır.

Başlamadan önce entegrasyon checklist'i

E-ticaret sitesi kurulumunda entegrasyon planı için aşağıdaki kontrol listesi başlangıç noktası olarak kullanılabilir:

• Bugün ve 12 ay içinde bağlanacak sistemler listelendi mi?
• Ürün için SKU, barkod, marka, kategori, varyant, desi ve ERP kodu standardı yazıldı mı?
• Stok ve fiyat için ana kaynak belirlendi mi?
• Ödeme başarılı, başarısız, bekleyen ve iade statüleri tanımlandı mı?
• Kargo barkodu, takip numarası ve teslimat bildirimi akışı yazıldı mı?
• Pazaryeri için kategori, ürün özellikleri ve stok/fiyat eşleştirmeleri planlandı mı?
• GA4 e-ticaret eventleri ve `transaction_id` standardı belirlendi mi?
• Entegrasyon hata kuyruğu ve tekrar deneme mantığı olacak mı?
• API anahtarları, webhook doğrulaması ve erişim rolleri güvenli planlandı mı?
• Yönetim panelinde entegrasyon durum ekranı tasarlandı mı?

Sonuç: Entegrasyon planı büyüme maliyetini düşürür

E-ticaret sitesi kurarken entegrasyon planı ilk günden yapılırsa proje ilk fazda gereksiz yere ağırlaşmak zorunda değildir. Ancak ürün, stok, sipariş, ödeme, kargo, pazaryeri, analitik ve ERP verileri doğru modele oturur. Bu da gelecekteki bağlantıların daha az kırılmayla, daha düşük yeniden geliştirme maliyetiyle ve daha kontrollü operasyonla kurulmasını sağlar.

Webioo, e-ticaret projelerinde entegrasyon planını site yayına çıktıktan sonra eklenecek teknik detay olarak değil; ürün veri modeli, yönetim paneli, ödeme, kargo, ERP, pazaryeri ve ölçüm mimarisinin temel parçası olarak ele alır. Böylece site yalnızca bugün satış almaya değil, büyüdüğünde sistemlerle sağlıklı konuşmaya hazır olur.