API Entegrasyonu: Veri Sözleşmesi ve Hata Yönetimi

API entegrasyonu nedir? En basit hâliyle, iki farklı yazılımın belirlenmiş kurallar üzerinden veri alışverişi yapmasını sağlayan bağlantıdır. Örneğin e-ticaret sitenizde oluşan siparişin muhasebe programına iletilmesi, stok bilgisinin ERP’den mağazaya aktarılması veya CRM’deki müşteri bilgisinin destek ekranında görüntülenmesi API entegrasyonu ile kurgulanabilir.

Ancak başarılı bir entegrasyon sadece iki sistemi bağlamak değildir. Hangi verinin ne zaman taşınacağı, hangi sistemin ana kaynak olduğu, hata oluştuğunda ne yapılacağı ve sonuçların nasıl kontrol edileceği baştan tanımlanmalıdır.

API entegrasyonu işletmelerde hangi sorunları çözer?

Bir işletmede aynı bilginin farklı ekranlara tekrar tekrar girilmesi; yanlış veri, gecikme ve takip yükü doğurur. API entegrasyonu, uygun tasarlandığında bu tekrarları azaltmaya ve sistemler arasındaki veri tutarlılığını yönetmeye yardımcı olur.

• Sipariş akışı: E-ticaret siparişlerinin depo, kargo veya muhasebe sistemine aktarılması.
• Stok ve fiyat güncellemesi: Merkezi stok veya fiyat bilgisinin satış kanallarına gönderilmesi.
• Müşteri görünümü: CRM, destek ve satış ekiplerinin aynı müşteri kaydına daha tutarlı biçimde erişmesi.
• Durum bildirimleri: Ödeme, sipariş, teslimat ya da onay durumunda ilgili sisteme bilgi iletilmesi.
• Raporlama hazırlığı: Dağınık uygulamalardaki verilerin raporlama için anlamlı biçimde bir araya getirilmesi.

Örneğin bir B2B satış ekibi, müşteriye özel fiyatı ERP’de; siparişi e-ticaret panelinde; tahsilat durumunu ise muhasebe yazılımında tutabilir. Buradaki hedef her veriyi her sisteme kopyalamak değil, ekibin ihtiyaç duyduğu veriyi doğru zamanda doğru ekrana ulaştırmaktır.

API, webhook, dosya aktarımı ve manuel süreç farkı

Her veri alışverişi ihtiyacı için API gerekli değildir. İşin sıklığı, veri hacmi, işlem kritiklik seviyesi ve teknik kapasite seçimi belirler.

Webhook ile API sıkça karıştırılır. API’de uygulamanız gerektiğinde diğer sisteme “siparişin durumu nedir?” diye sorabilir. Webhook’ta ise diğer sistem “sipariş durumu değişti” bilgisini size gönderir. Birçok projede bu iki yaklaşım birlikte kullanılır.

Entegrasyona uygun süreçleri belirleme

İlk adım, tüm süreçleri aynı anda otomatikleştirmeye çalışmak değildir. Önce veri hatası, bekleme veya yoğun takip yaratan süreçleri görünür hâle getirin. Bunun için her süreci aşağıdaki sorularla değerlendirin:

1. Bu işlem neyle başlıyor: yeni sipariş, ödeme, form, onay veya zamanlanmış görev mi?
2. Veri hangi sistemden çıkıyor ve hangi sisteme ulaşıyor?
3. İşlemde insan onayı ya da yorum gerektiren bir karar var mı?
4. Veri ne kadar güncel olmalı: anlık, kısa aralıklarla veya günlük mü?
5. Hatalı ya da eksik veri iş akışını nasıl etkiler?
6. İşlem tamamlandığında hangi ekip bilgilendirilmeli?

Örneğin “sipariş geldiğinde kargo kaydı aç” süreci çoğunlukla entegrasyona uygundur; çünkü tetikleyicisi, alanları ve beklenen sonucu nettir. Buna karşılık “yüksek tutarlı siparişlerde özel indirim değerlendirmesi yap” süreci insan kararı içerdiğinden tamamen otomatik olmamalıdır. Bu tür süreçlerde sistem, bilgiyi hazırlayıp ilgili kişiye görev veya onay gönderebilir.

Onay içeren süreçleri ayrı tasarlamak için iş akışı otomasyonu ve onay süreçleri rehberinden yararlanabilirsiniz.

Veri alanları ve veri sahipliği kontrol listesi

Entegrasyon projelerindeki yaygın sorunlardan biri, iki sistemde aynı alanın farklı anlam taşımasıdır. “Müşteri adı”, “ürün kodu”, “sipariş durumu” veya “stok” gibi görünen alanlar; biçim, kapsam ve güncelleme kuralı bakımından farklı olabilir.

Her veri alanı için netleştirilmesi gerekenler

• Alan adı ve anlamı: Örneğin “stok” satılabilir miktar mı, fiziksel depo miktarı mı?
• Veri türü: Metin, sayı, tarih, para birimi, liste veya dosya mı?
• Zorunluluk: Alan boş kalabilir mi? Boşsa işlem durmalı mı?
• Benzersiz kimlik: Ürün kodu, müşteri ID’si veya sipariş numarası hangi sistemde üretilir?
• Dönüşüm kuralı: Bir sistemdeki durum değeri diğer sistemde hangi değere karşılık gelir?
• Veri sahibi: Alanın doğru kaynağı hangi sistemdir?
• Güncelleme yönü: Veri tek yönlü mü, çift yönlü mü ilerler?

Veri sahipliği özellikle önemlidir. Örneğin ürün açıklamalarını PIM’de, stok miktarını ERP’de, web sitesi yayına alma bilgisini e-ticaret panelinde yönetiyorsanız; her alan için tek bir “asıl kaynak” belirleyin. Aksi durumda iki sistem birbirinin verisini ezebilir.

Pratik kural: Çift yönlü veri aktarımını varsayılan seçenek kabul etmeyin. Önce tek yönlü akışla işi çözüp çözemeyeceğinizi değerlendirin.

Hata yönetimi, kayıt tutma ve test senaryoları

Entegrasyonun değeri, normal koşullarda çalışmasından çok beklenmeyen koşullarda kontrollü davranmasında ortaya çıkar. Bağlantı kesilebilir, dış servis geçici olarak yanıt vermeyebilir veya kaynak sistem eksik veri gönderebilir. Bu nedenle hata yönetimi geliştirme sonrasına bırakılmamalıdır.

Planınıza eklemeniz gereken kontroller

• İşlem kaydı: İstek zamanı, ilgili kayıt kimliği, sonuç durumu ve hata mesajı kaydedilmelidir.
• Tekrarlı işlem koruması: Aynı webhook veya istek tekrar geldiğinde ikinci kez sipariş, fatura ya da kargo kaydı oluşmamalıdır.
• Yeniden deneme kuralı: Geçici hatalarda işlem kontrollü biçimde tekrar denenmeli; kalıcı hatalar ekip ekranına düşmelidir.
• Uyarı akışı: Kritik hatalarda hangi ekip üyesinin, hangi kanaldan bilgilendirileceği tanımlanmalıdır.
• Geri alma yaklaşımı: Birden fazla sistemde işlem yarıda kalırsa nasıl düzeltileceği belirlenmelidir.
• Yetki ve erişim: API anahtarları, kullanıcı rolleri ve erişim kayıtları güvenlik gereksinimlerine göre yönetilmelidir.

Test aşamasında yalnızca “başarılı sipariş” senaryosunu denemek yeterli değildir. Eksik adresli sipariş, aynı siparişin iki kez gelmesi, geçersiz ürün kodu, bağlantı zaman aşımı, iptal edilen ödeme ve kısmi iade gibi durumları da test listesine ekleyin. Üretim ortamına geçmeden önce örnek kayıtlarla mutabakat yapmak, veri farklılıklarını daha erken yakalamanızı sağlar.

E-ticaret altyapısındaki ürün, kategori ve görsel verilerinin tutarlılığı için ürün görsellerini optimize etme rehberindeki içerik ve medya yönetimi notları da tamamlayıcı olabilir.

Yazılım sağlayıcısına sorulacak teknik sorular

Bir sağlayıcının “entegrasyon desteği var” demesi, ihtiyacınız olan veri akışının hazır olduğu anlamına gelmeyebilir. Görüşme sırasında aşağıdaki sorular, kapsamı daha somut hâle getirir:

1. API dokümantasyonu güncel mi ve test ortamı sunuluyor mu?
2. Hangi kaynaklara erişilebilir: ürün, stok, fiyat, sipariş, müşteri, ödeme veya iade?
3. Veri okuma ve veri yazma yetkileri ayrı mı?
4. Webhook olayları hangileri ve imza doğrulaması nasıl yapılıyor?
5. İstek sınırı, sayfalama ve toplu veri alma kuralları nedir?
6. Hata kodları ile hata mesajları dokümante edilmiş mi?
7. API sürüm değişiklikleri nasıl duyuruluyor?
8. Kimlik doğrulama yöntemi nedir ve erişim anahtarları nasıl yenileniyor?
9. İşlem kayıtlarına veya başarısız aktarım listesine panelden erişilebilir mi?
10. Veri silme, güncelleme ve eşleştirme işlemlerinde hangi kısıtlar bulunuyor?

Bu yanıtları yalnız teknik ekibin değil, sürecin sahibi olan operasyon, satış ve finans ekiplerinin de değerlendirmesi gerekir.

Uygulanabilir entegrasyon planı şablonu

Entegrasyon planınızı kısa ama karar verilebilir bir doküman olarak hazırlayın. Aşağıdaki yapı, küçük bir bağlantı için de çok sistemli bir proje için de başlangıç noktası olabilir:

1. İş hedefi: Hangi operasyon sorununu çözmek istiyorsunuz?
2. Kapsam: İlk aşamada hangi sistemler, kayıtlar ve işlem türleri yer alacak?
3. Akış şeması: Tetikleyici, kaynak sistem, hedef sistem ve sonuç adımı nedir?
4. Veri sözlüğü: Alan eşleşmeleri, zorunlu alanlar ve dönüşüm kuralları nelerdir?
5. Sahiplik: Her verinin ana kaynağı ve süreç sorumlusu kimdir?
6. Teknik yöntem: API, webhook, dosya aktarımı veya manuel onay hangi noktada kullanılacak?
7. Hata planı: Tekrar deneme, uyarı, manuel müdahale ve kayıt saklama yaklaşımı nedir?
8. Test ve kabul: Başarılı, hatalı ve istisnai senaryolar kim tarafından onaylanacak?

API bağlantısında alanın bulunması yeterli değildir; boş değer ile bilinmeyen değer aynı anlama gelmeyebilir. Veri sözleşmesinde bu ayrımı yazın. Kaynak sistemde silinen bir kaydın hedefte silineceği, pasifleştirileceği veya korunacağı açıkça kararlaştırılmalıdır.