Web Yazılım Entegrasyonları Nasıl Planlanır? API, ERP, CRM ve Ödeme Sistemleri

Web yazılım entegrasyonu, iki sistem arasında yalnızca teknik bağlantı açmak değildir. Hangi verinin hangi sistemden çıktığı, ne zaman ve hangi kuralla aktarıldığı, hedef sistemin nasıl yanıt verdiği, hata halinde ne olacağı ve sonuçtan kimin sorumlu olduğu birlikte tanımlanmalıdır.

“ERP entegrasyonu yapılacak”, “CRM’e bağlanacak” veya “ödeme API’si eklenecek” ifadeleri teklif ve geliştirme kapsamı için yetersizdir. Uygulanabilir bir entegrasyon planı en az şu soruları cevaplar:

• Kaynak ve hedef sistem hangileri?
• Her veri alanının asıl sahibi hangi sistem?
• Akışı ne tetikler ve hangi yönde çalışır?
• İşlem eşzamanlı mı, zamanlanmış mı, olay tabanlı mı?
• Kimlik doğrulama ve yetki nasıl yönetilir?
• Başarı, bekleme, kısmi başarı ve hata nasıl temsil edilir?
• Aynı işlem iki kez gelirse ne olur?
• Veri tutarsızlığı nasıl fark edilir ve düzeltilir?
• Test, izleme, ücret ve bakım sorumluluğu kimdedir?

Bu rehber, entegrasyonu on başlıklı bir kayıt ve sorumluluk matrisiyle planlar. Belirli bir ERP, CRM veya ödeme sağlayıcısının her projede aynı yetenekleri sunduğunu varsaymaz; kullanılacak ürünün güncel teknik ve ticari koşulları ayrıca doğrulanmalıdır.

1. Önce sistem bağlam haritasını çıkarın

Tek tek API uçlarından önce sistemlerin görevini ve sınırını gösterin. Basit bir bağlam haritasında şu öğeler bulunabilir:

• yeni web uygulaması,
• ERP veya muhasebe sistemi,
• CRM,
• ödeme sağlayıcısı,
• kargo/lojistik servisi,
• kimlik veya kurumsal giriş servisi,
• e-posta ve mesajlaşma servisi,
• analitik/veri ambarı,
• dosya veya belge servisi,
• entegrasyonu kullanan insan rolleri.

Her bağlantı için okun yönünü ve taşınan ana bilgiyi yazın. Örneğin “Portal → ERP: onaylı sipariş”, “ERP → Portal: stok ve sevk durumu”, “Portal → CRM: yeni uygun müşteri adayı”. Çift yönlü ok, iki ayrı davranışı gizleyebilir; mümkünse yönleri ayrı gösterin.

Sistem sahibi ve veri otoritesi

Her veri için “source of truth” olarak da adlandırılan asıl kayıt sistemini belirleyin. Ürün fiyatının ERP’de, iletişim izninin CRM’de, kullanıcı yetkisinin portalda tutulduğu bir yapıda aynı alanın farklı sistemlerde bağımsız değiştirilmesi çelişki yaratabilir.

Şunları kaydedin:

• veriyi kim oluşturur,
• hangi sistem asıl kaydı tutar,
• diğer sistemler kopyayı okuyabilir mi veya değiştirebilir mi,
• çelişki halinde hangi kayıt kazanır,
• değişiklik geçmişi nerede bulunur,
• veri silme veya düzeltme hangi sistemden başlar.

2. Entegrasyon envanteri oluşturun

Sistem haritasındaki her oku ayrı envanter satırına dönüştürün:

Envanter kapsamın tamamını görünür kılar. Aynı sistemle üç farklı veri akışı varsa bunları tek “ERP entegrasyonu” satırında toplamayın; tetikleyici, kritikliği ve hata davranışı farklı olabilir.

3. Her entegrasyonun iş sonucunu tanımlayın

Teknik yöntemden önce entegrasyonun hangi kullanıcı veya iş sonucunu desteklediğini yazın.

Zayıf tanım:

CRM API entegrasyonu yapılacak.

Daha açık tanım:

İletişim formunda gerekli izin ve uygunluk koşullarını karşılayan başvuru, CRM’de kaynak kampanya ve portal kayıt numarasıyla bir müşteri adayı oluşturmalı; aktarım başarısızsa kullanıcı formu tekrar göndermeye zorlanmadan operasyon ekibi hatayı görebilmelidir.

Bu ifade veri, başarı ve hata davranışını tartışılabilir hâle getirir. Entegrasyon çalışsa bile yanlış kullanıcıya, yanlış zamanda veya eksik veriyle sonuç üretmesi iş ihtiyacını karşılamaz.

4. Tetikleyici, zamanlama ve veri yönünü seçin

Eşzamanlı istek

Kullanıcı işlemi sırasında hedef sistemden hemen yanıt beklenir. Anlık fiyat doğrulama veya ödeme başlatma örnek olabilir. Hedef sistem yavaş veya erişilemezse kullanıcı deneyimi etkilenir; zaman aşımı ve bekleme durumu tasarlanmalıdır.

Asenkron/olay tabanlı akış

Uygulama olayı kaydeder, işlem daha sonra kuyruk veya webhook üzerinden tamamlanır. Kullanıcı uzun işlemi beklemez; ancak “alındı”, “işleniyor”, “tamamlandı” ve “başarısız” durumları yönetilmelidir.

Zamanlanmış toplu aktarım

Veri belirli aralıklarla dosya veya toplu API işlemiyle aktarılır. Anlık güncellik gerekmeyen rapor veya katalog senaryolarında uygun olabilir. Dosya bütünlüğü, tekrar işleme, kesilen aktarım ve mutabakat gereksinimleri yazılmalıdır.

Tek yöntem her akış için doğru değildir. Kullanıcının bekleyebileceği süre, veri güncelliği, işlem hacmi, dış servisin sınırları ve hata etkisi birlikte değerlendirilmelidir.

5. API sözleşmesini ve veri eşlemesini belgeleyin

API dokümanı yalnızca adres listesinden oluşmamalıdır. İstek/yanıt alanları, veri tipleri, zorunluluk, doğrulama, hata kodları, sayfalama, hız sınırı, sürüm ve örnekler görünür olmalıdır.

OpenAPI Specification, HTTP API’lerini programlama dilinden bağımsız biçimde tarif etmek ve insanların/araçların servis yeteneklerini kaynak koduna erişmeden anlamasını sağlamak için standart bir arayüz açıklaması sunar (OpenAPI Specification). OpenAPI kullanılması entegrasyonun doğru çalışacağını garanti etmez; sözleşmeyi, dokümantasyonu ve test araçlarını ortaklaştırmaya yardımcı olabilir.

Veri eşleme tablosu

Alan adından ziyade iş anlamını eşleyin. İki sistemde “status” adlı alan bulunması aynı durum modelini kullandıkları anlamına gelmez.

6. Kimlik doğrulama, yetkilendirme ve sırları planlayın

Entegrasyon hesabı mümkün olan en geniş yetkiyle açılmamalıdır. Her bağlantı için gereken kaynak ve işlemleri sınırlandırın.

Plan şunları kapsamalıdır:

• kimlik doğrulama yöntemi,
• servis hesabı veya uygulama kimliği sahibi,
• test ve canlı ortam için ayrı bilgiler,
• izin kapsamı ve en az yetki,
• anahtar/sertifika saklama yöntemi,
• yenileme ve iptal süreci,
• erişim kaydı,
• sağlayıcı veya ekip değişiminde devir,
• olay halinde erişimi kapatma yöntemi.

OWASP API Security Top 10; nesne, özellik ve işlev düzeyinde yetkilendirme, kimlik doğrulama, kaynak tüketimi, envanter ve üçüncü taraf API tüketimi gibi risk alanlarını ele alır (OWASP API Security Top 10). Güvenlik kontrolü yalnızca geçerli bir API anahtarı bulunmasına indirgenmemelidir; isteğin o kullanıcı, rol, kuruluş ve kayıt için yetkili olup olmadığı da doğrulanmalıdır.

Parola, API anahtarı ve gizli değerleri gereksinim dokümanına, görev açıklamasına veya düz metin tabloya koymayın. Belge yalnızca hangi sırrın, kim tarafından, hangi güvenli yöntemle yönetildiğini kaydetmelidir.

7. Hata, tekrar deneme ve yinelenen işlemi tasarlayın

Entegrasyonlar kesinti, zaman aşımı, geçersiz veri, hız sınırı ve kısmi başarı yaşayabilir. “Hata olursa tekrar dener” ifadesi şu soruları cevaplamaz:

• Hangi hatalar tekrar denenebilir?
• Kaç kez ve hangi aralıkla?
• İşlem kullanıcıya hangi durumda gösterilir?
• Aynı istek iki kez gelirse çift kayıt veya çift tahsilat oluşur mu?
• Sürekli başarısız kayıt nereye alınır?
• Kim uyarılır ve nasıl yeniden işler?

İdempotency ve işlem kimliği

İdempotency, aynı mantıksal işlemin güvenli biçimde yeniden gönderildiğinde istenmeyen ikinci sonuç üretmemesini sağlar. Uygulama; sipariş, ödeme başlatma veya kayıt oluşturma gibi kritik işlemlerde benzersiz işlem anahtarı ve iş kuralı kullanabilir. Sağlayıcının desteği ve davranışı kendi güncel belgelerinden doğrulanmalıdır.

Stripe’ın resmi API belgeleri, idempotency anahtarlarının bağlantı hatası sonrasında aynı isteği yanlışlıkla ikinci bir nesne veya işlem oluşturmadan yeniden denemek için kullanılabildiğini açıklar (Stripe idempotent requests). Bu, tüm servisler için otomatik geçerli bir davranış değildir; entegrasyon yapılan API’nin sözleşmesi esas alınmalıdır.

Webhook tekrarları

Webhook göndericisi aynı olayı birden fazla kez iletebilir veya olaylar beklenen sırada gelmeyebilir. Olay kimliği, işlenen kayıt, imza doğrulaması, zaman bilgisi ve tekrar davranışı planlanmalıdır. Stripe webhook rehberi, yinelenen olayların tanınmasını, imzanın doğrulanmasını ve uzun işlemlerden önce hızlı başarılı yanıt verilmesini önerir (Stripe webhooks). Bu örnek ödeme entegrasyonunda kontrol edilmesi gereken davranışı gösterir; başka sağlayıcının kuralları farklı olabilir.

8. Mutabakat ve veri tutarlılığını planlayın

Başarılı HTTP yanıtı, bütün iş sürecinin doğru tamamlandığını her zaman kanıtlamaz. Portal siparişi göndermiş fakat ERP sonraki aşamada reddetmiş olabilir; ödeme alınmış fakat portal sonucu kaydedememiş olabilir.

Mutabakat için belirleyin:

• iki sistemde ortak işlem kimliği,
• karşılaştırılacak alan ve durumlar,
• mutabakat sıklığı,
• farkların raporu,
• otomatik düzeltilebilen durumlar,
• insan incelemesi gereken durumlar,
• düzeltme yetkisi ve kayıt geçmişi,
• finansal veya kritik işlemlerde onay sahibi.

Kullanıcıya “tamamlandı” mesajı gösterilecek nokta, teknik isteğin gönderildiği an değil, iş sonucunun hangi aşamada kesinleştiğine göre seçilmelidir.

9. İzleme, günlük ve uyarı gereksinimlerini yazın

Entegrasyon hatasını yalnızca müşteri bildirdiğinde fark etmek işletilebilir bir model değildir. Her akış için gözlemlenebilir sinyaller tanımlayın:

• toplam ve başarılı işlem sayısı,
• hata türü ve oranı,
• yanıt süresi ve zaman aşımı,
• kuyrukta bekleyen iş,
• son başarılı senkronizasyon zamanı,
• tekrar deneme sayısı,
• mutabakat farkı,
• üçüncü taraf kullanım kotası,
• sertifika/anahtar veya sürüm bitiş tarihi.

Günlüklere gizli değer, tam kart bilgisi veya gereksiz kişisel veri yazılmamalıdır. İşlem kimliği ve sınırlı teknik bağlam, sorun araştırması için kullanılabilir. Hangi uyarının kime, hangi kanaldan ve hangi çalışma saatinde gönderileceği belirlenmelidir.

10. Test, ücret, sürüm ve sorumluluğu tamamlayın

Test kapsamı

• test/sandbox hesabı ve sahibi,
• gerçekçi fakat güvenli örnek veri,
• başarılı senaryo,
• doğrulama ve yetki hataları,
• zaman aşımı ve kesinti,
• hız sınırı,
• yinelenen istek/olay,
• kısmi başarı,
• mutabakat ve yeniden işleme,
• canlıya geçiş öncesi uçtan uca kabul.

Sandbox davranışı canlı ortamla tamamen aynı olmayabilir. Canlıya özgü limit, izin, alan adı, sertifika ve onay gereksinimleri ayrıca doğrulanmalıdır.

Ücret ve kota

• kurulum/lisans ücreti,
• aylık veya yıllık abonelik,
• işlem, mesaj, kullanıcı, çağrı veya veri hacmi bedeli,
• ücretsiz/ücretli kota,
• kur veya vergi etkisi,
• aşım davranışı,
• fiyat değişikliği ve yenileme,
• hesabın müşteri mi sağlayıcı adına mı açılacağı.

Bu kalemler web yazılım geliştirme teklifinden ayrı veya dahil olabilir; sözleşmede açıkça belirtilmelidir.

Sürüm ve değişiklik

• kullanılan API sürümü,
• değişiklik duyuru kanalı,
• eski sürümün kapanış tarihi,
• uyumluluk testi sahibi,
• üçüncü taraf değişikliğinin bakım mı yeni geliştirme mi sayılacağı,
• acil değişiklik ve geri dönüş süreci.

Sorumluluk matrisi

Gerçek sorumluluklar sözleşme ve kullanılan hizmete göre değişir. “Entegrasyonu ajans yapacak” ifadesi üçüncü tarafın erişim, servis devamlılığı ve veri doğruluğu sorumluluğunu otomatik olarak ajansa devretmez.

ERP, CRM ve ödeme entegrasyonlarında farklı sorular

ERP entegrasyonu

• Ürün, stok, fiyat, müşteri ve sipariş için asıl sistem hangisi?
• Fiyat ve stok ne kadar güncel olmalı?
• Şube/depo/para birimi/vergi eşlemeleri nasıl yapılacak?
• Sipariş ERP’de reddedilirse portal durumu ne olacak?
• Gece işlemleri veya bakım penceresi var mı?
• Veri taşıma ve mutabakat kimin sorumluluğunda?

CRM entegrasyonu

• Kayıt hangi koşulda müşteri adayı veya kişi oluşturur?
• Yinelenen kişiler nasıl eşleştirilir?
• Kaynak, kampanya ve izin bilgileri nasıl korunur?
• Satış aşaması hangi sistemde değişir?
• CRM’den portala geri dönen sonuç var mı?
• Silme/düzeltme işlemi diğer sisteme nasıl yansır?

Ödeme entegrasyonu

• Ödeme sayfası sağlayıcıda mı, gömülü mü, uygulama içinde mi?
• Kart verisine hangi sistemler dokunuyor?
• Başlatma, yönlendirme, doğrulama ve sonuç akışı nedir?
• İptal, iade, kısmi iade ve uyuşmazlık nasıl yönetilir?
• Webhook imzası, olay tekrarı ve sırasız olaylar nasıl ele alınır?
• Tahsilat ile sipariş durumu nasıl mutabık kalır?
• Test ve canlı hesapların sahibi kimdir?

Ödeme mimarisinin kapsam ve uygunluk yükümlülüklerine etkisi olabilir. PCI Security Standards Council, ödeme sayfası öğelerinin kaynağına göre farklı uygunluk koşulları bulunduğunu açıklar (PCI SSC e-commerce FAQ). Projenin gerçek PCI DSS kapsamı, ödeme sağlayıcısı ve gerektiğinde yetkili uzmanlarla belirlenmelidir; bu makale uygunluk değerlendirmesi değildir.

Kopyalanabilir entegrasyon gereksinim kartı

Canlıya geçiş kontrol listesi

• Test ve canlı hesaplar ayrıldı mı?
• Canlı anahtarlar güvenli şekilde tanımlandı mı?
• En az yetki kontrol edildi mi?
• Alan ve durum eşlemeleri onaylandı mı?
• Başarı, hata, zaman aşımı ve tekrar senaryoları geçti mi?
• Webhook imzası ve yinelenen olay davranışı doğrulandı mı?
• Ortak işlem kimliği kaydediliyor mu?
• Mutabakat raporu veya yöntemi hazır mı?
• İzleme ve uyarılar doğru kişiye ulaşıyor mu?
• Kota ve ücret uyarıları tanımlı mı?
• Üçüncü taraf destek kanalı kayıtlı mı?
• Sürüm ve sertifika bitişleri izleniyor mu?
• Geri dönüş veya entegrasyonu güvenli durdurma yöntemi var mı?
• Operasyon ekibi başarısız işlemi nasıl yöneteceğini biliyor mu?
• Hesap, doküman ve sorumluluklar teslim kaydında mı?

Entegrasyon kararlarını web yazılımın genel proje süreciyle birlikte ele alın. Her akışı gereksinim dokümanında test edilebilir biçimde tanımlayın, ilk sürüme girecek bağlantıları MVP kapsamıyla sınırlandırın, maliyet etkisini bütçe rehberiyle ve canlı sorumluluğunu güvenlik ve bakım planıyla doğrulayın.

Sonuç

Başarılı entegrasyon yalnızca iki sistemin veri alışverişi yapması değildir. Doğru veri, doğru zamanda, yetkili akışla hareket etmeli; hata ve tekrar durumları kontrol edilmeli; sistemler sonuç üzerinde mutabık kalmalı ve operasyon ekibi sorunu görebilmelidir.

Önce sistem haritası ve veri otoritesini belirleyin. Her veri akışını ayrı envanter satırına dönüştürün; tetikleyici, sözleşme, yetki, hata, idempotency, mutabakat, izleme, test, ücret, sürüm ve sorumlulukları aynı kayıtta toplayın. Böylece “API entegrasyonu dahil” ifadesi, tekliften canlı işletime kadar doğrulanabilir bir kapsama dönüşür.